Claude Cursor Skill

polar-local-environment

This skill should be used when setting up or managing Polar local development environment with Docker.

LLM Mart · 0 points · 9 views 0 listing impressions 0 install-command copies
Download fcakyon-claude-codex-settings-plugins_polar-skills_skills_polar-local-environment-0dbec38.zip · 15 KB

Install

skills CLI npx skills add https://github.com/fcakyon/claude-codex-settings/tree/main/plugins/polar-skills/skills/polar-local-environment
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install fcakyon-claude-codex-settings@llmmart
Git git clone https://github.com/fcakyon/claude-codex-settings.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole fcakyon/claude-codex-settings collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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 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
Files (claude-codex-settings)
  • rules
    • manage-instances.md 2.7 KB
      Loading…
    • payment-testing.md 6.2 KB
      Loading…
    • service-architecture.md 3.1 KB
      Loading…
    • shell-and-workflows.md 2.6 KB
      Loading…
    • start-environment.md 3 KB
      Loading…
    • stop-environment.md 1.6 KB
      Loading…
    • troubleshooting.md 6 KB
      Loading…
    • view-logs.md 1.9 KB
      Loading…
  • SKILL.md 5.3 KB
    ---
    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 |
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.