Docker Deployment Checklist: The Five Errors That Break a First Deploy

The first deployment of a containerised app fails for a small set of reasons, and almost all of them are visible in the logs within thirty seconds. The problem is that the same three symptoms — the container exits immediately, the site does not load, or the app runs but behaves oddly — can come from five different causes, which is why first deploys turn into an afternoon.

This is the checklist version: what to confirm before you deploy, and how to read the five standard failures when they appear.

What has to be true before you run the first deploy

Five things, all checkable in the project files. Environment variables are documented in one place and not committed with real secrets. Ports are consistent: the app listens on a port, the Dockerfile exposes it, and the compose file publishes it. Volumes are declared for anything that must persist — uploads, database files, logs. The build context excludes what it should, via a .dockerignore, so images do not ship node_modules or git history. And the base image tag is pinned rather than latest, so today’s build can be reproduced tomorrow.

Why the container works locally and fails on the server

Three differences explain most of it. The architecture may differ: an image built on an ARM laptop will not run on an amd64 server unless it was built for both. The environment differs: a variable present in your shell is absent inside the container. And file ownership differs: what your user account can write, a container running as a different user often cannot.

Each of those produces a different log line, which is why reading the log is faster than guessing.

How to read the five standard errors

Symptom	Likely cause	Fix
Container exits immediately, restart loop	Missing environment variable or a crash on startup	Read the first twenty log lines; supply the variable
Site times out, container is running	Port not published, or bound to 127.0.0.1 inside the container	Bind to 0.0.0.0 and publish the port in compose
Permission denied on writes	Volume owned by a different user than the process	Match the user ID, or fix ownership on the host path
Exec format error	Image built for the wrong CPU architecture	Build for both platforms, or build on the server
Works on IP, fails on domain	Reverse proxy not forwarding, or the app expects HTTPS	Check proxy headers and the forwarded port

What to check when the app runs but nothing loads

If the container is up and the port is open, the problem sits in front of the app. Check, in order: whether the process inside is listening on the interface you think (not just localhost); whether the reverse proxy passes the host header; whether the app generates absolute URLs with the wrong scheme, which produces redirect loops behind a proxy; and whether a firewall or security group is blocking the port.

A quick test separates the layers: request the app directly on its published port, bypassing the domain. If that works, the app is fine and the proxy is the problem.

How to make the next deploy boring

Four habits turn deployments from an event into a routine. Put the whole stack in a compose file so one command brings it up. Pin every image tag and record the versions. Add a health-check endpoint, because a container that is running is not necessarily serving. Keep logs in a place you can read them, and back up volumes on a schedule — data loss is the one failure that a rollback cannot fix.

If you are starting from nothing, the beginner’s guide to deploying a Docker web app walks through the first deploy step by step, building your first REST API with FastAPI gives you something worth deploying, and the free AI API roundup covers the services worth wiring into the app afterwards.