Taking a Dockerised API Live: Every Step, and Everything That Broke(Part 4&5)

Taking a Dockerised API Live: Every Step, and Everything That Broke(Part 4&5)

Part 4 — What I would tell myself before starting

1. Suspect the step before the one that failed. Nearly every error here appeared downstream of its cause.
2. Read the status code, not just the body. A timeout is a firewall. "Refused" is nothing listening. 502 is a wrong upstream. An HTML 404 signed by your proxy means the proxy never forwarded. An empty body is not success — and curl -s hides all of it.
3. Know what is fixed at build time. Build arguments and copied files need a rebuild. Environment variables need up -d, not restart. A named volume keeps whatever owner it had the first time it was mounted.
4. Configuration on disk is not configuration in memory. nginx -T shows the file; only a reload applies it.
5. Profiles hide services from docker compose build.
6. "It works on my machine" usually works for a boring reason. My user ID happened to be 1000. My database happened to have hand-inserted rows. Port 8080 happened to be free. List the boring reasons before you deploy.
7. Development conveniences don't carry over. Bind mounts, override files and dependencies installed on the host are exactly what production doesn't have.
8. Shell redirection happens before the command runs.
9. A health check must touch what it claims to check.
10. Generate secrets on the server. Never copy a development .env, and never paste real secrets into screenshots or articles.
11. Every value you repeat will drift. One port number broke three things in three different files. Define it once.

Part 5 — Before you share the URL

• Demo credentials are public by nature. Anyone with the URL and the demo password can sign in. Use a server and database holding only fake data, and consider basic authentication or an IP allowlist at nginx until the demonstration is over.

• Only 80 and 443 open to the internet. The database publishes no port; the app is on loopback.

• Reserve a static IP, so a restart doesn't break DNS and certificate renewal.

• Rotating application or encryption keys invalidates every issued token and stored credential. Do it before real data arrives, not after.

• Confirm the development override isn't loaded — dcp config should show no published database port.

• Keep the repository private if it contains your schema, infrastructure or security reasoning.

The go-live checklist

Before the server

1. Production image builds locally
2. Production mode boots and resolves every route, checked in CI
3. Database migrates from empty and seeds successfully
4. Reference data comes from migrations, not hand-inserted rows
5. Scripts use set -euo pipefail and psql -v ON_ERROR_STOP=1
6. Full end-to-end demo passes twice in a row
7. No credentials baked into test tooling
8. Code committed, staged files checked for secrets, first commit read before pushing
9. Decided: the project's own database, never a shared superuser connection
10. Checked what owns ports 80 and 443 on the server, and chose the front door accordingly

On the server

1. docker ps works without sudo, after a fresh login
2. Code cloned or copied without dependency folders, runtime state or .env
3. .env created from the template before building
4. Build-time user ID and group ID set to your own user before building
5. Secrets generated on the server; production mode on, debug off
6. Every secret the app requires in production is non-empty
7. Images built; profile-gated services checked with config --services
8. Started with both -f files; config shows the app on 127.0.0.1 and no database port
9. Host port confirmed free and written down
10. Migrations run from the production image, with administrator credentials
11. Runtime volume owned by the app user; signing keys generated and listed
12. /readyz returns 200 on the server, with the status code checked
13. Static external IP reserved; dig matches ifconfig.me
14. Firewall allows 80 and 443, and nothing else publicly
15. Front door proxies to the loopback port, with X-Forwarded-Proto, body size and the ACME challenge location
16. nginx -t passes, and nginx reloaded
17. Certificate issued; health, readiness and key endpoints all return 200 over HTTPS
18. Database seeded on the server; accounts confirmed with a query
19. Client files generated on the server and fetched with scp
20. Full demo run against the domain
21. Access restricted if the demo credentials are public

None of these failures was exotic. Each was an ordinary assumption that happened to be true on my laptop and false on the server. The value of writing them down is that next time, they are checks instead of surprises.