# Deploying on Cosmos

The stack is three containers on `homelab_network`, none with a host port:

| Container | Image target | Port | Reached as | Who can reach it |
| --- | --- | --- | --- | --- |
| `gk-content` | `content` | 4310 | `content.gregkilmer.com` (API and `/mcp`), `http://gk-content:4310` on homelab_network | Tailnet only |
| `gk-admin` | `admin` | 4320 | `admin.gregkilmer.com` | Tailnet only |
| `gk-site` | `site` | 4321 | `beta.gregkilmer.com` until cutover, then `gregkilmer.com` | Tailnet only until cutover, then public through Cloudflare |

The old site keeps serving gregkilmer.com until phase 8 (cutover).

Files in the repo:

- `Dockerfile`: one target per service, plus `check` (typecheck and every test). Node is pinned to `node:22.20.0-alpine`.
- `deploy/compose.yaml`: the stack. Containers run as the vault's owner, with a read-only root filesystem, no capabilities and `no-new-privileges`.
- `deploy/deploy.sh`: builds `check`, then the three images tagged with the commit, and restarts the stack. If the new containers aren't healthy within two minutes, it puts the last good tag back. Run it again on the same commit and it does nothing (`FORCE=1` rebuilds).
- `deploy/rollback.sh`: switches to the previous tag. Run it again to roll forward.
- `.gitea/workflows/deploy.yml`: runs `deploy.sh` on Cosmos for each new commit to master.

## On Cosmos

Everything lives in `/home/greg/homelab/gregkilmer`:

```
/home/greg/homelab/gregkilmer/
  compose.yaml      copied from deploy/compose.yaml by every deploy
  .env              GK_TAG, GK_PREVIOUS_TAG, VAULT_SITE, PUID, PGID
  content.env       content service secrets and sync settings
  admin.env         ADMIN_TOKEN
  site.env          site secrets: tokens, Turnstile, SMTP
  data/content/     content.db and submissions/ (backed up)
```

Kopia already covers `/home/greg`, so the `.env` files and `data/` are in the encrypted backups.

## First-time setup

1. **Folder and settings.** Run these from a checkout of the repo:

   ```sh
   mkdir -p /home/greg/homelab/gregkilmer/data/content
   cd /home/greg/homelab/gregkilmer
   cp <repo>/deploy/stack.env.example .env
   cp <repo>/services/content/.env.example content.env
   cp <repo>/deploy/admin.env.example admin.env
   cp <repo>/services/site/.env.example site.env
   chmod 600 .env *.env
   ```

   In `.env`, check that `PUID` and `PGID` match `id -u greg` and `id -g greg`, so the content service can write notes back into the vault.

2. **Tokens.** Make one per role with `openssl rand -hex 24`:
   - In `content.env`, set `CONTENT_TOKENS=reader:<r>,admin:<a>,intake:<i>,agent:<g>`.
   - In `admin.env`, set `ADMIN_TOKEN=<a>`.
   - In `site.env`, set `CONTENT_TOKEN=<r>` and `CONTENT_INTAKE_TOKEN=<i>`.
   - Give agents `<g>`.

   Leave `CONTENT_URL` out of `site.env`; compose sets it.

3. **The rest of the settings.** Fill in Healthchecks, the Discord webhook, Turnstile, SMTP and the sync logins. The list is in `/mnt/project-files/website/phase6/setup-on-cosmos.md` and in each `.env.example`.

4. **Gitea runner.** The workflow needs an `act_runner` on Cosmos with the label `cosmos` running in host mode (`cosmos:host`). It runs as a user in the `docker` group with write access to `/home/greg/homelab/gregkilmer`.
   - A runner with the Docker socket is root-equivalent. Register it for this repository only, not for the whole instance.

5. **Gitea mirror.** Mirror `github.com/Patiun/com.gregkilmer.www` into Gitea as a pull mirror and turn Actions on for it.
   - A pull mirror's sync may not raise a push event. The workflow therefore also runs every 15 minutes and deploys only when master has moved.
   - Check once that a new commit reaches Cosmos. If the schedule doesn't fire on a mirror either, run the workflow by hand from the Actions tab.

