Topic

Docker & Compose

Definition

A container packages an application with its runtime dependencies into an isolated, reproducible unit, while a multi-container orchestration file such as docker-compose.yml declares how several related containers, such as an API, database, cache, and broker, run and network together.

In simpler words

Docker ships this exact app plus everything it needs as one predictable box. Compose wires several boxes together for local development.

Judge Docker the same conceptual way as Redis or RabbitMQ: where it solves a real environment problem, and where it stops mattering for this course.

Open official example (opens in new tab)

After this you can

Explain what a container isolates versus a virtual machine
Read a docker-compose.yml and name each service role
Reason about why it works on my machine gets fixed by containers
Describe the tradeoff of adding Docker to a small team workflow

Why containers instead of installing locally

Definition

Environment drift occurs when developer machines have different tool, library, or operating system versions than production, producing bugs that only reproduce on some machines. Containers eliminate that drift by shipping the exact runtime.

In simpler words

Docker stops it works on my laptop but not in staging by shipping the whole environment, not only the code.

A container bundles the app, its language runtime, and system libraries into one image that runs identically on a laptop, a CI runner, or a production host.

Compared to a full virtual machine, a container shares the host kernel and starts in seconds, which is why local development stacks combining a database, cache, broker, and API commonly run as containers instead of virtual machines.

A typical setup runs Postgres in a container for local development specifically so every contributor gets the same database version without installing Postgres natively.

Reading a compose file

services:
  api:
    build: ./apps/api
    ports: ["3001:3001"]
    depends_on: [postgres, redis]
  postgres:
    image: postgres:16
    environment: { POSTGRES_PASSWORD: dev }
  redis:
    image: redis:7

Each service is one container. depends_on only orders startup; it does not wait for the database to accept connections.

What Compose does and does not guarantee

Definition

docker-compose.yml declares service definitions, networking, and startup order for local or single-host multi-container environments. It does not manage rolling deploys, autoscaling, or multi-host orchestration.

In simpler words

Compose is great for running a whole stack locally with one command. It is not a production deployment platform by itself.

depends_on controls container start order, not application readiness. Nest must still retry its Postgres connection on boot rather than assume the database is already accepting queries.

Named volumes persist data, such as a Postgres data directory, across container restarts. Without one, stopping the stack can silently wipe local development data.

Production-grade orchestration, such as rolling updates, health-based routing, and scaling, is typically a separate tool such as Kubernetes or a managed container service. Compose is the local development and single-host layer.

Keep in mind

Containers fix environment drift; they do not fix incorrect code.
depends_on is start order, not a readiness check, so code defensively.
Reach for full orchestration only once the single-host model of Compose is not enough.

Test

Check your understanding

At least 10 questions — mix of concept, syntax, practical, and logic. Score ≥80% (enforced by the API) to save progress.

Checking your session…

15 questions · concept 5 · syntax 3 · practical 4 · logic 3

1. What does Compose buy you?

Concept

Automatic horizontal scaling of the API under loadThe same process shape for API (and usually Postgres) across environmentsA production-grade secrets manager for the whole stackZero-downtime rolling deploys of new image versions

2. Where should secrets live?

Syntax

In a build ARG passed at docker build timeEnvironment variables / secret mounts — not image layersIn a committed .env file that Compose reads on startupBaked into a base image shared across services

3. Do containers replace migrations?

Practical

No — still run reviewed migrationsYes — the entrypoint can enable synchronize for the first bootYes — a volume snapshot restores the schema insteadYes — Compose applies the schema from the image build

4. Does Docker remove Nest structure needs?

Logic

Yes — the container boundary replaces module boundariesYes — DI is unnecessary once each service is isolatedNo — modules, DI, and TypeORM still applyYes — TypeORM config moves entirely into compose env

5. What should a good API Dockerfile do?

Concept

Install dev dependencies so debugging works in productionBuild a reproducible runtime image without embedding prod secretsCopy the local node_modules to skip the install stepRun as root so the app can bind any port freely

6. Why depend_on Postgres in Compose?

Practical

It blocks the API until Postgres passes its healthcheckIt restarts the API whenever Postgres restartsStart order/help wiring — still wait for readiness/health for real readinessIt shares the Postgres environment variables with the API

7. What about binding Postgres data?

Syntax

Rely on the image layer cache to keep the data between runsUse a volume/bind mount so data survives container recreationCommit the running container to a new image after each writeMount the data as read-only so it cannot be corrupted

8. Is synchronize true OK only in containers?

Logic

No — still a bad shared-habit; use migrationsYes — an ephemeral container makes schema drift harmlessYes — only if the data is on a named volumeYes — because each container rebuilds the schema identically

9. How do services find each other in Compose?

Concept

Through the host’s /etc/hosts entries added by ComposeBy the container id, which Compose injects as an env varService DNS names on the compose networkOver the Docker bridge gateway IP shared by all services

10. Which practice is wrong?

Practical

Baking production JWT secrets into image layersInjecting secrets as environment variables at runtimeApplying schema changes with reviewed migrationsPersisting Postgres data on a named volume

11. Why is this Dockerfile practice bad?

Conceptadvanced

# Dockerfile
COPY .env.production .env

It overwrites the runtime environment variables at startupIt invalidates the build cache on every rebuildIt bakes secrets into image layers that anyone with the image can readIt prevents Compose from injecting its own env values

12. What is postgres in the host part of this URL?

Syntaxintermediate

# docker-compose.yml
services:
  api:
    environment:
      DATABASE_URL: postgres://user:pass@postgres:5432/app

The default Postgres superuser account nameThe name of the Docker volume holding the dataThe database name the connection opensThe Compose service name, resolved via the compose network DNS

13. What does depends_on guarantee here?

Practicaladvanced

services:
  api:
    depends_on:
      - postgres

That Postgres has passed a healthcheck before the API startsThat the API restarts if Postgres exitsStart ordering only — not that Postgres is ready to accept connectionsThat the two containers share the same network namespace

14. What does this bind mount achieve?

Logicintermediate

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

Database data persists across container recreationIt syncs the data directory to the image on each buildIt makes Postgres data read-only for safetyIt shares the data directory with the API container

15. What step is missing before the app serves traffic?

Conceptadvanced

# entrypoint
node dist/main.js  # synchronize:false

Seeding the database with the initial admin accountRecompiling the TypeScript sources into distRunning database migrations to apply the schemaFlushing the Redis cache before accepting requests

Checking your session…