Docker: packaging your app

The "works on my machine" problem

Your API works on your laptop. On the server it crashes, because the server has an older Node.js, a missing library or a different setting. Docker fixes this by shipping the app with its environment. If the container runs on your laptop, the same container runs on the server.

Image and container

An image is a read-only package: a small Linux system, the runtime (for example Node.js), your code and its dependencies. A container is a running copy of an image, with its own processes and network. You can start many containers from one image, and stop and throw them away at any time.

A Dockerfile for a Node.js API

# Stage 1: build
FROM node:24-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 2: run
FROM node:24-slim
ENV NODE_ENV=production
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

1. FROM picks the base image. node:24-slim is a small Debian image with a Node.js LTS version. Always pin a version; :latest can change under you.
2. COPY package*.json and RUN npm ci come BEFORE COPY . . so Docker can reuse the installed packages (its layer cache) when only your code changes. Builds go from minutes to seconds.
3. Multi-stage: the first stage compiles; the second copies only the result. The final image is smaller and has fewer tools an attacker could use.
4. USER node runs the app as a normal user, not root, so a bug in your app cannot take over the whole container as easily.
5. CMD is the command that runs when the container starts.

# .dockerignore: files Docker must NOT copy into the image
node_modules
.git
.env
dist
*.log

Build, run and inspect

docker build -t notes-api:1.4.0 .                 # build an image from the Dockerfile here
docker run -d -p 8080:3000 --env-file .env --name notes notes-api:1.4.0
docker ps                                          # list running containers
docker logs -f notes                               # follow the container's logs
docker stop notes && docker rm notes               # stop and remove it

Ports: a container has its own network, so your app listening on port 3000 inside it is not reachable until you publish the port with -p host:container. Volumes: a container's files disappear when it is removed. A volume is storage that lives outside the container, so database files survive restarts and upgrades.

Docker Compose: app + Postgres + Redis

# compose.yaml (local development only)
services:
  api:
    build: .
    ports:
      - "8080:3000"
    environment:
      DATABASE_URL: postgres://app:devpass@db:5432/notes
      REDIS_URL: redis://cache:6379
    depends_on:
      - db
      - cache
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: devpass
      POSTGRES_DB: notes
    volumes:
      - pgdata:/var/lib/postgresql/data
  cache:
    image: redis:7
volumes:
  pgdata:

A registry is a store for images, like an app store for containers. Docker Hub, GitHub Container Registry (ghcr.io), AWS ECR and Google Artifact Registry are common. Your CI builds the image once, pushes it with a version tag, and every server pulls exactly that image.