Skip to content

fcakyon/claude-codex-settings / plugins/polar-skills/skills/polar-local-environment

polar-local-environment

Verified

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

FileKindSize
SKILL.mdskill md5.3 KB
rules/manage-instances.mdmarkdown2.7 KB
rules/payment-testing.mdmarkdown6.2 KB
rules/service-architecture.mdmarkdown3.1 KB
rules/shell-and-workflows.mdmarkdown2.6 KB
rules/start-environment.mdmarkdown3.0 KB
rules/stop-environment.mdmarkdown1.6 KB
rules/troubleshooting.mdmarkdown6.0 KB
rules/view-logs.mdmarkdown1.9 KB

rules/service-architecture.md

View on GitHub
---
title: Service Architecture Reference
category: Reference
tags: architecture, services, infrastructure
---

# Service Architecture Reference

Two Docker projects: shared infra (`polar-shared`, one per machine) and a
per-instance app stack (`polar-app-<N>`, one per worktree). Shared infra
publishes **no host ports** — reach it with `dev docker exec <service> ...`.

## Infrastructure services (project `polar-shared`)

### db (PostgreSQL 15.1)
- Primary database. Reached at `db:5432` on the `polar-shared` network.
- Credentials: `polar` / `polar`.
- One logical database per instance: `polar_dev_<N>`.
- Volume: `postgres_data`. Health check: `pg_isready`.

### redis (Redis Alpine)
- Cache and job-queue backend at `redis:6379`.
- One DB index per instance (`<N>`); launched with `--databases 100`.
- Health check: `redis-cli ping`.

### minio (S3-compatible storage)
- File storage at `minio:9000` (container) or `localhost:9000` (host).
- Console at `localhost:9001` with credentials `polar-development` / `polar123456789`.
- Per-instance buckets: `polar-s3-<N>`, `polar-s3-public-<N>`.
- Volume: `minio_data`.

### tinybird
- Analytics engine at `tinybird:7181` (admin `7182`). Token is auto-discovered
  from the running container on api startup.

## Application services (project `polar-app-<N>`)

### api (FastAPI backend)
- `python:3.14.6-slim` + uvicorn, hot-reload on.
- Host port: `8000` (instance 0) or `8100+N`.
- Healthcheck: `curl /healthz` (generous `start_period` covers first-boot sync +
  migrations + seed).
- Startup: `uv sync`, build email templates, bootstrap DB/buckets, run
  migrations, load seed data on first run.

### worker (background jobs)
- Same image as api. No host port.
- Dramatiq with the priority queues (`high_priority`, `medium_priority`,
  `low_priority`), hot-reload on.
- Waits for api before starting.

### web (Next.js frontend)
- `node:24-slim` + Turbopack, hot-reload on.
- Host port: `3000` (instance 0) or `3100+N`. Memory limit: 6 GB.
- Healthcheck via Node's built-in `fetch` (the image has no curl/wget).
- Waits for api to be **healthy** before starting (it proxies SSR to api).

## Optional monitoring (project `polar-shared`, `--monitoring`)

- **prometheus** — metrics, 1-day retention, at `prometheus:9090` (no host port).
- **grafana** — dashboards at `grafana:3000` internally, login `polar` / `polar`
  (no host port; port-forward if you need the UI).

## Container dependencies

```
minio-setup → minio (healthy)
api         → db, redis, minio-setup
worker      → api (started)
web         → api (healthy)
grafana     → prometheus
```

## Volume persistence

| Volume | Purpose |
|--------|---------|
| postgres_data | Database (shared) |
| minio_data | Files (shared) |
| server_uv_cache | Python package cache |
| api_venv / worker_venv | Per-service virtualenv |
| pnpm_store | Node package store |
| web_node_modules | Frontend deps |
| web_next_cache | Build cache |

## Networking

App containers join a per-instance `default` bridge plus `polar-shared`. Infra
is addressed by name (`db:5432`, `redis:6379`, `minio:9000`, `api:8000`). Web
stays off `polar-shared` so `http://api:8000` resolves to *this* instance's api.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall