azzist-deploy

azzist-deploy

Build, ship, and run the container with hard isolation. Read config from azzist.yaml (public) and azzist.local.yaml (secrets). Let <name> = project.name.

Isolation guardrails (non-negotiable)

• Only create/modify resources prefixed azzist_<name>: network azzist_<name>, container azzist_<name>_app (and _db, _cache if enabled).
• NEVER stop/rm/restart/reconfigure containers, networks, or volumes you did not create.
• NEVER edit existing daemon, proxy, or compose configs. If something unexpected exists, stop and ask the user — do not work around it destructively.

Transfer strategy (read deploy.transfer from azzist.yaml)

• git (default): the server pulls the repo and builds the image remotely. Preferred — no large image upload, reproducible, easy redeploys (git pull + rebuild).
• image: build locally, smoke-test, then docker save | docker load over SSH. Use when the server cannot reach the git host or the repo is not pushed.

deploy.repo + deploy.branch (azzist.yaml) define the source for git mode. Server-side git credentials are described in git.auth (azzist.local.yaml): deploy_key (a read-only key already on the server), ssh_agent (forward your local agent), or token (HTTPS PAT).

Steps

1. Prepare SSH. Read the server entry (deploy.server -> servers.<server> in local). Export AZZIST_SSH_AUTH/AZZIST_SSH_HOST/AZZIST_SSH_USER/AZZIST_SSH_ALIAS/AZZIST_SSH_KEY as needed and source ${CLAUDE_PLUGIN_ROOT}/scripts/ssh-helpers.sh. For ssh_agent git auth, connect with agent forwarding (ssh -A).

1a. Survey the server BEFORE doing anything. Always inspect what's already on the box so we don't collide or duplicate: - Reverse proxy present? bash ${CLAUDE_PLUGIN_ROOT}/scripts/detect-proxy.sh -> traefik | nginx | none. If one exists, REUSE it later in azzist-server (do not install another). If none, ASK the user before installing nginx — never silently add a new proxy. - Port conflicts. Whether deploy.port: auto or a fixed number, always check the target port is actually free on the server before binding. For auto, scan and pick a free one (see step 6). For a fixed port, if it is already in use, STOP and ask the user whether to pick another or evict (we never evict). Use azzist_ssh 'ss -tlnH | awk "{print \$4}" | grep -E ":<port>\$"'. - Record both findings; they drive steps 6 (port) and the handoff to azzist-server (proxy).

2. PREFLIGHT — verify the server can pull the (private) repo. Do this FIRST, before any build, so failures are cheap. Skip only in image mode.

   azzist_ssh 'git ls-remote <deploy.repo> >/dev/null 2>&1 && echo REPO_OK || echo REPO_FAIL'
   

   • For token (HTTPS): test with the credentialed URL, never echoing the token: azzist_ssh 'git ls-remote https://x-access-token:<token>@github.com/<owner>/<repo>.git >/dev/null 2>&1 && echo REPO_OK || echo REPO_FAIL'
   • If REPO_FAIL: STOP and tell the user exactly how to grant access — add a read-only deploy key to the repo for the server's SSH key (azzist_ssh 'cat ~/.ssh/id_*.pub'), or provide a PAT, or use ssh_agent forwarding. Do not proceed until preflight returns REPO_OK.
   • Also confirm git exists on the server: azzist_ssh 'command -v git' (install if missing).

3. Ensure remote Docker. azzist_ssh 'command -v docker'. If missing, install Docker via the official convenience script (curl -fsSL https://get.docker.com | sh) — this adds Docker only; it does not alter existing services. Confirm with the user before installing.

3a. Validate the Dockerfile before any build. A broken Dockerfile wastes minutes of server time — catch it locally first. - Confirm Dockerfile exists at the build context the build command will use. - Lint with docker build --check . if available (BuildKit), else a local docker build --target <stage> . dry-run on the cheap stages. - Required contract: image must EXPOSE a port AND respond on /healthz (liveness) and /readyz (readiness). If the project's framework doesn't have these, add minimal handlers before deploy (Nuxt: a Nitro route handler; Go: a /healthz mux entry). - Locally run the built image and probe both endpoints: docker run -d --rm --name azzist_<name>_validate -p 13000:3000 azzist_<name>_app:latest curl -fsS http://localhost:13000/healthz && curl -fsS http://localhost:13000/readyz docker stop azzist_<name>_validate If either probe fails, STOP — do not ship a container that can't report health.

4. Build + ship (branch on transfer mode).

   git mode: build on the server from a fresh checkout.

   azzist_ssh 'mkdir -p ~/azzist/<name>'
   # clone once, then pull on redeploys:
   azzist_ssh 'test -d ~/azzist/<name>/.git \
     && git -C ~/azzist/<name> fetch --depth 1 origin <branch> && git -C ~/azzist/<name> reset --hard origin/<branch> \
     || git clone --depth 1 -b <branch> <deploy.repo> ~/azzist/<name>'
   azzist_ssh 'cd ~/azzist/<name> && docker build -t azzist_<name>_app:latest .'
   

   (token auth: use the credentialed HTTPS URL for clone/fetch; never print the token.)

   image mode: build + smoke-test locally, then transfer the image.

   docker build -t azzist_<name>_app:latest .
   docker run -d --rm --name azzist_<name>_smoke -p 3000:3000 azzist_<name>_app:latest
   curl -fsS http://localhost:3000 >/dev/null && docker stop azzist_<name>_smoke
   docker save azzist_<name>_app:latest | gzip | azzist_ssh 'gunzip | docker load'
   

5. Isolated network. Create only if absent: azzist_ssh 'docker network inspect azzist_<name> >/dev/null 2>&1 || docker network create azzist_<name>'

6. Resolve port. If deploy.port: auto, source scripts/ssh-helpers.sh then bash ${CLAUDE_PLUGIN_ROOT}/scripts/free-port.sh to get a free host port. Else use the fixed number. Record it as <port> for the server step.

7. Run container. Replace any prior instance of OUR app only:

   azzist_ssh 'docker rm -f azzist_<name>_app 2>/dev/null || true'
   azzist_ssh 'docker run -d --name azzist_<name>_app \
     --network azzist_<name> \
     -p 127.0.0.1:<port>:3000 \
     --restart unless-stopped \
     azzist_<name>_app:latest'
   

   Binding to 127.0.0.1:<port> keeps the app private until the proxy fronts it.

8. Verify on server. Probe BOTH endpoints (not just root) to confirm the container is actually serving and ready:

   azzist_ssh 'curl -fsS http://127.0.0.1:<port>/healthz >/dev/null && echo health_ok'
   azzist_ssh 'curl -fsS http://127.0.0.1:<port>/readyz  >/dev/null && echo ready_ok'
   

   Both must pass before handoff.

8a. Pre-check the target domain. Before handing off to azzist-server, see whether <domain> already resolves and where it points: dig +short <domain> (locally) and curl -sSI http://<domain> (best-effort). - If it already resolves to a DIFFERENT IP than this server, WARN the user — the Cloudflare upsert in azzist-server will replace it. Confirm before proceeding. - If it resolves to this server already, note it — we just need to ensure proxy + TLS. - If it doesn't resolve yet, fine — azzist-server will create the record.

9. Hand <port>, the running container, the detected proxy (from step 1a), and the domain pre-check result to azzist-server for proxy + DNS + TLS + final reachability.

Optional: database / cache (if enabled in azzist.yaml)

• database: postgres -> run postgres:16-alpine as azzist_<name>_db on network azzist_<name> with a named volume azzist_<name>_pgdata. Not published to host.
• cache: redis -> run redis:7-alpine as azzist_<name>_cache on the same network.
• App reaches them by container name over the private network.

Output

Report the image built, smoke-test result, the chosen <port>, and remote verification.