Docker Compose Configuration Mistakes with Practical Examples

Intro

Docker Compose simplifies multi-container application management, but its ease of use masks configuration pitfalls that can cause data loss, service outages, or security vulnerabilities. This article addresses common Docker Compose configuration mistakes, offering practical examples and actionable solutions for developers, DevOps engineers, and technical startup teams.

We focus on observable, verifiable steps: check the current state before making changes, use sensible defaults, avoid hardcoded secrets, and know how to roll back. Each section includes concrete command snippets, expected outputs, and recovery procedures.

Version and Environment Inventory

Before altering any Compose configuration, understand your environment. Different Docker Compose versions have different capabilities and syntax. Run:

docker compose version

Example output:

Docker Compose version v2.27.1

For Compose v1 (Python-based), use docker-compose version. Note the difference: v2 is written in Go and is a plugin for the Docker CLI, while v1 is a standalone binary. Many online examples refer to v1; if you use v2, commands may need docker compose (with space) instead of docker-compose.

Check Docker Engine version:

docker version --format '{{.Server.Version}}'

This should be compatible with your Compose version.

Inventory running containers and their status:

docker compose ps

This shows the project services, their state, and exposed ports. For deeper inspection, use docker inspect on a specific container to see mounts, networks, and environment variables (though environment variables may be sensitive unless redacted).

Separating Observation from Intervention

Make a habit of recording the current state before changing anything. For example, save the current configuration:

docker compose config > compose-backup-$(date +%Y%m%d).yml

This allows you to diff against the new configuration and roll back if needed.

Data Storage Location Verification

One frequent mistake is assuming data persists across container recreations without configuring volumes properly. In Compose, you can mount a named volume or bind mount. A named volume is managed by Docker and typically stored under /var/lib/docker/volumes/, while a bind mount maps a host path directly.

Example Compose snippet with a named volume:

services:
  db:
    image: postgres:16
    volumes:
      - db_data:/var/lib/postgresql/data
volumes:
  db_data:

With a bind mount:

volumes:
  - ./data:/var/lib/postgresql/data

To verify data persistence, run a restart test: stop and remove the container, then bring it back up:

docker compose down
docker compose up -d

Then check if the data is still accessible. If data disappears, the service likely wrote to the container's ephemeral filesystem instead of the intended volume.

Safe Configuration Path

When modifying Compose files, follow a systematic approach to avoid introducing errors.

Validate Configuration Before Applying

Always validate your Compose file with:

docker compose config

This checks syntax and resolves variables, showing the final configuration. If there are errors, it exits with a non-zero code and prints messages. For example, if you have an invalid YAML indentation:

docker compose config

Output:

services.db.environment.MYSQL_ROOT_PASSWORD contains an invalid type, it should be a string, or an object

Note: docker compose config does not guarantee the services will run correctly; it only checks syntax and schema.

Use Environment Variables Correctly

Instead of hardcoding secrets in the Compose file, use environment variable substitution. In docker-compose.yml:

services:
  app:
    image: myapp:latest
    environment:
      DB_PASSWORD: ${DB_PASSWORD}

Then specify the value in a .env file in the same directory (not committed to version control):

DB_PASSWORD=supersecret

Or set it in the shell:

export DB_PASSWORD=supersecret

When you run docker compose config, the variable will be substituted. To avoid exposing secrets, use docker compose config --no-interpolate to see the raw file without substitution.

A common mistake is using $$ (double dollar) to escape variable substitution when you want the literal string passed through. For instance, if you want to pass a literal $DB_PASSWORD to the container, write $$DB_PASSWORD in the Compose file.

Limit Blast Radius: Use Profiles and Override Files

Use Compose profiles to optionally start services. For example:

services:
  app:
    image: myapp:latest
  debug-tools:
    image: busybox
    profiles: ["debug"]

With profiles, docker compose up starts only app, while docker compose --profile debug up starts both. This prevents accidental startup of debugging services in production.

Another technique is multiple Compose files, like compose.yaml and compose.override.yaml. The override file can specify development-specific settings. By default, if both files exist, Compose merges them automatically; you can view the merged configuration with:

docker compose config

If you use custom file names, specify them with -f flags. This allows you to keep base configuration stable and add local modifications without touching the main file.

Make Small, Reversible Changes

Change one setting at a time and test immediately. For instance, if you need to increase a service's memory limit, edit the Compose file:

services:
  app:
    deploy:
      resources:
        limits:
          memory: 512M

Apply:

docker compose up -d

Then check if the service is healthy and memory usage is within limits. If issues arise, revert the change easily by undoing the edit and running docker compose up -d again.

Verification and Diagnostics

After applying changes, verify the system behaves as expected.

Check Service Status

Use docker compose ps to see if containers are running:

docker compose ps

Output example:

NAME                COMMAND                  SERVICE             STATUS              PORTS
myapp_app_1         "python app.py"          app                 running             0.0.0.0:8000->8000/tcp
myapp_db_1          "docker-entrypoint.s…"   db                  running             5432/tcp

If a container is exited or restarting, investigate logs.

Read Logs Effectively

Use docker compose logs to view logs:

docker compose logs app

Follow logs in real time:

docker compose logs -f app

If you need to see only recent lines:

docker compose logs --tail=100 app

Common failure indicators in logs include exceptions, connection refused errors, or crash loop messages. For example, if the database is unreachable, you might see:

ERROR: could not connect to database: connection refused

Inspect Container Details

Use docker inspect to get detailed information about a container, including its health status, mounts, and environment:

docker inspect myapp_app_1

To extract specific fields:

docker inspect --format '{{.State.Health.Status}}' myapp_app_1

If the health status is unhealthy, review the healthcheck configuration.

Define Healthchecks

Add healthchecks to your services to automatically detect failures. Example for a web app:

services:
  web:
    image: nginx:alpine
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

With healthchecks, docker compose ps shows the health status, and you can use docker compose up --wait to block until services are healthy.

Debug Inside the Container

Use docker compose exec to run commands inside a running container:

docker compose exec app sh

This gives you a shell in the container to check files, processes, or test connectivity. For one-off commands:

docker compose exec app env

Note: exec requires the container to be running; if the container exits immediately, you may need to override the entrypoint:

docker compose run --entrypoint sh app

Failure Modes and Recovery

Even with careful planning, things go wrong. Here are typical failure scenarios and how to recover.

Container Exits Immediately

If a container starts and exits with code 0 or non-zero, check the logs:

docker compose logs <service>

Often, the command is misconfigured. In Compose, the command option overrides the default CMD. For example, if you have:

services:
  app:
    image: alpine
    command: echo "hello"

The container will run echo and exit. To keep it running, you might need a long-running process. Recovery: adjust the command to a foreground process.

Port Conflicts

If a service fails to bind a port, you'll see an error like:

Error starting userland proxy: listen tcp4 0.0.0.0:80: bind: address already in use

Identify which process is using the port on the host:

sudo lsof -i :80

Or on Linux:

sudo ss -tulpn | grep :80

Then either stop the conflicting process or change the host port in the Compose file:

ports:
  - "8080:80"

Volume Mount Errors

If a bind mount path does not exist on the host, Docker may create it as a directory with root ownership, leading to permission issues inside the container. For example:

volumes:
  - ./logs:/app/logs

If ./logs does not exist, Docker creates it, but the container user might not have write permissions. Recovery: create the directory with appropriate permissions before starting:

mkdir -p logs && chmod 777 logs

Or adjust the container user to match.

Environment Variable Not Substituted

If you reference a variable in the Compose file but it is not defined, docker compose config will warn or error. For example:

environment:
  - DATABASE_URL=${DATABASE_URL}

If DATABASE_URL is not set, the container receives an empty string. To prevent this, set a default in the Compose file:

environment:
  - DATABASE_URL=${DATABASE_URL:-postgres://localhost:5432}

Then verify with docker compose config.

Recovery Strategy: Rollback

Always be able to revert to a known good state. This means:

• Keep version control for your Compose files (e.g., Git).
• Before making changes, create a backup of the current configuration and, if applicable, data.
• Use docker compose config to save the fully resolved configuration for future reference.
• If a change breaks the application, check the previous version and apply it: git checkout -- docker-compose.yml and then docker compose up -d.

For data, if using named volumes, consider snapshots or backups. For instance, to backup a PostgreSQL database in a volume, you could run:

docker compose exec db pg_dump -U postgres mydb > backup.sql

Then to restore:

cat backup.sql | docker compose exec -T db psql -U postgres mydb

Common Pitfalls and How to Avoid Them

This section consolidates frequent mistakes, why they happen, and how to prevent or recover from them.

Pitfall 1: Using latest Tag for Images

Using image: myapp:latest can lead to unpredictable behavior because latest may change unexpectedly. This makes rollback difficult and breaks reproducibility.

How to avoid: Pin specific image versions, e.g., image: myapp:1.2.3. Use digest for even stronger immutability: myapp@sha256:....

Pitfall 2: Hardcoding Secrets in Compose Files

Storing passwords or API keys directly in docker-compose.yml is a security risk, especially if the file is committed to a repository.

How to avoid: Use environment variables or Docker secrets. For local development, use a .env file that is gitignored. For production, use a secrets manager.

Pitfall 3: Misunderstanding Volume Types

Using bind mounts when you meant named volumes (or vice versa) can cause data loss or permission issues. Bind mounts are host-specific; named volumes are portable and managed by Docker.

How to avoid: Clearly define volume type and purpose. Use named volumes for persistent application data, bind mounts for development where you need live code sync.

Pitfall 4: Not Setting restart Policies

By default, containers do not restart automatically unless you specify a restart policy. If a container crashes, it stays down.

How to avoid: Set restart: unless-stopped or restart: always for production services. Example:

services:
  app:
    restart: unless-stopped

Pitfall 5: Ignoring Resource Limits

Without limits, a container can consume all host resources, affecting other services.

How to avoid: Set memory and CPU limits using the deploy key (for Swarm) or mem_limit, cpus (for non-Swarm). Example:

services:
  app:
    mem_limit: 512m
    cpus: 0.5

Pitfall 6: Misconfiguring Networks

Services may not communicate because they are on different networks or network aliases are wrong.

How to avoid: Explicitly define networks in the Compose file and attach services to appropriate ones. Use docker compose exec to test connectivity with ping or curl.

Pitfall 7: Not Backing Up Data

Data in containers or volumes can be lost if you delete volumes inadvertently.

How to avoid: Regularly back up volumes using docker run --rm -v volume_name:/data -v $(pwd):/backup alpine tar czf /backup/backup.tar.gz -C /data .

Pitfall 8: Overlooking depends_on Limitations

depends_on only controls startup order; it does not wait for the dependency to be ready (e.g., database accepting connections).

How to avoid: Use healthchecks and depends_on with condition: service_healthy (Compose v2.1+). Example:

services:
  web:
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

Operations Checklist

Use this checklist before and after making Compose configuration changes. Assign an owner (e.g., DevOps engineer) and review frequency.

Each item should have a named owner. For instance, the DevOps lead (e.g., "Priya Shah, Engineering Lead") is responsible for configuration backups and applying changes. Review intervals can be adjusted based on risk, but critical settings should be reviewed after every change.

Conclusion

Docker Compose configuration errors can lead to downtime and data loss, but they are preventable with systematic practices. By validating configurations, managing volumes and environment variables correctly, and having a rollback plan, you can reduce risk significantly.

Always observe before changing, make small reversible edits, and verify the outcome with concrete commands. Keep a checklist and assign ownership to ensure accountability. For further learning, explore Docker's official documentation on Compose file reference, healthchecks, and secrets management.

Next step: pick one low-risk improvement from this article, such as adding healthchecks to a service, and implement it in a development environment. Record the current state, apply the change, and verify the expected behavior. Document any issues for future reference.

By adopting these practices, you'll build a more resilient containerized environment.