6. **First deploy.** Run it from the Actions tab, or by hand from a checkout: `./deploy/deploy.sh`. Then check:
   - `docker compose -f /home/greg/homelab/gregkilmer/compose.yaml ps` shows three healthy containers.
   - `docker logs gk-content` says `Content service on 0.0.0.0:4310: N notes`.

7. **Nginx Proxy Manager.** Add a proxy host for each hostname. Force SSL on each. For `content`, add `proxy_buffering off;` under Advanced, because MCP streams its responses.

   | Host | Forward to | Access list |
   | --- | --- | --- |
   | `admin.gregkilmer.com` | `http://gk-admin:4320` | Tailnet only |
   | `content.gregkilmer.com` | `http://gk-content:4310` | Tailnet only |
   | `beta.gregkilmer.com` | `http://gk-site:4321` | Tailnet only |

   - DNS: an A record for each pointing at 100.99.111.16 (TTL 300), the same as other tailnet hosts.
   - Certificates: Let's Encrypt can't reach a tailnet-only host over HTTP, so use NPM's DNS challenge with your DNS provider. This is the same open item as the `*.patiun.com` certificate.
   - Agents already on homelab_network can skip NPM and use `http://gk-content:4310/mcp`.

8. **Turnstile.** Add `beta.gregkilmer.com` and `gregkilmer.com` to the widget's hostnames.

9. **Healthchecks.** Create these checks:
   - one for the content service's full scan (`HEALTHCHECK_URL`), every 5 minutes;
   - one per sync job you turn on (Archidekt, Suwayomi, Bambuddy and Homebox hourly; BGG and Kavita daily; covers every 15 minutes).

10. **Inventory note.** Copy `vault-kit/24.01_PersonalWebsite/GregKilmer.com stack.md` into the vault's `24.01_PersonalWebsite` folder, so `cosmos-inventory` stops listing the containers as undocumented.

## Backups

- `gk-content` carries `backup.dump=sqlite`. `cosmos-dump` finds `content.db` in its `/data` mount and copies it with `VACUUM INTO` before Kopia runs.
  - `content.db` holds note history, the review queue, saved inquiries and orders, and the sync cache.
  - The vault mount has no SQLite files, so nothing else is dumped.
- Form attachments are plain files in `data/content/submissions/`, which Kopia picks up with the rest of `/home/greg`.
- The plan called for a cache folder in `exclusions.conf`. None is needed: the sync cache and search index live inside `content.db` and are small.
- `gk-admin` and `gk-site` keep no data.

## Cutover (phase 8)

1. In NPM, point `gregkilmer.com` and `www.gregkilmer.com` at `http://gk-site:4321` with no access list, and retire the old `greg-profile-site` container.
2. Turn on Cloudflare's proxy for both records with SSL mode Full (strict). Cloudflare doesn't cache HTML by default, which is what the site needs: pages change within a minute of a note changing.
3. The site already trusts `X-Forwarded-Host` and `X-Forwarded-Proto` for gregkilmer.com and its subdomains (`security.allowedDomains` in `services/site/astro.config.mjs`), so form posts pass Astro's origin check behind the proxy. It reads the visitor's address from `CF-Connecting-IP` for the form rate limits.

## Day to day

- **Deploy:** merge to master on GitHub; Gitea mirrors it and the workflow deploys it.
- **Roll back:** `GK_STACK_DIR=/home/greg/homelab/gregkilmer ./deploy/rollback.sh` from a checkout, or set `GK_TAG` in `.env` to any image tag still on the host and run `docker compose up -d`.
- **Logs:** `docker logs gk-content`. Sync runs also appear on the admin page's Overview.
- **Restart one service:** `docker compose -f /home/greg/homelab/gregkilmer/compose.yaml restart gk-site`.