Reading a docker-compose.yml Configuration

depends_on controls startup order with optional health conditions:

The web service has two depends_on entries with different conditions:

• db: condition: service_healthy → web waits until the db passes its healthcheck (pg_isready returns success)
• redis: condition: service_started → web only waits for the redis container to start, not for Redis to be ready to accept connections

Why two different conditions?
The database needs the stricter check because the app will crash immediately if it can't connect to Postgres on startup — and Postgres takes a few seconds to initialize even after the container starts. Redis typically starts faster and connection failures are less critical.

The three condition values:

• service_started → container is running (default if condition is omitted)
• service_healthy → container is running AND healthcheck passes
• service_completed_successfully → for one-off tasks that must finish before the service starts (e.g., database migrations)

YAML indentation rule: The conditions are children of db and redis, which are children of depends_on. Every level of indentation = one level deeper in the hierarchy.

PORT MAPPING syntax: "HOST_PORT:CONTAINER_PORT"

The format is always "HOST:CONTAINER" — left side is your machine, right side is inside the container:

• You visit http://localhost:8080 on your computer
• Docker forwards that to port 3000 inside the web container
• The Node.js app inside the container listens on port 3000 (as configured in the app code)

Why use different port numbers?

• You might already have something running on port 3000 locally
• 8080 is a common alternative HTTP port (ports below 1024 require root privileges)
• You can map multiple containers to different host ports even if they all use the same container port

Compare redis in this file:
Redis uses "6379:6379" — same host and container port. This is common when there is no conflict and you want the default port to work directly.

What if you omit the ports section (like db does here)?
The db service has no ports: mapping — Postgres is not reachable from your host machine, only from other containers in the same Docker Compose network. This is a security best practice: the database should not be exposed to the host.

Named volumes persist data beyond the container lifecycle:

Docker containers are ephemeral — if you run docker compose down without volumes, everything written inside the container is lost. For a database, this would mean losing all your data every time you restart.

The pgdata:/var/lib/postgresql/data mapping solves this:

• pgdata → the named volume (defined at the bottom of the file under volumes:)
• /var/lib/postgresql/data → the directory inside the container where PostgreSQL stores all its data files

Docker manages the pgdata volume on your host machine's filesystem. Even if you remove and recreate the container, the volume (and all your database data) remains intact.

Compare: bind mount vs. named volume:

• Named volume (pgdata:/path) → Docker manages the location; portable across machines
• Bind mount (./uploads:/app/uploads in the web service) → maps a specific host directory directly; good for development files you want to edit locally

The web service uses a bind mount for uploads (so you can see uploaded files on your host machine). The db uses a named volume for data (so Docker manages it safely).

Healthcheck verifies readiness; web waits for it to pass:

The db healthcheck is configured as:

test: ["CMD-SHELL", "pg_isready -U appuser -d shopdb"]
interval: 10s
timeout: 5s
retries: 5

What each line means:

• test → the command to run: pg_isready is a PostgreSQL utility that checks if the server is ready to accept connections for the specified user and database
• interval: 10s → run the check every 10 seconds
• timeout: 5s → if the command takes longer than 5 seconds, count it as failed
• retries: 5 → the service becomes "unhealthy" only after 5 consecutive failures

The chain of events on startup:

1. Docker starts the db container
2. PostgreSQL initializes inside the container (may take 5-15 seconds)
3. Docker runs pg_isready every 10 seconds
4. When pg_isready succeeds, Docker marks db as "healthy"
5. Only now does Docker start the web container (because of condition: service_healthy)

Without this, the Node.js app would try to connect to the database before PostgreSQL finished initializing — causing a crash-on-startup bug.

Missing env var = undefined in app code = runtime error:

Docker does NOT automatically copy environment variables between services. Each service's environment is self-contained. If DATABASE_URL is removed from the web service's environment section:

• The web container starts (Docker doesn't know DATABASE_URL is required)
• The Node.js app reads process.env.DATABASE_URL → gets undefined
• The ORM or database client tries to parse undefined as a connection URL → throws an error
• The app crashes, or fails to connect to the database

Notice the hostname in the URL: @db:5432
Inside a Docker Compose network, services can reach each other by their service name (db, redis, web). This is why the URL uses @db:5432 instead of @localhost:5432 — from inside the web container, "db" resolves to the db service's internal IP address.

Best practices for environment variables in Docker:

• Use .env files for local development (reference with ${"${VAR_NAME}"} in the compose file)
• Never commit real credentials to version control — use secrets managers in production
• Use env_file: directive for longer lists of variables
• Document required variables in README so developers know what to set