fcakyon/claude-codex-settings / plugins/polar-skills/skills/polar-local-environment
polar-local-environment
VerifiedThis skill should be used when setting up or managing Polar local development environment with Docker.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.3 KB |
| rules/manage-instances.md | markdown | 2.7 KB |
| rules/payment-testing.md | markdown | 6.2 KB |
| rules/service-architecture.md | markdown | 3.1 KB |
| rules/shell-and-workflows.md | markdown | 2.6 KB |
| rules/start-environment.md | markdown | 3.0 KB |
| rules/stop-environment.md | markdown | 1.6 KB |
| rules/troubleshooting.md | markdown | 6.0 KB |
| rules/view-logs.md | markdown | 1.9 KB |
SKILL.md
View on GitHub---
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:
1. `POLAR_DOCKER_INSTANCE` pinned in `dev/docker/.env.docker` (`dev docker set-instance N`)
2. The cross-worktree registry (`~/.config/polar/docker-instances.json`)
3. 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](rules/service-architecture.md) | Reference | Service details, ports, healthchecks |
| [start-environment](rules/start-environment.md) | Operations | Starting the stack (flags, `--wait`, `--pull`) |
| [stop-environment](rules/stop-environment.md) | Operations | Stopping and cleanup (app vs shared) |
| [manage-instances](rules/manage-instances.md) | Operations | Parallel worktree instances |
| [view-logs](rules/view-logs.md) | Debugging | Viewing service logs |
| [shell-and-workflows](rules/shell-and-workflows.md) | Operations | Shell access and common dev workflows |
| [troubleshooting](rules/troubleshooting.md) | Debugging | Common errors and fixes |
| [payment-testing](rules/payment-testing.md) | Operations | Login codes, Stripe webhooks, backoffice |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |