a. Overview

During the semester you will build BoxOffice, a ticketing platform for concerts, games and festivals. It starts as one small service on your laptop and grows, lab after lab, into a system with an edge proxy, an API gateway, a cache, a replicated database, an event stream, observability, Kubernetes and an AI assistant. Each lab adds one component of the System Design Playground palette, and each lab ends with a measurement: system design is about trade-offs, and a trade-off is only real when you can put a number on it.

This first lab is short but important: a broken environment costs hours later, in the middle of a load test.

Before you start

Slides

Click the slides and use ← → to move through them; F goes full screen and P opens the presenter view, with the notes. Open the slides in a new tab

Where we are going

The diagram shows BoxOffice at the end of the semester. Do not worry about the details: every box has its own lab, and the number in each label says which one.

flowchart LR
    user([Fan / k6]) --> edge["edge<br/>Nginx · lab 3"]
    edge --> gw["gateway<br/>lab 4"]
    gw --> auth["auth<br/>lab 4"]
    gw --> catalog["catalog ×3<br/>lab 1"]
    gw --> inventory["inventory<br/>lab 6"]
    gw --> order["order<br/>lab 7"]
    gw --> assistant["assistant<br/>lab 12"]
    catalog --> redis[("redis<br/>lab 5")]
    catalog --> db[("db<br/>PostgreSQL")]
    inventory --> pgb["pgbouncer<br/>lab 6"] --> db
    inventory --> replica[("db-replica<br/>lab 6")]
    order --> kafka[["kafka<br/>lab 7"]]
    kafka --> notification["notification<br/>lab 7"]
    order --> payment["payment<br/>lab 9"]

BoxOffice services and ports

Every lab — and every team project — uses the names below. Do not rename them: the configuration files, the k6 scripts and the next labs assume them. A service listens on the same port inside its container and on your machine, so http://catalog:8082 (from another container) and http://localhost:8082 (from your terminal) reach the same service.

Application services (one folder each under services/):

Infrastructure (official images, configuration under infra/):

Conventions shared by all services:

Environment variables (the same name everywhere; defaults in parentheses):

Headers that cross service boundaries:

1. Install the tools

The table lists what each tool is for; the tabs below show how to install them on each system. k6 is a single binary¹; Docker Compose comes with Docker Desktop or as a plugin of Docker Engine².

brew install --cask docker          # Docker Desktop (or OrbStack: brew install --cask orbstack)
brew install --cask temurin@21      # Eclipse Temurin JDK 21
brew install maven uv k6 kubectl kind jq git
uv python install 3.12              # Python is managed by uv, not by Homebrew or pip

# Docker Engine + Compose plugin (official convenience script) and run docker without sudo
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker "$USER" && newgrp docker

# JDK 21, Maven, tools
sudo apt-get update
sudo apt-get install -y openjdk-21-jdk maven git jq curl

# uv (Python package and project manager) and Python 3.12
curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.12

# k6 (official APT repository)
sudo gpg -k
sudo gpg --no-default-keyring --keyring /usr/share/keyrings/k6-archive-keyring.gpg \
  --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D69
echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main" \
  | sudo tee /etc/apt/sources.list.d/k6.list
sudo apt-get update && sudo apt-get install -y k6

# kubectl and minikube
sudo snap install kubectl --classic
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube && rm minikube-linux-amd64

docker run --rm -i -v "$PWD":/w -w /w -e BASE_URL=http://host.docker.internal:8888 grafana/k6 run load/hello.js

2. Check your environment

Save the script below as scripts/check-env.sh in your repository (next step) and run it. Every line must say ok.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

#!/usr/bin/env bash
# BoxOffice labs: checks that every tool is installed and prints its version.
# Usage: bash scripts/check-env.sh
set -u
missing=0

check() {            # check <label> <command line>
  local label="$1" cmd="$2" out
  if ! command -v "${cmd%% *}" >/dev/null 2>&1; then
    printf '  MISS  %-9s not found\n' "$label"; missing=$((missing + 1))
  elif out=$(eval "$cmd" 2>&1); then
    printf '  ok    %-9s %s\n' "$label" "$(echo "$out" | head -n 1)"
  else
    printf '  FAIL  %-9s %s\n' "$label" "$(echo "$out" | head -n 1)"; missing=$((missing + 1))
  fi
}

