dev_arc_aws/deploy/README.md

# ArchNest — Build & Deploy (Forgejo Actions → registry → racknerd2)

This pipeline builds the Docker images in Forgejo Actions, pushes them to the
Forgejo container registry, and deploys them to **racknerd2** (validation host)
over the NetBird mesh. racknerd2 only pulls and runs — it never builds (1.9 GiB
RAM).

```
push to main ─► [build.yml]
                  job: build   ─► build + push images ─► registry.snsnetlabs.com/sam/{archnest,archnest-backend}
                  job: deploy  ─► (needs build) ssh racknerd2 ─► compose pull + up -d (this build's SHA) ─► /api/health
                                                                      │
        manual dispatch (any tag / rollback) ─► [deploy.yml] ssh racknerd2 ─► compose pull && up -d
```

Every push to `main` auto-builds and auto-deploys to racknerd2. `deploy.yml`
stays as a manual `workflow_dispatch` for deploying/rolling back to an arbitrary
tag without rebuilding.

## Images

| Image | From | Tags |
|-------|------|------|
| `registry.snsnetlabs.com/sam/archnest` | root `Dockerfile` (React build → nginx) | `latest`, `<commit-sha>` |
| `registry.snsnetlabs.com/sam/archnest-backend` | `backend/Dockerfile` (Fastify) | `latest`, `<commit-sha>` |

`registry.snsnetlabs.com` is the **unproxied (DNS-only)** registry host, so large
layers bypass Cloudflare's ~100 MB request-body cap. Pushed images appear at
`https://forgejo.snsnetlabs.com/sam/-/packages` (web UI, Cloudflare Access SSO).

## One-time setup

### 1. Forgejo Actions secrets (repo or org settings → Actions → Secrets)
- `FORGEJO_REGISTRY_TOKEN` — Forgejo personal access token for `sam` with
  **package** scope (NOT the account password). Used by `build.yml` to log in
  and push.
- `RACKNERD2_SSH_KEY` — private SSH key authorized for `root@racknerd2`
  (mesh IP `100.96.217.250`). Used by `deploy.yml`.

### 2. Runner (forgejo-runner host) — allow Docker builds
The runner runs jobs inside containers and by default has **no Docker access**.
Enable socket auto-mounting so the `build` job can build images. Create
`/opt/config.yaml` (or edit the existing runner config) with at least:

```yaml
container:
  docker_host: "automount"   # mounts /var/run/docker.sock into job containers
```

Generate a full example with `forgejo-runner generate-config > /opt/config.yaml`,
set `docker_host: "automount"`, point the service at it
(`ExecStart=/usr/local/bin/forgejo-runner daemon -c /opt/config.yaml`), then
`systemctl daemon-reload && systemctl restart forgejo-runner`.

### 3. racknerd2 — prepare the deploy host
Docker Engine + compose plugin are already installed. Then:

```bash
mkdir -p /opt/archnest
# copy deploy/docker-compose.yml from this repo to /opt/archnest/docker-compose.yml
# create /opt/archnest/.env from deploy/.env.example and fill in the secrets:
#   ARCHNEST_JWT_SECRET   = openssl rand -hex 32
#   ARCHNEST_SECRET_KEY   = openssl rand -hex 32
#   ARCHNEST_GUAC_CRYPT_KEY = openssl rand -base64 24 | cut -c1-32
docker login registry.snsnetlabs.com   # user: sam, password: the package token
```

Ports are bound to the **mesh IP only** (`100.96.217.250`) — Docker bypasses
ufw, so this is what keeps the app off the public interface. Validate at
`http://100.96.217.250:8080`.

## Running it

- **Automatic**: push to `main` → `build.yml` builds + pushes both images, then
  its `deploy` job (needs `build`) pulls this commit's SHA onto racknerd2,
  restarts the stack, and health-checks `/api/health`. Fully hands-off.
- **Manual build**: run **Build & Push Images** from the Actions tab (also
  triggers the auto-deploy job).
- **Manual deploy / rollback**: run **Deploy to racknerd2**, entering any tag
  (`latest` or a specific commit SHA) to deploy without rebuilding.

## Notes / ceilings

- Auto-deploy targets racknerd2 (the validation host) on every push to `main`,
  pinned to the built commit's SHA. If you later add a prod host, gate
  prod deploys behind a manual approval or a tag/release trigger rather than
  every push.
- Single-arch (amd64) only — both the runner host and racknerd2 are amd64, so
  no buildx/multi-platform is needed.