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 |
rules/manage-instances.md
View on GitHub---
title: Managing Multiple Instances
category: Operations
tags: instances, parallel, isolation
---
# Managing Multiple Instances
## What are instances?
An instance is one worktree's isolated app stack (project `polar-app-<N>`). All
instances share a single infra stack (`polar-shared`), but each gets:
- Its own api/web **host ports** (offset per instance)
- Its own database `polar_dev_<N>` on the shared postgres
- Its own redis DB index `<N>` on the shared redis
- Its own S3 buckets `polar-s3-<N>` / `polar-s3-public-<N>` on the shared minio
So instances are cheap: only api/worker/web containers are duplicated, not the
infra.
## Port mapping
Only api and web publish host ports. Everything else is shared and reached by
container name, so there is **no** per-instance `5532`/`6479`/`9100` — those
ports don't exist in this model.
| Service | Instance 0 | Instance 1 | Instance 2 |
|---------|------------|------------|------------|
| API (host) | 8000 | 8101 | 8102 |
| Web (host) | 3000 | 3101 | 3102 |
| DB (logical) | `polar_dev_0` | `polar_dev_1` | `polar_dev_2` |
| Redis (DB index) | 0 | 1 | 2 |
| S3 bucket | `polar-s3-0` | `polar-s3-1` | `polar-s3-2` |
**Host-port formula (api/web only):** `Port = Base + Instance` (Base 8100 for
api, 3100 for web), for instances 1–99. Instance 0 uses the legacy `8000`/`3000`.
So instance 5 is api `8105` / web `3105`.
Run `dev docker ports` in a worktree to print its resolved instance and URLs.
## Pinning and inspecting instances
Auto-detection usually picks the right instance, but you can pin or inspect:
```bash
dev docker set-instance 5 # pin this worktree to instance 5 (writes .env.docker + registry)
dev docker clear-instance # back to auto-detect
dev docker list # every registered instance: number, status, path
dev docker prune # drop registry entries whose worktree is gone, and their data
```
Pinning makes ports deterministic, which is what you want when wiring a worktree
into tooling like `.claude/launch.json`.
## Commands (explicit instance)
Most commands auto-detect, but `-i N` targets one explicitly:
```bash
dev docker up -i 1 -d # start instance 1
dev docker ps -i 1 # status
dev docker logs -i 1 api # logs
dev docker down -i 1 # stop
dev docker shell -i 1 api # shell
```
## Use cases
- **Branch A vs branch B** side by side, each in its own worktree.
- **Run a long test suite** in one instance while developing in another.
- **Before/after comparisons** without tearing down your main stack.
## Resource notes
Each app stack adds ~2 GB and its own build/cache volumes; the shared infra is
paid once. Two or three instances is comfortable on a typical machine. Use
`dev docker prune` to reclaim data from worktrees you've deleted.
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 |