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 / manual ─► [build.yml] build + push images ─► registry.snsnetlabs.com/sam/{archnest,archnest-backend}
                                                                      │
                                          manual dispatch ─► [deploy.yml] ssh racknerd2 ─► docker compose pull && up -d

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:

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:

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

1. Build: push to main, or run Build & Push Images manually (Actions tab → Run workflow).
2. Deploy: run Deploy to racknerd2 manually, entering the tag (latest or a specific commit SHA). It pulls, restarts, and health-checks /api/health.

Notes / ceilings

• ponytail: deploy is manual (workflow_dispatch), not auto-on-merge — this is a validation host, so deploys are deliberate. Wire build.yml → deploy.yml with needs: later if auto-deploy-to-validation is wanted.
• Single-arch (amd64) only — both the runner host and racknerd2 are amd64, so no buildx/multi-platform is needed.