A reproducible test environment

By the end of this chapter you have the lab’s repository layout, a compose.yaml that starts PostgreSQL, Prometheus, and Grafana with one command, and — the part that actually makes results comparable — a written record of every variable that affects a measurement. The application itself arrives in chapter 04; this chapter builds the ground it stands on.

Prerequisites: Docker Engine with Compose v2 (docker compose version), roughly 4 GB of free memory for containers, and nothing else listening on ports 5432, 9090, or 3000.

Why the environment comes before the tests

A load-test number is a property of a system, not of code. The same Order API produces different p99 latencies depending on whether PostgreSQL has two vCPUs or eight, whether the buffer cache is warm, whether the dataset fits in RAM, and whether the load generator shares the machine. If any of those differ between two runs, the runs measure different systems and comparing them is noise.

That is why this series treats the environment as code plus a checklist: the Compose file pins the software, and a short document — written before each significant run — pins everything else.

Repository layout

The whole series lives in one directory:

1
orders-perf-lab/
2
├── .env
3
├── compose.yaml
4
├── build.gradle.kts
5
├── settings.gradle.kts
6
├── gradle/                  # wrapper, added in chapter 04
7
├── db/
8
│   └── init/                # mounted into PostgreSQL at first boot
9
│       ├── 01-schema.sql    # chapter 04
10
│       └── 02-seed.sql      # chapter 05
11
├── prometheus/
12
│   └── prometheus.yml
13
├── grafana/
14
│   └── provisioning/
15
│       └── datasources/
16
│           └── prometheus.yml
17
└── src/
18
    ├── main/                # the Order API — chapter 04
19
    │   ├── java/in/o612/eng/orders/…
20
    │   └── resources/application.yml
21
    └── gatling/             # simulations — chapter 06
22
        ├── java/in/o612/eng/orders/load/…
23
        └── resources/data/…

The application runs on the host — via ./gradlew bootRun — and the infrastructure runs in containers. This is a deliberate trade-off: rebuilding and restarting a container on every code change would slow the experiment loop in chapters 09–11, where you will restart the API dozens of times. The cost is realism, and chapter 12 moves the same service into Kubernetes to close that gap. Record which mode each run used.

The Compose file

Create orders-perf-lab/compose.yaml:

1
name: orders-perf-lab
2

3
services:
4
  postgres:
5
    image: postgres:18-alpine
6
    environment:
7
      POSTGRES_DB: orders
8
      POSTGRES_USER: orders
9
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
10
    ports:
11
      - "5432:5432"
12
    volumes:
13
      - pgdata:/var/lib/postgresql
14
      - ./db/init:/docker-entrypoint-initdb.d:ro
15
    healthcheck:
16
      test: ["CMD-SHELL", "pg_isready -U orders -d orders"]
17
      interval: 5s
18
      timeout: 3s
19
      retries: 10
20

21
  prometheus:
22
    image: prom/prometheus:v3.7.0
23
    command:
24
      - --config.file=/etc/prometheus/prometheus.yml
25
      - --storage.tsdb.retention.time=7d
26
    ports:
27
      - "9090:9090"
28
    volumes:
29
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
30
    extra_hosts:
31
      - "host.docker.internal:host-gateway"
32

33
  grafana:
34
    image: grafana/grafana:12.2.0
35
    environment:
36
      GF_AUTH_ANONYMOUS_ENABLED: "true"
37
      GF_AUTH_ANONYMOUS_ORG_ROLE: Admin
38
      GF_AUTH_DISABLE_LOGIN_FORM: "true"
39
    ports:
40
      - "3000:3000"
41
    volumes:
42
      - ./grafana/provisioning:/etc/grafana/provisioning:ro
43

44
volumes:
45
  pgdata:

And .env, which Compose reads automatically:

1
# Local lab only. Never commit real credentials.
2
POSTGRES_PASSWORD=orders-local-pw

Three details carry weight here:

• db/init/ is mounted read-only into PostgreSQL’s init directory. Files there run once, when the data volume is empty — schema in chapter 04, seed data in chapter 05. Re-running them means destroying the volume, which is exactly the reset semantics you want: docker compose down -v gives you a known-empty database.
• The volume mounts at /var/lib/postgresql, not /var/lib/postgresql/data. From PostgreSQL 18 the image stores data in a major-version subdirectory (PGDATA=/var/lib/postgresql/18/docker) and refuses to start if a mount sits at the old /var/lib/postgresql/data path — the single change that makes this Compose file version-specific.
• extra_hosts: host-gateway lets Prometheus, inside its container, reach the Spring Boot app running on the host at host.docker.internal:8080. On Docker Desktop for Mac or Windows this hostname already exists; on Linux it needs the mapping above. Skip it and Prometheus scrapes nothing, silently.
• Anonymous Grafana admin is a lab shortcut. It must never appear in a shared environment; chapter 12 covers the access controls that apply when this stack leaves your laptop.

