descrybe/docs/docker.md

Docker Compose (Postgres only)

One file: 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).

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):

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 (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:

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:

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:

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

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