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/shell-and-workflows.md
View on GitHub---
title: Shell Access and Common Workflows
category: Operations
tags: shell, exec, workflows, testing
---
# Shell Access and Common Workflows
## Shell into a container
```bash
dev docker shell api # Python env (api)
dev docker shell worker # Python env (worker)
dev docker shell web # Node env
dev docker shell db # postgres container (shared)
```
For one-off commands without an interactive shell, use `exec`:
```bash
dev docker exec api uv run alembic current
dev docker exec db psql -U polar -d polar_dev_<N> -c "SELECT 1"
dev docker exec redis redis-cli -n <N> dbsize
```
`exec`/`shell` auto-route by service name: app services hit this instance's
`polar-app-<N>` project, infra services hit `polar-shared`.
## Useful in-container commands
**api / worker (Python):**
```bash
uv run alembic upgrade head # run migrations
uv run alembic revision --autogenerate -m "message" # create a migration
uv run alembic current # show current revision
```
(Backend tests are the exception — they don't run in this container; see below.)
**web (Node):**
```bash
pnpm test
pnpm lint
```
**db (PostgreSQL):** the database is per-instance, so pass `polar_dev_<N>`, not
`polar`:
```bash
psql -U polar -d polar_dev_<N>
```
## Common workflows
**Daily development:**
```bash
dev docker up -d --wait # start and wait until serving
dev docker ps # confirm status
dev docker logs -f api # watch as you work
dev docker down # stop when done (data persists)
```
**After a git pull:** hot-reload handles most changes. If deps changed:
```bash
dev docker restart api worker web # picks up new deps via startup uv sync / pnpm
# only if a Dockerfile or system dep changed:
dev docker up -b -d api worker web
```
**Run tests:**
Frontend unit tests run in the web container:
```bash
dev docker exec web pnpm test
```
Backend tests do **not** run in the `dev docker` api container. The suite's
session-wide `empty_test_bucket` fixture hard-requires S3 at
`http://127.0.0.1:9000` with `testing`-prefixed buckets, but containers can't
reach `localhost:9000` on the host — they use `minio:9000` internally with
per-instance `polar-s3-<N>` buckets. Run backend tests on the host with the
standard setup in `server/AGENTS.md` (`uv run task test`).
**Database operations:**
```bash
dev docker exec api uv run alembic upgrade head
dev docker exec api uv run alembic downgrade -1
dev docker exec db psql -U polar -d polar_dev_<N>
```
Find `<N>` (and the real ports) for the current worktree with `dev docker ports`.
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 |