🧰 Weekend Project: Version Control & Docker

The Brief & How to Work

Your goal is not to write a lot of application code — it's to build the environment and workflow around a small app so that it is reproducible, versioned, and continuously tested. The app itself can stay deliberately tiny: a backend that returns a health-check message, a frontend that displays it, and a database that proves the network wiring works.

Treat this like a professional would. Work in small, well-labelled Git commits. Do each unit of work on a branch, open a pull request, and merge it. Don't try to do everything at once — the milestones below are designed so each one leaves you with something that runs.

💡 Approach it methodically. Understand the goal, plan the pieces, build one milestone at a time, then review against the checklist. That "understand → plan → execute → review" loop (Polya's classic problem-solving steps) is exactly how experienced developers tackle unfamiliar setup work.

Milestone Roadmap

Five milestones take you from an empty folder to a continuously tested, containerized app. Each depends on the one before it.

Milestone 1 — Repository & Git Workflow

Start with a clean, well-structured repository and a branching habit you'll keep for the rest of the project.

Create the structure

mkdir weekend-stack && cd weekend-stack
git init
mkdir backend frontend
# a top-level README you'll fill in at Milestone 5
touch README.md docker-compose.yml

Add a real .gitignore

Never commit dependencies, build output, or secrets. A minimal but honest ignore file:

# dependencies
node_modules/
# build output
dist/
build/
# environment & secrets
.env
.env.local
# logs and OS cruft
*.log
.DS_Store

Adopt a feature-branch workflow

Keep main always working. Do each piece of work on a short-lived branch, then merge it back through a pull request.

# commit the skeleton on main
git add .
git commit -m "chore: scaffold repo structure and gitignore"

# start the first feature on its own branch
git switch -c feat/compose-stack

Milestone 2 — Compose the Stack

Now make three services run together with one command. We'll use a Node/Express backend, a static frontend, and a Postgres database — but the shape is identical if you swap in Python or PHP.

A tiny backend

backend/server.js — a single health-check endpoint. Modern syntax: const, arrow functions, and a route that reports the database host it was told to use.

const express = require('express');

const app = express();
const PORT = process.env.PORT || 4000;

app.get('/api/health', (req, res) => {
  res.json({
    status: 'ok',
    db: process.env.DB_HOST || 'not configured',
    time: new Date().toISOString(),
  });
});

app.listen(PORT, () => {
  console.log(`API listening on http://localhost:${PORT}`);
});

backend/package.json — declare the start scripts so the container knows how to run and test the app.

{
  "name": "backend",
  "version": "1.0.0",
  "scripts": {
    "start": "node server.js",
    "dev": "node --watch server.js",
    "test": "node --test"
  },
  "dependencies": {
    "express": "^4.19.2"
  }
}

Dockerfile for the backend

backend/Dockerfile — copy manifests first so Docker can cache the dependency layer.

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 4000
CMD ["npm", "start"]

Wire it together with Compose

docker-compose.yml — three services on one network. Note the modern Compose file needs no version: key. The backend reaches the database using the service name db as its hostname.

services:
  backend:
    build: ./backend
    ports:
      - "4000:4000"
    environment:
      DB_HOST: db
      DB_USER: appuser
      DB_PASSWORD: apppass
      DB_NAME: appdb
    depends_on:
      - db

  frontend:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./frontend:/usr/share/nginx/html:ro

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: apppass
      POSTGRES_DB: appdb
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

A frontend that proves the wiring

frontend/index.html — fetches the backend health check and shows it. This confirms the browser can reach the API.

<!DOCTYPE html>
<html lang="en">
<head><meta charset="UTF-8"><title>Weekend Stack</title></head>
<body>
  <h1>Weekend Stack</h1>
  <pre id="out">loading…</pre>
  <script>
    fetch('http://localhost:4000/api/health')
      .then((r) => r.json())
      .then((data) => {
        document.getElementById('out').textContent = JSON.stringify(data, null, 2);
      })
      .catch((err) => {
        document.getElementById('out').textContent = 'API unreachable: ' + err;
      });
  </script>
</body>
</html>

Bring it up

docker compose up --build

{
  "status": "ok",
  "db": "db",
  "time": "2026-07-30T12:00:00.000Z"
}

Milestone 3 — Dev Container

A dev container guarantees every teammate develops with the same Node version, extensions, and settings — no more "works on my machine." VS Code reads a .devcontainer/devcontainer.json and reopens your project inside a container.

{
  "name": "Weekend Stack",
  "dockerComposeFile": "../docker-compose.yml",
  "service": "backend",
  "workspaceFolder": "/app",
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ],
      "settings": {
        "editor.formatOnSave": true
      }
    }
  },
  "forwardPorts": [4000, 8080],
  "postCreateCommand": "npm install"
}

Open the folder in VS Code, then run Dev Containers: Reopen in Container from the command palette. VS Code builds (or reuses) the backend service, installs extensions inside it, and opens a terminal that lives in the container.

Milestone 4 — CI with GitHub Actions

Continuous Integration runs your checks automatically on every push, so a broken commit is caught before it reaches main. Create .github/workflows/ci.yml:

name: CI

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

jobs:
  backend:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: backend
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
          cache-dependency-path: backend/package-lock.json
      - run: npm ci
      - run: npm test

Add one small test so npm test actually verifies something. backend/health.test.js using Node's built-in test runner (no extra dependency):

const { test } = require('node:test');
const assert = require('node:assert');

test('health payload is well formed', () => {
  const payload = { status: 'ok', db: 'db' };
  assert.strictEqual(payload.status, 'ok');
  assert.ok(payload.db, 'db host should be set');
});

Commit, push your feature branch, and open a pull request. GitHub runs the workflow and shows a green check when it passes.

Milestone 5 — Document & Reflect

A project isn't done until someone else can run it. Write a README.md that a newcomer could follow cold.

# Weekend Stack

A minimal full-stack app used to practice Git, Docker Compose,
dev containers, and CI.

## Stack
- Backend: Node.js + Express
- Frontend: static HTML served by nginx
- Database: PostgreSQL

## Run it
```bash
docker compose up --build
```
- Frontend: http://localhost:8080
- API health: http://localhost:4000/api/health

## Develop
Open in VS Code and choose "Reopen in Container".

## Workflow
Feature branches → pull request → CI green → merge to `main`.

Reflect (write 4–6 sentences in the README)

• What was the hardest part to get working, and how did you diagnose it?
• Which milestone gave the biggest payoff for the effort?
• One thing you'd add next: automated end-to-end tests? A production Dockerfile? A staging deploy?

What Good Looks Like

Before you call it finished, compare your work against these standards. This is roughly how a reviewer or instructor would grade it.

Completion Checklist

Tick these off before you consider the weekend project done:

Summary & Quiz

📚 Further Reading

• Docker Compose documentation
• VS Code Dev Containers
• GitHub Actions documentation
• Feature-branch workflow (Atlassian)

🚀 What's Next?

You've closed out Module 2 with a reproducible, tested project. Next, in Module 3, we zoom back out to the web itself — how browsers, servers, HTTP, and the wider technology ecosystem fit together — so your future features rest on a solid mental model.