a. Visão geral

Durante o semestre você vai construir o BoxOffice, uma plataforma de venda de ingressos para shows, jogos e festivais. Ele começa como um pequeno serviço no seu notebook e cresce, lab após lab, até virar um sistema com proxy de borda, API gateway, cache, banco replicado, stream de eventos, observabilidade, Kubernetes e um assistente de IA. Cada lab acrescenta um componente da paleta do System Design Playground, e cada lab termina com uma medição: projeto de sistemas é feito de trade-offs, e um trade-off só é real quando você consegue colocar um número nele.

Este primeiro lab é curto, mas importante: um ambiente quebrado custa horas depois, no meio de um teste de carga.

Antes de começar

Slides

Clique nos slides e use ← → para navegar; F abre em tela cheia e P abre a visão do apresentador, com as notas. Abrir os slides em uma nova aba

Aonde vamos chegar

O diagrama mostra o BoxOffice no fim do semestre. Não se preocupe com os detalhes: cada caixa tem o seu lab, e o número em cada rótulo diz qual.

flowchart LR
    user([Fã / 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"]

Serviços e portas do BoxOffice

Todos os labs — e todos os projetos em equipe — usam os nomes abaixo. Não os renomeie: os arquivos de configuração, os scripts k6 e os próximos labs dependem deles. Um serviço escuta na mesma porta dentro do container e na sua máquina, então http://catalog:8082 (a partir de outro container) e http://localhost:8082 (a partir do seu terminal) chegam ao mesmo serviço.

Serviços de aplicação (uma pasta cada em services/):

Infraestrutura (imagens oficiais, configuração em infra/):

Convenções compartilhadas por todos os serviços:

Variáveis de ambiente (o mesmo nome em todo lugar; padrões entre parênteses):

Cabeçalhos que atravessam fronteiras entre serviços:

1. Instale as ferramentas

A tabela lista para que serve cada ferramenta; as abas abaixo mostram como instalá-las em cada sistema. O k6 é um único binário¹; o Docker Compose vem com o Docker Desktop ou como plugin do 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. Verifique o seu ambiente

Salve o script abaixo como scripts/check-env.sh no seu repositório (próximo passo) e execute-o. Toda linha deve dizer 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

As suas versões serão diferentes; o que importa é que nada diga MISS ou FAIL.

3. Crie o seu repositório

Todo o seu trabalho dos labs fica em um repositório, chamado boxoffice, criado por você no GitHub (privado; você adicionará os colegas de projeto depois). O repositório da disciplina tem o esqueleto de referência e é onde as atualizações do código dos labs são publicadas; o seu repositório é onde vivem o seu código e as suas medições.

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

No fim do semestre ele terá esta cara — cada pasta aparece no lab indicado no comentário:

📁 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

Acrescente um .gitignore na raiz:

# 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

Depois crie o repositório no GitHub, faça o push e continue fazendo commits ao fim de cada 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. Meça: a referência da sua máquina

Todo lab termina com uma medição, e esta define a referência: quanto o seu notebook consegue atender quando o servidor quase não faz nada? O alvo é um Nginx padrão devolvendo uma pequena página estática; qualquer número que você obtiver depois para o BoxOffice será menor, e a diferença é o custo do seu código, do seu banco e dos seus saltos de rede.

Salve o script como 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 });
}

Suba o alvo, rode o k6 com 1, 10 e 50 usuários virtuais (VUs) e depois pare o alvo:

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

Seus números dependem da máquina. Com o Docker Desktop (macOS, Windows) cada requisição também atravessa o encaminhamento de portas da VM, então espere algumas vezes menos do que no Linux nativo — cerca de 15.000 req/s com 10 VUs em um notebook Apple Silicon de 8 núcleos.

Leia o resumo assim:

• http_reqs … /s é a vazão (throughput, em requisições por segundo, RPS).
• http_req_duration dá a distribuição de latência: med é a mediana (p50), p(95)/p(99) são os percentis 95 e 99 — 1 requisição em 100 é mais lenta que o p99.
• vus é a concorrência: cada usuário virtual envia uma requisição, espera a resposta e envia a próxima (um modelo de carga fechado).

Registre os resultados em 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. Primeiro contato com o playground

O System Design Playground simula, sob carga e em segundos, os mesmos componentes que você vai construir. Cada lab incorpora o cenário que está prestes a medir de verdade, para você formar uma hipótese antes de rodar o k6.

Experimente: aperte Run no cenário monolith abaixo (um servidor de aplicação, um banco SQL). Aumente a carga até o p99 saltar. Qual componente satura primeiro? Anote a resposta — você vai confrontá-la com o seu próprio serviço catalog no lab 2.

Solução de problemas

Limpeza

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

Mantenha tudo em boxoffice/: o lab 1 começa dele.

Entrega

• bash scripts/check-env.sh imprime All set. (cole a saída em results/lab0.md).
• O seu repositório boxoffice existe no GitHub com a estrutura de pastas, o .gitignore, o scripts/check-env.sh e o load/hello.js, com a tag lab0.
• results/lab0.md tem a tabela de referência preenchida (1, 10 e 50 VUs) e a verificação da Lei de Little.
• Você rodou o cenário monolith no playground e anotou qual componente satura primeiro.
• Quiz respondido.

Estado final

Ao fim deste lab o seu repositório contém (o overlay code/ do lab mais os seus resultados):

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

Próximo: Lab 1 — Primeiro serviço.