Set up a server

The procedure is deploy/setup-server.md. Follow it step by step and do not reinvent or shorten it: every command there is part of the security baseline. This skill adds how to run it safely as an agent and how to know each step is done. docs/deploy.md explains the moving parts.

Before you start

Collect from the user:

• the server's public IP address and SSH access as root or a sudo user (Ubuntu 22.04 or 24.04);
• the domain, with its DNS A record pointing at the server (needed before step 6);
• the GitHub repository (owner/name) the server will deploy from;
• the username for the first account in the app;
• whether Caddy runs on the host (variant A, recommended) or in a container (variant B).

Who runs the commands. If you have a shell on the server, run each step's commands yourself, one step at a time, and show the output. Otherwise give the user one step at a time and wait for its output before the next. Either way, never ask for passwords or private keys in the chat: the user types the account password into the CLI prompt, and private keys go straight into GitHub secrets.

Steps and their "done" checks

Step 3 needs extra care

A wrong firewall rule locks everyone out. Before any firewall change: arm the rollback timer exactly as the guide shows, and keep the current SSH session open. Confirm with the user that a second, fresh SSH login works before stopping the timer. If that login fails, do nothing: the timer turns the firewall off within five minutes.

Final checks (step 7 of the guide)

Report each result to the user:

1. curl -fsS https://<domain>/api/health answers "status":"ok", and git_sha equals sudo -u deploy git -C /srv/ai-tutor rev-parse HEAD on the server.
2. From outside the server, curl -m 5 http://<server-ip>:8000/ fails (timeout or connection refused).
3. curl -s --path-as-is https://<domain>/%2e%2e/VERSION returns the app's HTML start page, never the bare version string.
4. On the server, docker ps --format '{{.Names}}\t{{.Ports}}' shows no 0.0.0.0: or [::]:, except the proxy's 80 and 443 when Caddy runs in a container.

A failure in 2, 3 or 4 means the server is exposed: stop, tell the user, and fix it before anything else.

Never

• Never publish the app port without an address (8000:8000); keep 127.0.0.1:8000:8000, plus docker-compose.edge.yml only for a proxy in a container.
• Never give the server's deploy key write access to the repository.
• Never turn on REGISTRATION=open or COOKIE_SECURE=false on a public server unless the user asks for it and understands the consequence.
• Never stop the firewall rollback timer before a fresh SSH login has worked.
• Never change the server by hand without copying the change into the repository the same day; the next deploy resets the checkout.