Deploying a Web Application with Docker Compose: Production Configuration

Production deployment with Docker Compose: pinned image versions, secrets, the port and firewall trap, volume backups, healthchecks, log and resource limits, and the threshold for moving on.
Technical summary
Technology
Docker Engine, Docker Compose v2, Compose Specification, Nginx, PostgreSQL
Topic
Production deployment with Compose on a single server
Level
Intermediate–advanced
Prerequisites
  • A Linux server with Docker Engine and the Compose plugin installed
  • The application’s container image or Dockerfile
  • Basic networking and reverse proxy knowledge
In this article9 sections

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.production don’t go into version control; they’re added to the .gitignore and .dockerignore files.
  • File permissions are set so that only the deployment user can read them.
  • Secrets are never embedded in the image with COPY or ENV; 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.

Support

Contact us for support or a discovery session on this topic.

Contact form
[email protected]

Eretek Web

We build and maintain corporate websites, WordPress and CMS platforms, intranet and SharePoint portals, document management, and form and approval workflows, and keep them secure and up to date.

Knowledge Center

Other articles