| name | local-environment |
| description | Local development environment management for Polar using Docker |
| license | MIT |
| metadata | {"author":"polar","version":"1.0.0"} |
This skill enables Claude to help manage the Polar local development environment using Docker. Use this when the user needs to start, stop, debug, or understand the local development stack.
The dev docker command automatically detects the correct instance number. No manual -i flag is needed in most cases.
Detection priority:
CONDUCTOR_PORT env var → (port - 55000) / 10 + 1You can override with -i N if needed, but auto-detection handles Conductor workspaces automatically.
| Task | Command |
|---|---|
| Start full stack | dev docker up -d |
| Stop services | dev docker down |
| View all logs | dev docker logs |
| View service logs | dev docker logs {service} |
| Follow logs | dev docker logs -f |
| Check status | dev docker ps |
| Restart service | dev docker restart {service} |
| Shell access | dev docker shell {service} |
| Fresh start | dev docker cleanup -f && dev docker up -d |
| With monitoring | dev docker up --monitoring -d |
| Force rebuild | dev docker up -b -d |
| Service | Default Port | Description |
|---|---|---|
| api | 8000 | FastAPI backend |
| worker | - | Background job processor |
| web | 3000 | Next.js frontend |
| db | 5432 | PostgreSQL database |
| redis | 6379 | Redis cache |
| minio | 9000/9001 | S3-compatible storage |
| prometheus | 9090 | Metrics (optional) |
| grafana | 3001 | Dashboards (optional) |
For manually started instances: Port = Base Port + (Instance × 100)
| Instance | API | Web | DB | Redis | MinIO |
|---|---|---|---|---|---|
| 0 | 8000 | 3000 | 5432 | 6379 | 9000 |
| 1 | 8100 | 3100 | 5532 | 6479 | 9100 |
| 2 | 8200 | 3200 | 5632 | 6579 | 9200 |
Shared infra (db/redis/minio/tinybird) runs under the polar-shared project
without host port mappings — reach it via dev docker exec <service> or
docker exec polar-shared-<service>-1. The per-instance database is named
polar_dev_<N>, not polar.
| Rule | Category | Description |
|---|---|---|
| service-architecture | Reference | Service details |
| start-environment | Operations | Starting the stack |
| stop-environment | Operations | Stopping the stack |
| manage-instances | Operations | Running parallel instances |
| view-logs | Debugging | Viewing service logs |
| troubleshooting | Debugging | Common errors and fixes |
| payment-testing | Operations | Login codes, Stripe webhooks, dramatiq actors, backoffice |
Analyze and fix issues reported by Sentry in the Polar codebase.
Add a new Terraform Cloud variable for the Render-hosted backend across production, sandbox, and test. Declares the tfe_variable in terraform/global/{production,sandbox,test}.tf and the matching variable {} block in terraform/{production,sandbox,test}/variables.tf, then reminds the user to wire it into render.tf / the render_service module.
Add a new translation locale to the Polar frontend. Walks through registering the locale, generating translations, wiring the generated file into the i18n package, and updating the public-facing docs. Expects the target locale's ISO 639-1 alpha-2 code (optionally with a BCP-47 region suffix, e.g. `pt-PT`).
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
Prepare an interview task for a candidate, as part of our hiring process.
A skill to add a new entry in the section "Backend Development" of the Polar Handbook. Those entries are there to explain concepts, tooling and best practices related to backend development, and are meant to be read by Polar developers.
