Polar local environment

Local Environment Skill

Helps manage the Polar local development environment through the dev docker CLI. Use it to start, stop, debug, or reason about the local stack.

The two-part model

dev docker deliberately splits the stack so many worktrees can share one set of heavy infra:

• Shared infra — one copy per machine, Docker project polar-shared: postgres, redis, minio, tinybird, and optional prometheus/grafana. Postgres and redis publish no host ports; MinIO exposes 9000/9001 for browser uploads. Use dev docker exec <service> ... for services without host ports.
• Per-instance app stack — one per worktree, project polar-app-<N>: api, worker, web. Only api and web publish host ports, offset per instance so worktrees don't collide.

Knowing this prevents the most common confusion: there is no localhost:5432 for the database (it lives in the shared stack and is reached through dev docker exec db ...). MinIO does expose ports 9000/9001 for browser uploads and console access.

Instance auto-detection

dev docker auto-detects the instance for the current worktree, so -i is rarely needed. Priority:

1. POLAR_DOCKER_INSTANCE pinned in dev/docker/.env.docker (dev docker set-instance N)
2. CONDUCTOR_PORT env var → (port - 55000) / 10 + 1
3. The cross-worktree registry (~/.config/polar/docker-instances.json)
4. Otherwise the lowest free number, then registered

Run dev docker ports to see the resolved instance and its URLs (add --json for tooling). To wire this worktree into Claude Code's preview, run dev docker launch-json, which writes a per-instance .claude/launch.json with the correct ports (it's gitignored, so regenerate after set-instance).

When to use

• Start / stop / restart the local environment
• View logs or debug a service that won't come up
• Run several isolated worktree instances in parallel
• Understand the service architecture or find a service's real port
• Diagnose container or first-boot errors

Quick reference

Task	Command
Start full stack (background)	dev docker up -d
Start and block until healthy	dev docker up -d --wait
Start in foreground (stream logs)	dev docker up --no-detach
Rebuild with fresh base images	dev docker up -b --pull -d
Show this instance's ports/URLs	dev docker ports (--json for tooling)
Write Claude Code preview config	dev docker launch-json
Stop app stack	dev docker down
Stop app and shared infra	dev docker down --all
Follow logs	dev docker logs -f [service]
Print logs and exit	dev docker logs --no-follow [service]
Status	dev docker ps
Restart a service	dev docker restart <service>
Shell into a service	dev docker shell <service>
One-off command in a service	dev docker exec <service> <cmd>
Reset this instance	dev docker cleanup -f
Wipe ALL shared data	dev docker cleanup --all -f
List every instance	dev docker list
With monitoring	dev docker up --monitoring -d

Services

Service	Project	Host port (instance 0 / N)	Notes
api	polar-app-<N>	8000 / 8100+N	FastAPI; /healthz healthcheck
web	polar-app-<N>	3000 / 3100+N	Next.js; healthchecked
worker	polar-app-<N>	none	Background jobs
db	polar-shared	none (exec)	PostgreSQL; DB polar_dev_<N>
redis	polar-shared	none (exec)	Redis DB index = N
minio	polar-shared	9000, 9001	S3; buckets polar-s3-<N>; console at 9001
tinybird	polar-shared	none (exec)	Analytics
prometheus / grafana	polar-shared	none (exec)	--monitoring only

Discover the exact host ports for the current worktree with dev docker ports.

Instance port mapping

Only api and web get host ports: Port = Base + Instance (Base 8100 for api, 3100 for web) for instances 1–99. Instance 0 uses the legacy 8000 / 3000.

Instance	API	Web
0	8000	3000
1	8101	3101
2	8102	3102
5	8105	3105

Everything else is per-instance but not on a host port: database polar_dev_<N>, redis DB index <N>, buckets polar-s3-<N> / polar-s3-public-<N>. Reach them via dev docker exec <service> or docker exec polar-shared-<service>-1.

Rules index

Rule	Category	Description
service-architecture	Reference	Service details, ports, healthchecks
start-environment	Operations	Starting the stack (flags, --wait, --pull)
stop-environment	Operations	Stopping and cleanup (app vs shared)
manage-instances	Operations	Parallel worktree instances
view-logs	Debugging	Viewing service logs
shell-and-workflows	Operations	Shell access and common dev workflows
troubleshooting	Debugging	Common errors and fixes
payment-testing	Operations	Login codes, Stripe webhooks, backoffice