# Carr Garage — new service playbook You already unlocked this bootstrap. Use the JSON fields in this payload (`host`, `integrations`, `homepage`). Do not ask the owner to paste settings forms. **Hairpin NAT:** from the garage LAN, `*.carrgarage.com` often fails. Call APIs at `integrations.*.lan_url` (or `http://:`). Public URLs are for browsers off-LAN. **Protected names (never create/overwrite):** www, coolify, git, npm, auth, and the apex domain. **Secrets:** do not print handshake keys, tokens, or passwords in chat or logs. --- ## 0) Homepage (this garage) - Public: `https://carrgarage.com` - After NPM publish, a tile appears on the homepage automatically. You do not edit homepage HTML for new apps. - Publish HTTPS via this garage (preferred) so you do not talk to NPM by hand: POST https://carrgarage.com/api/agent/publish?key= Content-Type: application/json {"subdomain":"","port":} Same handshake as context: query `?key=` or header `X-Handshake-Key`. ## 1) Gitea (source) - UI: `integrations.gitea.url` · API from this host: `integrations.gitea.lan_url` - User: `integrations.gitea.username` - Auth header: `Authorization: token ` - Create repo: POST /api/v1/user/repos {"name":"","private":true,"auto_init":false,"default_branch":"main"} - Clone/push: HTTPS `http://:@:3001//.git` or SSH `ssh://git@://.git` - Coolify must pull from the **LAN** git URL, not the public hostname. ## 2) Coolify (build + run) - UI: `integrations.coolify.url` · API: `integrations.coolify.api_base` (LAN) - Auth header (Coolify's API): `Authorization: Bearer ` - Use existing `project_uuid`, `server_uuid`, `environment_name` - Create an app that clones the Gitea repo (LAN URL). Nixpacks/Node unless it needs Docker. - **Host port is required** for public URLs. Map `HOST:CONTAINER` (e.g. `3016:3000`). Free host ports are usually 3002–3099; skip ports already in NPM. - Set env in Coolify, never commit secrets. - Deploy, wait until listening on the host port. ## 3) Public URL + TLS - Preferred: `POST https://carrgarage.com/api/agent/publish?key=...` as in step 0. - Pattern: `https://.carrgarage.com` → `http://:` - Fallback NPM API: `integrations.npm.lan_url` + email/password from the payload (login `POST /api/tokens` with `{"identity":email,"secret":password}`, then create proxy host + Let's Encrypt). - Websocket apps need websocket upgrade (the garage publisher turns this on). ## 4) Authentik (SSO) Use Authentik whenever the app should not be open to the world. - UI: `integrations.authentik.url` · API: `integrations.authentik.lan_url` - Auth header (Authentik's API): `Authorization: Bearer ` - Flows and signing key UUIDs are in `integrations.authentik.flows` ### A) App has its own OIDC/OAuth login (preferred for real apps) 1. Create OAuth2 provider — `POST /api/v3/providers/oauth2/` - `authorization_flow` / `invalidation_flow` / `signing_key` from payload - `property_mappings`: openid, email, profile (and offline if needed) - `client_type`: confidential - `redirect_uris`: the app callback on `https://_{.carrgarage.com/...`
2. Create application — `POST /api/v3/core/applications/`
- `slug` = subdomain, `provider` = provider pk, launch URL = public HTTPS URL
3. Put `client_id` / `client_secret` / issuer
`https://auth.carrgarage.com/application/o//`
into Coolify env. Shared endpoints:
- authorize: https://auth.carrgarage.com/application/o/authorize/
- token + userinfo: use Authentik **LAN** (`:9000`) from the app container if hairpin breaks
4. Restrict to the owner's Authentik user/groups; do not enable public enrollment.

Existing apps (carr-home, Coolify, Gitea, Pulpit, ServerMaster, Shopping) already have providers — do not recreate those.

### B) App has no login of its own (admin UIs)

Put Authentik **proxy** in front via NPM (embedded outpost at `http://:9000/outpost.goauthentik.io`). Only do this if the owner wants the whole site gated; otherwise use (A).

## 5) Done when

- Repo is on Gitea under the configured user
- Coolify app is deployed with a host port
- `https://_{.carrgarage.com` serves HTTPS
- Authentik SSO is wired if the app is private
- Homepage shows the new tile}}

Journey to the Bathhouse