Prometheus scrape configuration

prometheus/prometheus.yml scrapes two targets: itself, and the application’s /actuator/prometheus endpoint (which chapter 03 adds):

1
global:
2
  scrape_interval: 5s
3
  evaluation_interval: 5s
4

5
scrape_configs:
6
  - job_name: prometheus
7
    static_configs:
8
      - targets: ["localhost:9090"]
9

10
  - job_name: order-api
11
    metrics_path: /actuator/prometheus
12
    static_configs:
13
      - targets: ["host.docker.internal:8080"]
14
        labels:
15
          application: order-api
16
          instance: local

The 5-second interval is finer than Prometheus defaults. For load tests you want resolution inside the run — a 15-second scrape can miss the beginning of a latency ramp. The cost is trivial at this scale. The application and instance labels matter later: when chapter 12 moves to Kubernetes and multiple pods report, they are what keep one pod’s metrics from being averaged into another’s.

Grafana datasource provisioning

grafana/provisioning/datasources/prometheus.yml wires Grafana to Prometheus so a dashboard works on first boot instead of after manual clicking:

1
apiVersion: 1
2
datasources:
3
  - name: Prometheus
4
    type: prometheus
5
    access: proxy
6
    url: http://prometheus:9090
7
    isDefault: true

Note the URL: Grafana reaches Prometheus by service name over the Compose network — prometheus:9090, not localhost. Inside a container, localhost is the container itself; this is the single most common Compose-networking mistake.

Start it, verify it

1
docker compose up -d
2
docker compose ps          # postgres healthy; prometheus and grafana up

Verification, not assumption:

1. curl http://localhost:9090/-/ready — Prometheus reports ready.
2. http://localhost:9090/targets — the order-api target will be DOWN (the app does not exist yet). That is expected now; it must be UP before any test run in chapter 07.
3. http://localhost:3000 — Grafana opens without a login prompt, with a Prometheus datasource under Connections → Data sources.
4. docker compose exec postgres psql -U orders -d orders -c 'select 1' — the database answers.

Why this laptop is not your production cluster

The lab controls the variables that make runs repeatable; it does not reproduce production. The differences that matter:

• Shared machine. The app, the database, Prometheus, and soon Gatling all compete for the same cores. Gatling itself can consume a CPU at high rates — when the client saturates, it stops measuring latency and starts adding to it. Chapter 07 shows how to check for this.
• No network distance. Loopback adds under a millisecond; a cloud availability zone adds more, and an internet path adds far more. Server-side latency transfers roughly; client-observed latency does not.
• Tiny, clean storage. A fresh NVMe-backed Docker volume is not a managed disk with IOPS limits, and fsync behaviour differs.
• No neighbours. Production VMs and Kubernetes nodes share hosts. Nothing here is throttled unless you throttle it.
• Cold caches until warmed. PostgreSQL’s shared buffers and the JVM’s JIT compiler both need warm-up — a configured, measured phase of every run, not an afterthought.

The numbers the lab produces answer “did this change make the service faster here?” They do not produce a production capacity figure. For that, the same method runs in a staging environment that resembles production — chapter 12.

The variables you must control

Every difference below is a confound — something that changes results without being the change you intended:

The run sheet

Before every significant test run, copy this checklist into a file named with the run’s date and purpose — runs/2026-09-26-baseline.md — and fill it in. Sixty seconds now is what makes “the regression appeared in October” diagnosable in December.

1
# Run sheet: <purpose>
2

3
- Git commit:
4
- App config changed since last run: (diff or "none")
5
- JVM flags: -Xmx:  GC:  other:
6
- Docker resources: CPUs:  Memory:
7
- Postgres: version, shared_buffers, max_connections
8
- Dataset: customers=  orders=  items=  (row counts, seed version)
9
- Simulation + injection profile:
10
- Warm-up / steady / cool-down durations:
11
- Load generator location and CPU headroom observed:
12
- Other significant load on the host:
13
- Result (p50/p95/p99/err% per endpoint, achieved throughput):
14
- Verdict vs SLO:

Milestone check: you should now have Prometheus and Grafana answering on their ports, a healthy empty PostgreSQL, and a runs/ directory with the template saved. Chapter 03 adds the application-side instrumentation that gives Prometheus something to scrape.