Docker and repeatable environments

Why this matters

Right now, running your app on a new machine means installing the right Node version, installing PostgreSQL, creating a database, running migrations, and setting environment variables — and discovering, some hours in, that the other machine has PostgreSQL 15 and one of your queries behaves differently. Today you package the whole stack so that a clean clone plus one command gives a running API and database at the exact versions you tested. That is the difference between "works on my machine" and software someone else can run.

The problem being solved

"Works on my machine" is not a joke about carelessness. It is a real statement: your app depends on far more than the files in your repository. It depends on a Node version, a PostgreSQL version, system libraries, environment variables, and a database that already has your schema in it. None of that is in Git, so none of it travels with your code.

There are two ways to fix this: write a long setup document and hope people follow it exactly, or ship the environment along with the code. Containers are the second option.

What a container actually is

A container is an ordinary process on your machine, started from a packaged filesystem and run with isolation so that it sees only that filesystem, its own process list, and its own network interface.

Read that again, because the common misconception matters: a container is not a virtual machine. There is no second operating system booting inside it. A VM emulates hardware and runs a full guest OS with its own kernel — gigabytes of image, tens of seconds to boot. A container shares your machine's kernel and simply runs a process whose view of the world has been fenced off. That is why containers start in well under a second and why a small one is tens of megabytes.

The consequence: the packaged filesystem contains everything above the kernel — the Node binary, system libraries, your code — so it is identical everywhere. What it cannot change is the kernel, which is why containers built for Linux run on macOS and Windows through a small Linux VM that Docker Desktop manages for you.

Image versus container

This is the distinction everything else rests on, and today's quiz asks it directly.

An image is a packaged filesystem and configuration, used to create containers. It is read-only, built once, and stored as a stack of layers. Its configuration includes the default command, the working directory, environment variables, and the port it expects to serve on. An image does nothing on its own; it is inert, like a .zip that also remembers how to be launched.

A container is a running (or stopped) instance created from an image: the image's filesystem plus a thin writable layer on top, with a process running inside. You can start ten containers from one image; they all see the same starting files and cannot see each other's writes.

docker images   # the inert packages you have built or pulled
docker ps       # the containers currently running
docker ps -a    # containers including stopped ones

The Dockerfile

A Dockerfile is the recipe for building an image: a list of instructions, each producing a layer.

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "src/server.js"]

Line by line: start from the official Node 22 image on Alpine Linux (small); work inside /app; copy only the dependency manifests; install exactly the versions in package-lock.json, skipping dev dependencies; copy the rest of the source; declare the port as documentation; and record the command that runs when a container starts.

The odd-looking part is copying package*.json before the source. Docker caches each layer and reuses it while its inputs are unchanged. Because your source changes far more often than your dependencies, this order means editing a route rebuilds in seconds instead of reinstalling every package.

Next to it, a .dockerignore — the same idea as .gitignore, deciding what is not copied in:

node_modules
.env
.git
test-results

Compose: services, networks, and volumes

Your app is two programs, so you need two containers that can find each other. Docker Compose describes a multi-container stack in one file, compose.yaml:

services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: maintenance
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 10

  api:
    build: .
    env_file: .env
    ports:
      - "3000:3000"
    depends_on:
      db:
        condition: service_healthy

volumes:
  db-data:

Three ideas in there:

• Services are the containers. Compose puts them on a private network and gives each a hostname equal to its service name. So inside the api container, the database is at db, not localhost: DATABASE_URL=postgresql://postgres:postgres@db:5432/maintenance. localhost inside a container means that container, which is the single most common Compose mistake.
• Ports map host to container. "3000:3000" means port 3000 on your machine reaches port 3000 inside. The database has no ports entry, so it is reachable by the API but not from outside — a good default.
• Volumes solve the fact that a container's writable layer is deleted with the container. A named volume (db-data) is storage managed by Docker that outlives any container, so your rows survive a restart. The health check plus condition: service_healthy makes the API wait until PostgreSQL is genuinely accepting connections, instead of crash-looping on startup.

Walkthrough: bring the stack up

docker compose up --build

[+] Running 3/3
 ✔ Network maintenance-tracker_default  Created
 ✔ Container maintenance-tracker-db-1   Healthy
 ✔ Container maintenance-tracker-api-1  Started

In another terminal, check state and logs, then prove the API answers:

docker compose ps
docker compose logs -f api
curl -i http://localhost:3000/api/equipment

Run your migrations inside the running API container — exec runs a command in a container that already exists:

docker compose exec api npm run migrate

Stop the stack:

docker compose down

down removes the containers and the network but keeps the named volume, so docker compose up again finds your data intact. Confirm that: create a record, down, up, and read it back.

Your turn

1. Write the Dockerfile and .dockerignore for your API. Build it: docker build -t maint-api . Confirm with docker images that maint-api is listed, and note its size.
2. Write compose.yaml with the db and api services, the named volume, and the health check.
3. Create .env with DATABASE_URL pointing at the db host, and confirm .env is in both .gitignore and .dockerignore. Commit a .env.example with the keys and dummy values instead.
4. Run docker compose up --build, then curl a route to prove the API answers.
5. Run migrations with docker compose exec, create one record through your API, then down and up again and read the record back. That round trip is your proof the volume works.
6. Write docs/runbook.md with four sections you have personally run: start, stop, logs, reset data (docker compose down -v, with the warning written next to it).
7. Final test: git clone your repo into a fresh folder, copy .env.example to .env, and run docker compose up --build. If that is not enough, your runbook is incomplete — fix it now.

Common pitfalls

• Using localhost for the database inside a container. It means the container itself. Use the service name, db.
• Copying the whole project before npm ci. Every source edit then reinstalls all dependencies. Copy package*.json first.
• Forgetting the volume. Without it, docker compose down silently discards the entire database, and you conclude the app is broken.
• Committing .env. Commit .env.example instead. Secrets in Git history outlive the commit that removed them.

Verify it yourself

Open today's reference, Docker's Get started guide.

1. Find where it explains the difference between an image and a container, and compare its wording to this lesson's. Write the definition of an image in your own words in docs/runbook.md.
2. Find what docker compose down does to volumes by default, and confirm the -v behaviour this lesson warned about. Quote the documented sentence next to that command in your runbook.