| name | polar-local-environment |
| description | This skill should be used when setting up or managing Polar local development environment with Docker. |
| license | MIT |
| metadata | {"author":"polar","version":"1.1.0"} |
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:
POLAR_DOCKER_INSTANCE pinned in dev/docker/.env.docker (dev docker set-instance N)CONDUCTOR_PORT env var → (port - 55000) / 10 + 1- The cross-worktree registry (
~/.config/polar/docker-instances.json)
- 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
