🐳 Weekend Project: Containerize a Full-Stack App with Docker Compose

The Goal

Build a repository that a stranger can run without knowing a single thing about your stack. They clone it, copy one example env file, type docker compose up, and thirty seconds later a working app answers at http://localhost:8080. Behind that one port sit four cooperating containers: an Nginx container serving your compiled React bundle and proxying /api calls, an Express container running your API, a Postgres container holding the data, and a Redis container for caching and sessions. They find each other by name, start in the right order, and the database keeps its data even when every container is destroyed and rebuilt.

The magic word is reproducibility. A container bundles your code together with the exact operating system libraries, language runtime, and dependencies it needs, frozen into an image. That image runs identically on your laptop, your teammate's, the CI runner, and the production server — because it is identical. Docker Compose is the conductor: one declarative file describes every service, every connection, and every volume, and Compose makes it so.

Prerequisites

This is the Week 11 capstone, so it assumes the Docker fundamentals you built up all week — images versus containers, the Dockerfile instruction set, volumes, and networks — plus a working full-stack app to wrap. Before you start, make sure you're comfortable with:

You'll need Docker Desktop (macOS/Windows) or Docker Engine (Linux) installed, with the Compose v2 plugin — check both at once:

# Docker Engine version
docker --version
# => Docker version 27.x.x

# Compose v2 is a SUBCOMMAND now: "docker compose" (a space), not "docker-compose"
docker compose version
# => Docker Compose version v2.x.x

Required Features Checklist

These are the non-negotiables. Every one is achievable with plain Docker and Compose — no orchestration platform required. Tick each off as you go.

The Architecture

Four services, one internal network, one door to the outside world. Only the client publishes a port to your host (8080). The browser talks to Nginx; Nginx serves the React files and proxies any /api request across the internal network to the Express server. The server talks to Postgres and Redis. Crucially, the database and cache are never exposed to the host — they're only reachable from inside the Compose network, which is exactly how you want it in production.

Notice how each container is addressed by its service name. The server's database URL is postgres://...@db:5432/... — literally the word db, the service's name in compose.yaml. Compose runs a tiny DNS server on the internal network so db, redis, and server resolve to the right container automatically. You never hardcode an IP address.

The other big idea is the multi-stage build. Your client image is built in two phases: a heavyweight Node stage compiles the app, then a featherweight Nginx stage receives only the finished files. The Node toolchain — hundreds of megabytes — is thrown away. The image you ship is just Nginx plus a folder of static assets.

Project Structure

Two folders — one per service you build — plus the Compose files and env at the repo root. Postgres and Redis need no folders of their own; you pull them ready-made from official images. Each build context gets its own Dockerfile and .dockerignore.

fullstack-app/
├── compose.yaml              <-- the production topology (committed)
├── compose.override.yaml     <-- dev-only tweaks, auto-merged (committed)
├── .env                      <-- real secrets (NEVER committed)
├── .env.example              <-- a safe template to copy (committed)
├── .gitignore                <-- ignores .env, node_modules
├── client/                   <-- React (Vite) single-page app
│   ├── Dockerfile            <-- multi-stage: build → Nginx
│   ├── nginx.conf            <-- serve SPA + proxy /api to the server
│   ├── .dockerignore
│   ├── package.json
│   └── src/
└── server/                   <-- Express API
    ├── Dockerfile            <-- multi-stage: deps → non-root runtime
    ├── .dockerignore
    ├── package.json
    └── src/
        └── server.js         <-- includes a GET /health route

Stage 1 — The Client Image (React → Nginx)

Your React app is source code the browser can't run directly — it has to be compiled into plain HTML, CSS, and JavaScript first. So the client image has two jobs that call for two very different tools: a Node environment to build, and a web server to serve. A multi-stage Dockerfile does both in one file and ships only the second.

Create client/Dockerfile:

# syntax=docker/dockerfile:1

# --- Stage "base": install dependencies (shared by dev + build) ---
FROM node:20-alpine AS base
WORKDIR /app
# Copy ONLY the manifests first so this layer is cached until deps change.
COPY package*.json ./
RUN npm ci