echo "Tools"
check git      "git --version"
check docker   "docker --version"
check compose  "docker compose version"
check java     "java -version"
check maven    "mvn -v"
check uv       "uv --version"
check k6       "k6 version"
check kubectl  "kubectl version --client"
check jq       "jq --version"
check curl     "curl --version"

echo "Kubernetes (lab 10): kind OR minikube is enough"
if command -v kind >/dev/null 2>&1 || command -v minikube >/dev/null 2>&1; then
  command -v kind >/dev/null 2>&1 && echo "  ok    kind      $(kind version 2>&1 | head -n 1)"
  command -v minikube >/dev/null 2>&1 && echo "  ok    minikube  $(minikube version --short 2>&1 | head -n 1)"
else
  echo "  MISS  kind / minikube"; missing=$((missing + 1))
fi

echo "Checks"
java_major=$(java -version 2>&1 | head -n 1 | sed -E 's/[^"]*"([0-9]+).*/\1/')
if [ "${java_major:-0}" -ge 21 ] 2>/dev/null; then
  echo "  ok    JDK $java_major (21 or newer)"
else
  echo "  MISS  JDK 21 or newer (found: ${java_major:-none})"; missing=$((missing + 1))
fi
# Python is installed and managed by uv (uv python install 3.12)
if py=$(uv python find '>=3.12' 2>/dev/null); then
  echo "  ok    Python $("$py" -c 'import platform; print(platform.python_version())') (via uv)"
else
  echo "  MISS  Python 3.12 or newer: run  uv python install 3.12"; missing=$((missing + 1))
fi
if docker info >/dev/null 2>&1; then
  echo "  ok    Docker daemon: $(docker info --format '{{.NCPU}} CPUs, {{.MemTotal}} bytes of memory')"
else
  echo "  MISS  Docker daemon is not running"; missing=$((missing + 1))
fi

echo
if [ "$missing" -eq 0 ]; then echo "All set."; else echo "$missing item(s) missing: fix them before lab 1."; fi

Your version numbers will differ; what matters is that nothing says MISS or FAIL.

3. Create your repository

All your lab work lives in one repository, called boxoffice, created by you on GitHub (private; you will add your project teammates later). The course repository has the reference skeleton and is where updates to the lab code are published; your repository is where your code and your measurements live.

mkdir boxoffice && cd boxoffice
git init -b main
mkdir -p services infra load results scripts

At the end of the semester it will look like this — each folder appears in the lab shown in the comment:

📁 boxoffice/
├──  docker-compose.yaml        # lab 1, grows in every lab
├──  .gitignore
├──  README.md                  # how to run your BoxOffice
├── 📁 services/
│   ├── 📁 catalog/               # lab 1  (Spring Boot, port 8082)
│   ├── 📁 auth/                  # lab 4  (Spring Boot, port 8081)
│   ├── 📁 gateway/               # lab 4  (Spring Cloud Gateway, port 8080)
│   ├── 📁 inventory/             # lab 6  (Spring Boot, port 8083)
│   ├── 📁 order/                 # lab 7
│   ├── 📁 notification/          # lab 7
│   ├── 📁 payment/               # lab 9
│   └── 📁 assistant/             # lab 12 (FastAPI)
├── 📁 infra/
│   ├──  nginx/nginx.conf       # lab 3  (edge)
│   ├── 📁 postgres/              # lab 6  (replication)
│   └── 📁 pgbouncer/             # lab 6
├── 📁 load/                      # k6 scripts, from lab 0
│   └──  hello.js
├── 📁 results/                   # your measurements: lab0.md, lab1.md, ...
├── 📁 scripts/
│   └──  check-env.sh
├── 📁 k8s/                       # lab 10
└── 📁 .github/workflows/         # lab 11

Add a .gitignore at the root:

# build output
target/
*.class
# IDEs and OS
.idea/
.vscode/
*.iml
.DS_Store
# local secrets: never commit them
.env
# k6 HTML reports are big; commit the JSON summaries and the tables in results/*.md
results/*.html

Then create the repository on GitHub, push, and keep committing at the end of every lab:

git add . && git commit -m "lab 0: environment"
git remote add origin git@github.com:<your-user>/boxoffice.git
git push -u origin main

4. Measure it: your machine's baseline

Every lab ends with a measurement, and this one sets the reference: how much can your laptop serve when the server does almost nothing? The target is a stock Nginx returning a small static page; any number you get later for BoxOffice will be lower, and the difference is the cost of your code, your database and your network hops.

Save the script as load/hello.js:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

// Lab 0: how fast is *your* machine? The target is a plain Nginx container.
//   docker run -d --rm --name hello -p 8888:80 nginx:1.30-alpine
//   k6 run -e VUS=10 load/hello.js
import http from 'k6/http';
import { check } from 'k6';

const BASE_URL = __ENV.BASE_URL || 'http://localhost:8888';

export const options = {
  vus: Number(__ENV.VUS || 10),          // closed model: N users, no think time
  duration: __ENV.DURATION || '20s',
  summaryTrendStats: ['avg', 'med', 'p(95)', 'p(99)', 'max'],
  thresholds: {
    http_req_failed: ['rate<0.01'],      // fewer than 1% errors
  },
};

export default function () {
  const res = http.get(`${BASE_URL}/`);
  check(res, { 'status is 200': (r) => r.status === 200 });
}

Start the target, run k6 with 1, 10 and 50 virtual users (VUs), then stop the target:

docker run -d --rm --name hello -p 8888:80 nginx:1.30-alpine
k6 run -e VUS=1  load/hello.js
k6 run -e VUS=10 load/hello.js
k6 run -e VUS=50 load/hello.js
docker stop hello

Your numbers depend on the machine. With Docker Desktop (macOS, Windows) every request also crosses the VM's port forwarding, so expect a few times less than on native Linux — about 15,000 req/s at 10 VUs on an 8-core Apple Silicon laptop.

Read the summary like this:

• http_reqs … /s is the throughput (requests per second, RPS).
• http_req_duration gives the latency distribution: med is the median (p50), p(95)/p(99) are the 95th/99th percentiles — 1 request in 100 is slower than p99.
• vus is the concurrency: each virtual user sends a request, waits for the answer, and sends the next one (a closed workload model).

Record the results in results/lab0.md:

# Lab 0 — baseline

Machine: <CPU model>, <cores> cores, <RAM> GB; Docker resources: <CPUs> CPUs, <GB> GB

| VUs | Throughput (req/s) | p50 (ms) | p95 (ms) | p99 (ms) | Errors |
|----:|-------------------:|---------:|---------:|---------:|-------:|
|   1 |                    |          |          |          |        |
|  10 |                    |          |          |          |        |
|  50 |                    |          |          |          |        |

Little's Law check (VUs ≈ throughput × average latency):
- 10 VUs: ____ req/s × ____ s = ____

5. First look at the playground

The System Design Playground simulates the same components you will build, under load, in seconds. Every lab embeds the scenario it is about to measure for real, so you can form a hypothesis before running k6.

Try it: press Run on the monolith scenario below (one app server, one SQL database). Raise the load until p99 jumps. Which component saturates first? Write down the answer — you will check it against your own catalog service in lab 2.

Troubleshooting

Clean up

docker rm -f hello 2>/dev/null || true     # the baseline target, if still running
docker image prune -f                      # optional: remove dangling images

Keep everything in boxoffice/: lab 1 starts from it.

Deliverable

• bash scripts/check-env.sh prints All set. (paste the output in results/lab0.md).
• Your boxoffice repository exists on GitHub with the folder layout, .gitignore, scripts/check-env.sh and load/hello.js, tagged lab0.
• results/lab0.md has the baseline table filled in (1, 10 and 50 VUs) and the Little's Law check.
• You ran the monolith scenario in the playground and wrote down which component saturates first.
• Quiz answered.

End state

At the end of this lab your repository contains (the lab's code/ overlay plus your results):

📁 boxoffice/
├──  .gitignore
├── 📁 load/
│   └──  hello.js
├── 📁 results/
│   └──  lab0.md
└── 📁 scripts/
    └──  check-env.sh

Next: Lab 1 — First service.