## 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:

```bash
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:

```bash
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:

```bash
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:

```json
[{"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.

```bash
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:

```bash
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:

```yaml
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:

```yaml
ports:
  - "8080:80"
```

After:

```yaml
ports:
  - "8081:80"
```

Run `docker compose up -d` and verify with `curl localhost:8081`.

### 4. Validate the Compose file syntax

Always run:

```bash
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:

```bash
docker compose up -d
```

Then check that the service is healthy:

```bash
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:

```bash
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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
docker compose stop
docker compose up -d
```

Then check the database contents, such as listing tables:

```bash
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:

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

- Then run `docker compose up -d` again. The volume persists until explicitly removed with `docker 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 config` to see which variables are unresolved.
- Add the variable to `.env` or export it in the shell before running `docker 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.