# --- Stage "build": compile the React app into static files ---
FROM base AS build
COPY . .
RUN npm run build          # Vite outputs to /app/dist

# --- Stage "runtime": a tiny, non-root Nginx that serves /dist ---
FROM nginxinc/nginx-unprivileged:1.27-alpine AS runtime
# nginx-unprivileged already runs as a non-root user and listens on 8080.
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 8080
# The base image's default CMD starts nginx in the foreground — nothing to add.

The COPY --from=build is the hinge of the whole file: it reaches into the finished build stage and lifts out only the dist folder. Everything else from that stage — Node, npm, node_modules, your source — is left behind and never ships.

Now the Nginx config. A single-page app needs two behaviors: serve index.html for any route the React router owns (the try_files ... /index.html fallback), and forward API calls to the Express service so the browser only ever talks to one origin.

# client/nginx.conf
server {
    listen 8080;
    server_name _;

    # Serve the compiled SPA; fall back to index.html for client-side routes.
    location / {
        root /usr/share/nginx/html;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    # Proxy API calls to the "server" service by name over the Compose network.
    location /api/ {
        proxy_pass http://server:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Stage 2 — The Server Image (Express)

The API image is simpler — Node is the runtime, so there's nothing to compile. But we still use multiple stages for two wins: install all dependencies for a dev stage with hot reload, and install only production dependencies for a lean runtime that runs as a non-root user.

Create server/Dockerfile:

# syntax=docker/dockerfile:1

# --- Stage "base": shared workdir + manifests ---
FROM node:20-alpine AS base
WORKDIR /app
COPY package*.json ./

# --- Stage "dev": ALL deps (incl. nodemon) for hot reload ---
FROM base AS dev
RUN npm ci
COPY . .
USER node                  # drop root even in development
EXPOSE 3000
CMD ["npm", "run", "dev"]  # e.g. "nodemon src/server.js"

# --- Stage "prod-deps": production dependencies ONLY ---
FROM base AS prod-deps
RUN npm ci --omit=dev      # skips devDependencies → smaller image

# --- Stage "runtime": the lean, non-root production image ---
FROM node:20-alpine AS runtime
ENV NODE_ENV=production
WORKDIR /app
COPY --from=prod-deps /app/node_modules ./node_modules
COPY . .
USER node                  # run as the built-in unprivileged "node" user
EXPOSE 3000
CMD ["node", "src/server.js"]

The order of instructions is deliberate. Copying package*.json and running npm ci before copying the rest of the source means Docker caches the expensive dependency install as its own layer. Change a line in server.js and the next build reuses the cached node_modules layer, rebuilding in seconds instead of reinstalling everything.

Your API needs a health route so Compose can tell when it's truly ready to serve traffic. Add this to server/src/server.js:

// A trivial liveness probe the container's healthcheck will hit.
app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok', uptime: process.uptime() });
});

Stage 3 — Wire It Up with compose.yaml

This is the keystone. One declarative file names every service, tells Compose how to build or pull it, connects them, and describes health and persistence. Modern Compose needs no version: key — that field is obsolete and Compose warns if you include it.

Create compose.yaml at the repo root:

# compose.yaml — the production topology. No "version:" key needed.
name: fullstack-app

services:
  client:
    build:
      context: ./client        # uses the multi-stage Dockerfile's final stage
    image: fullstack-client:latest
    ports:
      - "8080:8080"            # the ONLY service exposed to your host
    depends_on:
      server:
        condition: service_healthy
    restart: unless-stopped

  server:
    build:
      context: ./server
      target: runtime          # build the lean production stage
    image: fullstack-server:latest
    environment:
      NODE_ENV: production
      PORT: 3000
      # Reach the DB and cache by SERVICE NAME — Compose DNS resolves them.
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
      REDIS_URL: redis://redis:6379
    depends_on:
      db:
        condition: service_healthy   # wait until Postgres is READY, not just up
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--spider", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s        # grace time while the app boots
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - db-data:/var/lib/postgresql/data   # named volume → durable data
    healthcheck:
      # Double $$ escapes Compose interpolation so the SHELL expands the vars.
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    command: ["redis-server", "--save", "60", "1", "--loglevel", "warning"]
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

# Named volumes live independently of any container's lifecycle.
volumes:
  db-data:
  redis-data:

Three ideas in this file carry the whole project — worth reading slowly.

1. Service-name networking

Compose puts every service on one private network and gives each a DNS name equal to its service key. That's why the server's DATABASE_URL points at @db:5432 and not an IP: db resolves to the Postgres container. Change the service name and the hostname changes with it. Because db and redis publish no host ports, nothing outside the network can reach them — only the server can, exactly as it should be.

2. Health-check-gated depends_on

A plain depends_on: [db] only waits for the database container to start — not for Postgres to finish its own boot and accept connections. Your server would race ahead and crash on "connection refused." The fix is condition: service_healthy: Compose runs each service's healthcheck and holds dependents in the gate until the check passes. The server waits for db and redis to be genuinely ready; the client waits for the server. Startup becomes an orderly chain instead of a race.

3. A named volume for persistence

Containers are disposable — delete one and everything written inside it vanishes. That's fine for stateless app code, fatal for a database. Mounting the named volume db-data at Postgres's data directory stores the files outside the container, managed by Docker. Run docker compose down and back up, rebuild the image, swap Postgres versions — the data is still there. Only an explicit docker compose down -v removes it.

Stage 4 — Dev Mode & Hot Reload

The production images are sealed on purpose: source is baked in at build time, so editing a file changes nothing until you rebuild. Great for shipping, miserable for coding. Development wants the opposite — your edits reflected the instant you save. The answer is a bind mount plus a dev server, layered on with an override file that Compose merges automatically.

Create compose.override.yaml:

# compose.override.yaml — dev-only tweaks, auto-merged over compose.yaml.
services:
  client:
    build:
      target: base            # stop at the Node stage; run Vite's dev server
    command: ["npm", "run", "dev", "--", "--host", "0.0.0.0"]
    ports:
      - "5173:5173"           # Vite's dev port, with HMR
    volumes:
      - ./client:/app         # bind-mount live source into the container
      - /app/node_modules     # keep the image's node_modules, don't shadow it
    environment:
      NODE_ENV: development

  server:
    build:
      target: dev             # the "dev" stage: all deps + nodemon
    command: ["npm", "run", "dev"]
    ports:
      - "3000:3000"           # expose the API directly for curl/Postman
    volumes:
      - ./server:/app
      - /app/node_modules
    environment:
      NODE_ENV: development

Two mounts, working together. ./server:/app maps your project folder over the container's /app, so a saved change appears inside instantly and nodemon restarts the server. The second, /app/node_modules, is an anonymous volume that shields the container's own installed dependencies from being hidden by your host folder — without it, your (possibly empty or platform-mismatched) local node_modules would shadow the good one baked into the image.

# Development (override merged automatically):
docker compose up

# Production (base file ONLY — override ignored):
docker compose -f compose.yaml up -d

Stage 5 — Slim It Down & Secure It

A working stack isn't a finished one. Two things separate a hobby setup from a professional one: small images (faster builds, faster deploys, smaller attack surface) and clean secret handling (nothing sensitive in Git, nothing sensitive baked into a layer).

A .dockerignore in every context

When you run docker build, Docker copies the whole build context to the daemon before running the Dockerfile. Ship your entire local node_modules and .git and that copy is slow, the cache busts constantly, and secrets can leak into the image. A .dockerignore — same syntax as .gitignore — keeps the context lean. Put one in client/ and server/:

# client/.dockerignore  and  server/.dockerignore
node_modules
npm-debug.log
dist
build
coverage
.git
.gitignore
.env
.env.*
Dockerfile
.dockerignore
.DS_Store

Ignoring node_modules is the big one: you want the image to run its own npm ci, not inherit your host's possibly-mismatched binaries. Ignoring .env guarantees a stray secrets file can never be copied into a layer.

Env files: a template you commit, secrets you don't

Compose reads a .env file in the project root automatically and substitutes ${VAR} references in compose.yaml. Commit a template so teammates know which variables exist; keep the real .env out of Git.

# .env.example  (committed — safe placeholder values)
POSTGRES_USER=appuser
POSTGRES_PASSWORD=change-me-in-a-real-env
POSTGRES_DB=appdb

# .gitignore
node_modules/
.env

New teammates run one line to get started:

cp .env.example .env      # then edit .env with real secrets, never commit it

Squeezing the images

You've already done most of the work; here's the checklist that makes it deliberate:

Measure your results — the numbers are motivating:

# List image sizes; the client should be tens of MB, not hundreds
docker images fullstack-client fullstack-server

# See the layers and where the bytes went
docker history fullstack-server:latest

REPOSITORY          TAG      SIZE
fullstack-client    latest   26.4MB
fullstack-server    latest   198MB

Stage 6 — Run & Verify

Time to bring it online. From the repo root, with your .env in place:

# Build images and start the whole stack (override merges → dev mode)
docker compose up --build

# ...or run detached (in the background) and follow logs separately
docker compose up --build -d
docker compose logs -f

Watch the startup order in the logs: db and redis report healthy, then the server boots, then the client comes up. That ordering is your health-check gates doing their job. Check the running services and their health at a glance:

docker compose ps
# STATE should read "running (healthy)" for db, redis, and server

Now exercise it. In dev mode the client is on Vite's port and the API is exposed directly:

# The app in the browser (dev):
#   http://localhost:5173

# Hit the API's health route straight through:
curl http://localhost:3000/health
# => {"status":"ok","uptime":12.3}

For the production shape — Nginx serving the bundle and proxying /api behind a single port — run the base file only:

docker compose -f compose.yaml up --build -d

# Everything behind ONE door now:
#   App:            http://localhost:8080
#   API (proxied):  http://localhost:8080/api/health

docker compose down          # stops + removes containers, KEEPS volumes
docker compose up -d          # fresh containers, same db-data volume
# → your row is still there

A few commands you'll lean on constantly while iterating:

docker compose logs -f server        # tail one service's logs
docker compose exec server sh        # open a shell inside a running container
docker compose exec db psql -U appuser -d appdb   # a psql prompt in the DB
docker compose restart server        # bounce one service
docker compose down                  # stop everything (data volumes survive)

Stretch Goals

Required build done with time left? Push it toward production. Pick whatever excites you — none are needed to pass the rubric.

CI starter — validate and build on every push

# .github/workflows/docker.yml
name: Docker Build

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate the Compose file
        run: docker compose config

      - name: Build all images
        run: docker compose build

Self-Check Rubric

Before you call this done, grade yourself. Aim to answer "yes" to everything in the first two columns — the stretch column is bonus.

Summary

This project is proof that Week 11 stuck. You crossed from "here's a fifteen-step setup guide, good luck" to "clone it and type one command." The moves you practiced — multi-stage builds, non-root users, service-name DNS, health-gated startup, named volumes, an auto-merged dev override, and a tight .dockerignore — are the everyday grammar of shipping software the way professional teams do. Your app now runs the same on every machine because it is the same, everywhere.

📚 Additional Resources

• Docker — Compose overview
• Docker — The Compose file specification
• Docker — Multi-stage builds
• Docker — Dockerfile reference
• Docker — Building best practices
• Docker — Compose healthcheck & depends_on conditions

🚀 What's Next?

Your app is packaged and portable — but is it correct? So far you've verified it by hand, clicking and curling. That doesn't scale, and it doesn't catch the bug you introduce next Tuesday. Week 12 opens exactly there: the next lesson, Testing Principles, lays the foundation for automated tests — why they matter, what to test, and how a good test suite lets you change code fearlessly. The containerized app you just built is the perfect thing to point that new safety net at.