# Setup — standing the lab up (and stopping it safely)

Working directory for every command in this course: **your kafka-lab
checkout** (referred to as `kafka-lab/`). About one minute of work.

## 1. Point the lab at your Docker host

Open `kafka-lab/docker/.env` and check one line:

```bash
LAB_HOST_IP=localhost
```

- Docker on your own machine → `localhost`.
- Docker daemon on another machine → that machine's address.

## 2. Start the cluster

```bash
cd kafka-lab
scripts/up.sh
```

This starts 3 Kafka brokers (KRaft mode, no ZooKeeper), ksqlDB and Schema
Registry via `docker/docker-compose.yml`, then waits for the quorum. On
success it prints:

```
Cluster is up.  Bootstrap from your code : localhost:9092
```

If the command hangs at "Waiting for the KRaft quorum", see
`TROUBLESHOOTING.md` §1.

## 3. Create the course topics (idempotent — safe to re-run)

```bash
scripts/run.sh lab.AdminLesson
```

This compiles the `lessons` module and runs `lab.AdminLesson`, which
creates the **lab topics the Java/Spring exercises use** (`lab.spring.orders`,
its `.DLT`, `lab.spring.retries`, …). The CLI exercises create their own
`course.*` topics as they go, so this step is a health check as much as a
setup step. You will see it connect, list the three brokers, and create
topics (already-existing ones are reported as "nothing to do"). Keep this
command: any time you want to confirm the cluster is healthy, run it — it
is read-only against existing topics.

## 4. Sanity-check the CLI wrapper

```bash
scripts/k kafka-topics.sh --list
```

`scripts/k` runs any stock Kafka CLI tool inside the kafka-1 container
(`kafka-1:29092` internally). You will use it throughout. If you see the
topic list, the lab is ready. Record the version you are running:

```bash
docker exec kafka-1 /opt/kafka/bin/kafka-topics.sh --version
# 3.9.0 (the version every exercise in this pack was verified against)
```

## Pausing (data kept) — the normal way to stop

```bash
docker compose -f docker/docker-compose.yml stop
```

Containers stop; **all records and consumer offsets remain** (they live in
Docker volumes). Resume later:

```bash
docker compose -f docker/docker-compose.yml start
```

## ⚠ Destructive reset — only if you want a brand-new cluster

The repo's own teardown script **destroys all data**, including every record
you produced and every committed offset:

```bash
scripts/down.sh     # docker-compose down -v — volumes included
```

You never need this to finish the course. Run it only when you want to
replay the whole course on a fresh cluster — and expect every consumer
group in the exercises to behave as brand-new again (no committed offsets),
which is itself a lesson.

## What state does the course leave behind?

- Topics named `course.*` (small: a dozen records each) and the lab's own
  `lab.*` topics.
- Consumer groups named `course.*` with committed offsets.
- Docker volumes holding the broker data.

All of it is harmless and inspectable; nothing grows on its own once you
stop producing.
