Some faults hide while containers keep running. They show up when the stack starts from nothing: on a new host, after docker compose down, or after a fresh checkout.
fresh checkout ─► .env missing ─────────► DB_PASSWORD blank ─► db refuses to initialise
docker compose down ─► db removed ──────► new anonymous volume ─► signups gone
docker compose up ─► db and web start ──► web connects too early ─► web exits 1Missing configuration
Compose reads .env from the project directory to fill ${VAR}. .env usually holds secrets and stays out of git, so a fresh checkout has only .env.example.
docker compose configWARN[0000] The "DB_PASSWORD" variable is not set. Defaulting to a blank string.Restore it with cp .env.example .env and set a real value. Postgres reads POSTGRES_PASSWORD only when it initialises an empty data directory. A changed password has no effect on existing data.
Where the data lives
The postgres image declares a volume for its data directory:
docker image inspect -f '{{json .Config.Volumes}}' postgres:16{"/var/lib/postgresql/data":{}}| Storage | Kept until |
|---|---|
Anonymous volume (no volumes: in compose.yaml) | docker compose down removes the container; the next up creates a new, empty volume |
Named volume pgdata (signup_pgdata) | docker compose down -v or docker volume rm |
services:
db:
image: postgres:16
volumes:
- pgdata:/var/lib/postgresql/data
volumes:
pgdata:Wait for readiness, not for start
Postgres takes a few seconds to initialise. A health check reports when it accepts connections, and service_healthy holds web back until then.
services:
web:
depends_on:
db:
condition: service_healthy
db:
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 2s
timeout: 3s
retries: 10Prove it
docker compose up -d
curl -X POST "localhost:8000/signup?name=ana"
docker compose down
docker compose up -d
curl localhost:8000/signupsThe row must still be there, and docker compose ps must show db as (healthy).