Intro
Moving a Docker Compose stack from a laptop to production often fails because the local environment does not resemble production closely enough. A controlled local lab closes that gap. This guide walks through building a production-like Docker Compose environment on a single machine, with practical commands, expected outputs, and recovery steps for common failures.
The target reader is a developer, DevOps consultant, or technical startup team member who already understands basic Docker concepts but needs a repeatable process for deploying and operating Compose-based services safely. The emphasis is on operational safety: observe before changing, limit the blast radius, use placeholders instead of secrets, verify each result, and document how to recover if the expected state is not reached.
By the end of this article, you will have a reusable local lab that includes version and environment checks, a safe configuration path, verification and diagnostics, failure modes with recovery, and an operations checklist. Each section includes commands you can run immediately and the output you should expect.
Version and Environment Inventory
Before changing anything, capture the current state of Docker and the Compose project. This prevents accidental modifications and gives you a baseline for troubleshooting.
1. Record Docker and Compose versions
Run:
docker --version
docker compose version
Expected output example:
Docker version 24.0.7, build afdd53b
Docker Compose version v2.23.0
Make a note of these versions. Compose v2 commands use docker compose (with a space), while the legacy v1 uses docker-compose (with a hyphen). Many tutorials still show the old syntax; using the correct one for your environment avoids "command not found" errors.
2. List running containers and services
Check what is currently running:
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
Expected output example:
NAMES STATUS PORTS
web Up 10 minutes 0.0.0.0:8080->80/tcp
db Up 10 minutes 3306/tcp
If a container is missing or restarting, that is a signal to inspect logs before making changes.
3. Inspect a container without modifying it
Use docker inspect to see mounts, networks, environment variables, and health status:
docker inspect <container_name> --format '{{json .Mounts}}'
This command is read-only and safe. For example, it will show whether the container uses a named volume or a bind mount:
[{"Type":"volume","Name":"myapp_data","Source":"/var/lib/docker/volumes/myapp_data/_data","Destination":"/var/lib/app"}]
4. Verify data persistence
A production-like local test must include a restart test. Stop the container, recreate it, and confirm the application still sees the expected files.
docker stop <container_name>
docker compose up -d
docker exec <container_name> ls /var/lib/app
If the directory is empty after recreation, the service was writing to the container filesystem instead of a volume or mount. Fix that before proceeding.
Common pitfall: Using a bind mount with a relative path that differs between machines. For a portable lab, prefer named volumes for application data and reserve bind mounts for source code or configuration files that you edit locally.
Safe Configuration Path
Configuration changes should be deliberate and reversible. This section provides a step-by-step approach for modifying a Compose file safely in a local lab.
1. Back up the current Compose file
Always make a timestamped copy before editing:
cp docker-compose.yml docker-compose.yml.bak.$(date +%Y%m%d)
This allows instant rollback if a change causes problems.
2. Use environment variables for secrets
Never hardcode passwords or API keys in the Compose file. Instead, reference environment variables:
services:
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
Then create a .env file (and add it to .gitignore):
POSTGRES_PASSWORD=change-me-in-production
For local labs, use placeholder values that are obviously not production secrets. This prevents accidental exposure if the lab is shared.
3. Change one scoped item at a time
If you need to change both a port mapping and a volume, do them separately and test after each change. This isolates the cause if something breaks.
Example: change the web service port from 8080 to 8081.
Before:
ports:
- "8080:80"
After:
ports:
- "8081:80"
Run docker compose up -d and verify with curl localhost:8081.
4. Validate the Compose file syntax
Always run:
docker compose config
This parses the file and reports any syntax errors or missing variables. It also expands environment variables so you can see the final rendered configuration without starting anything.
Expected output on success is the full YAML configuration with variables substituted. On error, it will print a message such as:
ERROR: The Compose file './docker-compose.yml' is invalid because:
services.db.environment.POSTGRES_PASSWORD contains {"POSTGRES_PASSWORD": null}, which is an invalid type, it should be a string
5. Apply and verify
After editing, apply the change:
docker compose up -d
Then check that the service is healthy:
docker compose ps
Expected output shows the service as running or healthy if a healthcheck is defined.
Common pitfall: Forgetting to set the environment variable. If docker compose config shows POSTGRES_PASSWORD: null or an empty string, the variable is missing from the shell or .env file.
Verification and Diagnostics
This section covers how to confirm the stack is working as expected and how to diagnose issues when it is not.
1. Check container status and health
Run:
docker compose ps
Sample output:
NAME COMMAND SERVICE STATUS PORTS
myapp-web-1 "nginx -g 'daemon of…" web running 0.0.0.0:8080->80/tcp
myapp-db-1 "docker-entrypoint.s…" db running (healthy) 5432/tcp
A service with (unhealthy) means the healthcheck is failing. Inspect logs for that service.
2. Read recent logs
docker compose logs -f <service_name>
The -f flag follows the logs in real time. Use --tail 100 to see the last 100 lines without streaming:
docker compose logs --tail 100 <service_name>
Look for error lines such as connection refused, missing files, or permission denied.
3. Execute commands inside a running container
For debugging without modifying the image:
docker compose exec <service_name> sh
Inside the container, you can check network connectivity, file permissions, and environment variables. For example, to test connectivity from the web service to the database:
nc -zv db 5432
Expected output if reachable:
Connection to db 5432 port [tcp/postgresql] succeeded!
4. Verify data persistence again
After the service has been running for a while, stop and restart it to confirm data survives:
docker compose stop
docker compose up -d
Then check the database contents, such as listing tables:
docker compose exec db psql -U postgres -c "\dt"
If tables are missing, the volume was not mounted correctly.
Common pitfall: Relying on the default network name. Containers on the same Compose network can reach each other by service name, but only if they are in the same project. If you see DNS resolution errors, check that both services are defined in the same docker-compose.yml and that you did not accidentally create separate networks.
Failure Modes and Recovery
Production-like labs must include realistic failure scenarios. Here are common failure modes and how to recover from each.
Failure 1: Port already in use
Symptom:
Error response from daemon: driver failed programming external connectivity on endpoint myapp_web_1: Bind for 0.0.0.0:8080 failed: port is already allocated
Why it happens: Another process on the host, or another container, is already listening on the same port.
Recovery:
- Identify the process using the port:
sudo lsof -i :8080 - Either stop that process or change the host port in the Compose file.
- For example, change
"8080:80"to"8081:80"and restart:docker compose up -d.
Failure 2: Database volume not persisting data
Symptom: After docker compose down and up, the database is empty.
Why it happens: The database service writes to the container filesystem by default. Without a named volume, that data is lost when the container is recreated.
Recovery:
- Add a named volume to the service definition:
services:
db:
image: postgres:16
volumes:
- db_data:/var/lib/postgresql/data
volumes:
db_data:
- Then run
docker compose up -dagain. The volume persists until explicitly removed withdocker volume rm.
Failure 3: Environment variable missing
Symptom: Service exits immediately or logs show a variable is null.
Why it happens: The required variable is not set in the shell or in the .env file.
Recovery:
- Check with
docker compose configto see which variables are unresolved. - Add the variable to
.envor export it in the shell before runningdocker compose up. - Restart the service:
docker compose up -d <service_name>.
Failure 4: Container keeps restarting
Symptom: docker compose ps shows Restarting instead of Up.
Why it happens: The application inside the container crashes on startup, often due to a misconfiguration.
Recovery:
- Check logs:
docker compose logs <service_name> - Common causes: incorrect database credentials, missing mount, or a syntax error in a config file.
- Fix the underlying issue, then restart:
docker compose restart <service_name>.
Failure 5: Healthcheck incorrectly marks service unhealthy
Symptom: Service is running but reported unhealthy.
Why it happens: The healthcheck command may be wrong, or it may require tools not present in the image.
Recovery:
- Inspect the healthcheck definition in the Compose file.
- Run the healthcheck command manually inside the container to see its output.
- Adjust the healthcheck parameters (interval, timeout, retries) or fix the command.
- Restart the service and wait for the health status to update.
Operations Checklist
Use this checklist before and after making changes in the lab. Assign a single owner to each item to ensure accountability, and review it at least weekly during active development.
| Check | Command / Action | Expected Result | Owner | Frequency |
|---|---|---|---|---|
| Docker version consistent | docker --version && docker compose version | Output matches documented versions in team runbook | Priya Shah, DevOps Lead | Weekly |
| All services running | docker compose ps | Each service shows Up or healthy | Priya Shah | Every change |
| No recent error logs | docker compose logs --tail 50 | No fatal errors or repeated exceptions | Alex Chen, Backend Dev | Daily |
| Data persistence verified | docker compose down && docker compose up -d && docker compose exec db psql -c "\dt" | Tables still exist after restart | Alex Chen | Weekly |
| Ports not unexpectedly exposed | docker compose ps --format '{{.Ports}}' | Only intended ports are published | Priya Shah | Every change |
| Secrets not in Compose file | grep -i password docker-compose.yml | No hardcoded secrets; only ${VAR} references | Security Review (Lee Wong) | Monthly |
| Backup of volumes exists | docker run --rm -v myapp_data:/data -v $(pwd):/backup alpine tar czf /backup/data.tgz /data | Backup file created and not empty | Lee Wong | Weekly |
| Resource usage within limits | docker stats --no-stream | CPU < 80%, memory < 1GB for lab | Priya Shah | Weekly |
| Recovery procedure documented | Review runbook section Recovery.md | Steps are up to date and tested | Priya Shah | Monthly |
Note: Replace owner names with actual team members. Review frequencies can be adjusted based on project risk.
Conclusion
A Docker Compose production deployment local lab is only valuable if you treat it like production. That means version scoping, read-only observation first, one change at a time, and verification after every step. The commands and checks in this article provide a starting framework.
Begin with a low-risk verification: run docker compose ps, confirm all services are healthy, then perform a restart test to validate data persistence. From there, gradually add more complex scenarios to your lab, such as network partitions or resource constraints.
The goal is to make failures visible early, protect sensitive values, and define recovery steps before an incident occurs. A reliable technical workflow does not just prevent problems; it gives you confidence that when something breaks, you can fix it quickly and safely.