When a compose file that runs on a developer’s laptop is moved to production as is, the problems come one after another: the latest tag pulls a different version one night, a password embedded in the file ends up in the repository, a published database port bypasses the firewall, and unlimited json-file logs fill the disk. Compose was designed for development; still, configured correctly, it does the job for single-server production deployments. Below, the decisions to make in production are covered in order, and the threshold where Compose is no longer enough is described clearly.
When Compose is enough in production
Compose isn’t an orchestrator. It manages a single Docker Engine, doesn’t move services to another machine if the server crashes and doesn’t manage traffic switchover during updates. On the other hand, it’s simple to set up, has a low learning cost and describes the whole stack in a single file. Fewer parts, fewer failures. It’s a reasonable choice for production under these conditions:
- The application fits on a single server and vertical growth (a more powerful server) is enough.
- The accepted recovery time for a server failure can be met by rebuilding from backup or from a second server on standby.
- Brief downtime during updates is acceptable, or it’s solved separately at the reverse proxy level.
- The team doesn’t have the capacity to operate a platform like Kubernetes, or doesn’t need one.
Sample production compose file
The example below shows a web application, PostgreSQL, and a structure that connects to a shared reverse proxy network in front. The following sections explain each decision separately.
name: shop
services:
app:
image: registry.example.com/shop/app:1.8.3
restart: unless-stopped
env_file: .env.production
environment:
DB_HOST: db
DB_PASSWORD_FILE: /run/secrets/db_password
secrets: [db_password]
depends_on:
db:
condition: service_healthy
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/healthz"]
interval: 30s
timeout: 5s
retries: 3
start_period: 40s
read_only: true
tmpfs: [/tmp]
security_opt: ["no-new-privileges:true"]
deploy:
resources:
limits:
cpus: "1.5"
memory: 768M
logging:
driver: json-file
options:
max-size: "20m"
max-file: "5"
networks: [proxy, backend]
db:
image: postgres:16.4
restart: unless-stopped
environment:
POSTGRES_DB: shop
POSTGRES_USER: shop
POSTGRES_PASSWORD_FILE: /run/secrets/db_password
secrets: [db_password]
volumes:
- db_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U shop -d shop"]
interval: 10s
timeout: 5s
retries: 5
networks: [backend]
secrets:
db_password:
file: ./secrets/db_password.txt
volumes:
db_data:
networks:
backend:
internal: true
proxy:
external: true
Before applying the configuration, view the merged version with variables resolved using docker compose config; syntax errors and unexpected variable values show up here. Make sure the wget or curl used in the healthcheck exists in the image; minimal images don’t have these tools and the check always appears to fail. For a container that’s running but constantly shows “unhealthy”, this is the first place to look.
Pinning image versions and building
A latest tag or a major-version-only tag (postgres:16) makes the same compose file run different software on different days. When the server restarts or someone runs docker compose pull, an unexpected version can come into play. Versions should change by decision. In production:
- Use a full version tag (
postgres:16.4). For tighter control, the digest can also be pinned along with the tag:postgres:16.4@sha256:…; in that case the same image is pulled even if the tag changes. - Instead of building your own application’s image on the server with
build:, build it in the CI pipeline and push it to a registry with a version tag. That way only tested images run on the server, and rolling back is just a matter of switching the tag to the previous version. Setting up the pipeline is explained in the CI/CD pipeline with GitHub Actions guide. - Rebuild base images regularly for security updates; pinning doesn’t mean stopping updates, it means doing them in a controlled way.
Environment variables and secrets
Two different “env” concepts are often confused in Compose. The .env file in the project directory is read to fill in the ${VARIABLE} expressions in the compose file; env_file:, on the other hand, passes variables into the container. For environment-specific settings (domain, log level, external service addresses), env_file is enough, but it’s a weak choice for passwords and API keys: environment variables appear in the docker inspect output and can leak into error reports and child processes.
A better method is the Compose secrets definition. A file-based secret appears inside the container as a read-only file at /run/secrets/<name>. The official PostgreSQL, MariaDB and MySQL images support reading the password from a file with _FILE-suffixed variables; apply the same pattern in your own application. The rules:
- The
secrets/directory and.env.productiondon’t go into version control; they’re added to the.gitignoreand.dockerignorefiles. - File permissions are set so that only the deployment user can read them.
- Secrets are never embedded in the image with
COPYorENV; image layers can be read back.
Network structure and port publishing
Because the backend network in the example is defined as internal: true, it has no outbound access to the outside world; the database is reachable only from the application. The application talks to the reverse proxy running in front over a shared network created in advance (docker network create proxy), so it publishes no ports. Details of the proxy configuration are in the Nginx reverse proxy configuration article.
If you do publish ports, know this trap: Docker adds its own iptables rules for published ports, and these rules can bypass rules defined with front-end tools such as UFW. A database port written as "5432:5432" can become reachable from the internet even if it looks closed in the firewall. If only local access is needed, bind the port explicitly to the loopback address: "127.0.0.1:8080:3000". Verify with a port scan from outside the server; looking from the inside is misleading.
Volumes, backups and data persistence
Containers are ephemeral; everything that needs to persist (database files, user uploads) must be kept in a named volume or a bind mount. The docker compose down -v command also deletes named volumes. On a production server, this command should be explicitly forbidden in the operating rules; a single slip of habit takes the database with it.
Having a volume doesn’t mean having a backup. Copying the files of a running database with tar can produce an inconsistent backup; use the database’s own tool:
# Logical backup (PostgreSQL custom format)
docker compose exec -T db pg_dump -U shop -Fc shop > /backup/shop_$(date +%F).dump
# Volume archive for static data such as the uploads directory
docker run --rm -v shop_uploads:/data:ro -v /backup:/backup alpine \
tar czf /backup/uploads_$(date +%F).tar.gz -C /data .
Compose prefixes volume names with the project name (such as shop_uploads); verify the real name with docker volume ls. Backups should be copied off the server, and restores should be tried regularly in an empty environment. An untested backup isn’t a backup. The 3-2-1-1-0 backup rule provides a good framework for backup retention.
Healthchecks, restarts and resource limits
| Setting | What it grants | Watch out for |
|---|---|---|
restart: unless-stopped |
The service comes back after a crashed process and a server reboot | Doesn’t restart a container that’s unhealthy but running |
healthcheck |
Measures whether the service really responds | The endpoint shouldn’t run heavy queries |
depends_on: condition: service_healthy |
The application doesn’t start before the database is ready | Only for startup order |
deploy.resources.limits |
Stops one service from consuming all the memory | If the memory limit is exceeded, the process is killed by the OOM killer |
logging options |
Prevents log files from filling the disk | The default json-file driver has no size limit |
Using docker compose up -d --wait during deployment makes the command wait until services become healthy and otherwise return an error code; in the CI/CD pipeline, this prevents the next step from running on top of an unhealthy deployment. When setting the memory limit, align the application’s runtime settings too (for example --max-old-space-size in Node.js, the heap size in the JVM); otherwise the process grows without knowing the limit and gets killed.
For extra hardening, read_only: true in the example makes the root file system read-only, and no-new-privileges stops processes from escalating privileges via setuid. Running as an application user defined in the image instead of root inside the container serves the same purpose.
Thresholds for moving to an orchestrator
Moving to an orchestrator such as Kubernetes, Nomad or Docker Swarm is a decision based on concrete need, not fashion. Consider the move when one or more of the following arises:
- Zero-downtime updates have become a business requirement, and solutions at the reverse proxy level are getting complex; the options for these techniques are compared in the zero-downtime deployment article.
- The acceptable downtime for a single server failure is too short to be met by rebuilding.
- The load requires horizontal scaling (spreading across multiple servers).
- The number of servers and stacks has grown; managing a separate compose file, separate backup script and separate monitoring for each one has started producing errors.
Setting up an orchestrator before reaching these thresholds means, in a small team, operating the platform more than the application. Complexity is a source of failure too. The deployment architecture, the image pipeline and the move decision should be planned together; we handle this as part of our Docker and container-based deployment service. The definition of every field is in the Compose file reference.
Frequently asked questions
Is there a difference between docker-compose and docker compose?
docker-compose is the old standalone tool written in Python (Compose v1) and is no longer developed. The current version is the docker compose command, which comes as a plugin to the Docker CLI (Compose v2). The version field in files is no longer taken into account either; there’s no need to write it in new files.
Does Docker automatically restart a container whose healthcheck fails?
Not with Docker Engine and Compose alone. The healthcheck status is marked as unhealthy and used in depends_on conditions and monitoring; the restart policy only kicks in when the process exits. Restarting an unhealthy container requires an orchestrator, an external monitoring script or the application terminating itself.
Is there downtime during updates when deploying with Compose?
Yes, even if brief. While docker compose up -d recreates the container with the new image, the old one is stopped and the new one starts, and requests aren’t served in between. Avoiding downtime requires techniques such as a blue-green switch with two separate stacks behind a reverse proxy; Compose doesn’t do this on its own.
Should I also run the database inside Compose?
It’s possible for small and medium-load single-server projects, but responsibility for backups, version upgrades and monitoring stays with you. A managed database service or a separate database server makes it easier not to put data at risk when rebuilding the application stack.