polar-local-environment — скилл для Claude Code: Docker-среда Polar
Скилл polar-local-environment помогает запускать и обслуживать локальное окружение Polar через dev docker. Он пригодится для отладки сервисов и работы с несколькими изолированными worktree.
MIT ★ 1 216 обновлён 2026-10-24
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settingsЧто делает polar-local-environment
Скилл объясняет, как устроен стек Polar: общая инфраструктура с PostgreSQL, Redis и MinIO используется всеми worktree, а для каждого worktree запускаются отдельные API, worker и web. Через dev docker можно поднимать и останавливать окружение, смотреть логи, проверять порты и выполнять команды внутри сервисов.
Номер экземпляра определяется для текущего worktree автоматически; его также можно закрепить командой dev docker set-instance N. API и web получают порты с учётом номера, а база данных и Redis не публикуют host-порты: доступ к ним идёт через dev docker exec. Это важно при отладке: подключение к базе через localhost:5432 не сработает.
Для предпросмотра в Claude Code команда dev docker launch-json создаёт файл .claude/launch.json с портами экземпляра. После смены номера файл нужно создать заново, поскольку он игнорируется Git.
Какие задачи решает
- Запустить или остановить локальный стек Polar
- Найти порты текущего worktree
- Посмотреть логи и отладить сервис
- Развести окружения нескольких worktree
- Выполнить команду внутри контейнера
Примеры запросов агенту
- Запусти локальное окружение Polar и дождись готовности сервисов.
- Покажи порты текущего worktree и объясни, как открыть предпросмотр в Claude Code.
- Проверь логи
apiи подскажи, почему сервис не запускается.
Как установить polar-local-environment
1Через маркетплейс плагинов
/plugin marketplace add fcakyon/claude-codex-settings/plugin install polar-skills@claude-settingsКоманда ставит плагин polar-skills целиком, со всеми его скиллами
2Через Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill polar-local-environment -a claude-code3Вручную: положить файлы
~/.claude/skills/polar-local-environment/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/polar-local-environment/
1Через Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill polar-local-environment -a codex2Вручную: положить файлы
.agents/skills/polar-local-environment/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill polar-local-environment -a cursor2Вручную: положить файлы
.cursor/skills/polar-local-environment/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install fcakyon/claude-codex-settings plugins/polar-skills/skills/polar-local-environment2Вручную: положить файлы
.github/skills/polar-local-environment/SKILL.md1Через Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill polar-local-environment -a gemini-cli2Командой платформы
gemini skills install https://github.com/fcakyon/claude-codex-settings --path plugins/polar-skills/skills/polar-local-environmentВручную: положить файлы
.devin/skills/polar-local-environment/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Claude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о polar-local-environment
Как установить polar-local-environment в Claude Code?
Добавьте маркетплейс командой /plugin marketplace add fcakyon/claude-codex-settings, затем установите скилл: /plugin install polar-skills@claude-settings.
Что делает polar-local-environment?
Скилл помогает управлять локальным Docker-окружением Polar через dev docker: запускать стек, проверять порты, читать логи и работать с сервисами.
Почему PostgreSQL недоступен на localhost:5432?
База работает в общей инфраструктуре и не публикует host-порт. Подключайтесь к ней через dev docker exec db ....
Исходный текст
SKILL.md · MIT
--- 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 |
© polar · MIT · fcakyon/claude-codex-settings