gabrielmoreira 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. Usedev 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_INSTANCEpinned indev/docker/.env.docker(dev docker set-instance N)CONDUCTOR_PORTenv 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
| 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 |