# Synapse-Time — Docker Quick Start

Uses Docker Compose **v2** (`docker compose`, with a space). A v1 note is at the bottom.
Run all commands from the project root (the folder containing `docker-compose.yml`).

---

## 1. First-time setup (in order)

```bash
# 1. Create your environment file and set the secrets
cp .env.example .env
#    then edit .env — change POSTGRES_PASSWORD, REDIS_PASSWORD, JWT_SECRET, SECRET_PEPPER
#    (and mirror the DB/Redis passwords inside DATABASE_URL / REDIS_URL)

# 2. Build the images and start everything
docker compose up -d --build

# 3. Confirm the API is up
curl http://localhost:8000/healthz            # -> {"status":"ok"}
curl http://localhost:8000/auth/setup-status  # -> {"needs_setup": true}

# 4. (optional) Load demo staff for the maker-checker / rostering walkthroughs
docker compose exec api-gateway python -m app.seed
```

Then open the portal:

- **http://localhost:3000** (or `http://<host-ip>:3000` from another machine)
- First visit shows **Set up administrator** — create your admin, and you're in.
  (Or go straight to `http://localhost:3000/setup`.)

---

## 2. After updating the application

**The key question: did the change touch the database schema** (new tables, columns,
or permissions)? That decides which command you run.

### A. Schema changed → recreate the database

Schema lives in `db/schema.sql`, which runs **once, on a fresh database volume**. So any
new table/column/permission needs the volume wiped:

```bash
docker compose down -v          # stop + DELETE the database volume
docker compose up -d --build    # rebuild images + start with a fresh schema
docker compose exec api-gateway python -m app.seed   # optional demo data
```

Then create your admin again at `/setup` (the wipe removes users too).

> ⚠️ `down -v` deletes all data. That's fine on a dev database; do **not** use it on
> production data you want to keep (see migrations note below).

### B. Code-only change → plain rebuild (keeps your data)

```bash
docker compose up -d --build
```

To rebuild just one service (e.g. after a backend-only change):

```bash
docker compose up -d --build api-gateway
docker compose up -d --build frontend
```

### How to tell which case you're in

- If you (or a change log) mention **new tables, columns, or permissions** → **A** (`down -v`).
- If it's UI tweaks, endpoint logic, styling, bug fixes with **no schema change** → **B**.
- Unsure on dev? **A is always safe** — it just rebuilds the DB from the current schema.

---

## 3. Everyday commands

```bash
docker compose ps                          # what's running + published ports
docker compose logs api-gateway --tail 30  # gateway logs (add -f to follow)
docker compose logs postgres --tail 30     # database/startup logs
docker compose restart api-gateway         # restart one service
docker compose down                        # stop everything (KEEPS data)
docker compose down -v                     # stop everything (DELETES data)
```

Health / state checks:

```bash
curl http://localhost:8000/healthz
curl http://localhost:8000/auth/setup-status
# see the API docs in a browser:  http://localhost:8000/docs
```

---

## 4. Troubleshooting (quick)

| Symptom | Cause | Fix |
|---|---|---|
| "Cannot save…" / generic failures | DB missing new columns/tables | `docker compose down -v && docker compose up -d --build` |
| Dropdowns empty (locations, etc.) | `GET` 500s on a missing column | same as above |
| "Cannot reach the API" | gateway down or not rebuilt | `docker compose logs api-gateway --tail 30` |
| Gateway exits immediately | missing `.env` value / bad `.env` | check the log traceback; verify `.env` |
| Setup screen won't show | an admin already exists | `curl …/auth/setup-status`; if `false`, `down -v` |
| Works locally, not from another PC | using `localhost` in the URL | use `http://<host-ip>:3000` |

Confirm the running gateway is healthy from inside the network:

```bash
docker compose exec frontend wget -qO- http://api-gateway:8000/healthz
```

---

## 5. Production data (not dev)

`down -v` is only acceptable when you can discard the database. For a real deployment,
schema changes should be applied as **versioned migrations** (e.g. Alembic in
`db/migrations/`) instead of wiping the volume, so data is preserved.

---

## 6. Using Docker Compose v1 (`docker-compose`, with a hyphen)

Older v1 has a `ContainerConfig` bug when recreating containers. If you're stuck on v1:

- Use **`docker-compose`** (hyphen) for every command.
- **Always `down` before `up`** — never `up`/`--force-recreate` on running containers:

```bash
docker-compose down -v --remove-orphans   # (omit -v to keep data)
docker-compose build
docker-compose up -d
```

Best fix is to install Compose v2 (`docker compose version` to check).
