# Docker Compose (Postgres only)

One file: [`docker-compose.yml`](../docker-compose.yml). Compose runs **Postgres 16** on host port **5433** only. API, web, and worker stay on the host via `npm run setup` + `npm run dev` (see root [README.md](../README.md)).

## What starts

| Command | Services |
|---------|----------|
| `docker compose up -d` | Postgres (`descrybe-v2-postgres`) with `pg_isready` healthcheck |
| `npm run setup` | Ensures `.env`, starts Compose Postgres, runs goose migrate |
| `npm install && npm run dev` | Host API (:28471) + web (:28472) + worker |

Host DSN (matches Compose publish):

```text
postgres://descrybe:descrybe@localhost:5433/descrybe?sslmode=disable
```

`GET /healthz` = API liveness. `GET /readyz` needs the **host worker** (included in `npm run dev`).

## Prerequisites

- [Docker Desktop](https://docs.docker.com/desktop/) (Windows / macOS) **or** Docker Engine + Compose v2 (Linux)
- Node **≥ 20** and Go **1.25** on the host for `npm run setup` / `npm run dev`

## Windows (Docker Desktop)

1. Install Docker Desktop; prefer the **WSL2** backend (Settings → General).
2. Start Docker (whale icon), then from the repo in PowerShell:

```powershell
npm run setup
npm install
npm run dev
```

3. If **5433** is busy: stop the other Postgres/Compose project or change only the host side of `ports:` in `docker-compose.yml` (`"5433:5432"` → `"NEWport:5432"`) and update `DATABASE_URL` in `.env`.

## macOS (Docker Desktop)

1. Install Docker Desktop (Apple Silicon or Intel build as needed).
2. From Terminal:

```bash
npm run setup
npm install && npm run dev
```

Same ports and DSN as Windows. Home-directory clones are shared with Docker by default.

## Linux (Docker Engine)

1. Install Docker Engine and the Compose **v2** plugin (`docker compose version`).
2. Add your user to the `docker` group (re-login) or use `sudo`.
3. From the repo:

```bash
npm run setup
npm install && npm run dev
```

Optional: bind Postgres to loopback only with `"127.0.0.1:5433:5432"` if you do not want LAN exposure.

## Makefile

```bash
make up      # docker compose up -d
make down    # docker compose down
make setup   # npm run setup equivalent
```

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| `Bind for 0.0.0.0:5433 failed` | Another Compose/Postgres; `docker compose down` elsewhere or change host port |
| Postgres never healthy | `docker compose logs postgres`; wait for `pg_isready` |
| `/readyz` → 503 | Start host worker (`npm run dev` includes it; or `npm run dev:worker`). Read JSON `reason`. Compose does not run the worker. |
| Windows: Docker not running | Start Docker Desktop before `npm run setup` |