Polar Local Environment

Local Environment Skill

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.

Instance Auto-Detection

The dev docker command automatically detects the correct instance number. No manual -i flag is needed in most cases.

Detection priority: 1. CONDUCTOR_PORT env var → (port - 55000) / 10 + 1 2. Workspace path hash → stable instance derived from the repo root path

You can override with -i N if needed, but auto-detection handles Conductor workspaces automatically.

When to Use

• User asks to start/stop the local environment
• User needs to view logs or debug issues
• User wants to run multiple isolated instances
• User needs to understand the service architecture
• User encounters container or service errors

Quick Reference

Services

Instance Port Mapping

Port = Base Port + (Instance × 100)

Rules Index

Managing Multiple Instances

What Are Instances?

Instances allow running multiple isolated development environments simultaneously. Each instance:

• Uses different ports (offset by instance × 100)
• Has its own database
• Has its own file storage
• Runs independently

Port Mapping

Formula: Port = Base + (Instance × 100)

Commands

Start instance:

dev docker up -i 1 -d
dev docker up -i 2 -d

Check instance status:

dev docker ps -i 1

View instance logs:

dev docker logs -i 1 api

Stop instance:

dev docker down -i 1

Shell into instance:

dev docker shell -i 1 api

Use Cases

1. Testing different branches:

• Instance 0: main branch
• Instance 1: feature branch

2. Running parallel tests:

• Instance 0: development
• Instance 1: running test suite

3. Comparing behavior:

• Instance 0: before changes
• Instance 1: after changes

Resource Considerations

Each instance uses:

• ~2GB memory for full stack
• Separate disk space for volumes
• Independent CPU allocation

Limit to 2-3 instances on typical development machines.

Service Architecture Reference

Infrastructure Services

db (PostgreSQL 15.1)

• Purpose: Primary database
• Port: 5432
• Credentials: polar/polar
• Volume: postgres_data
• Health check: pg_isready (2s interval)

redis (Redis Alpine)

• Purpose: Cache and job queue backend
• Port: 6379
• Health check: redis-cli ping

minio (S3-Compatible Storage)

• Purpose: File storage
• Ports: 9000 (API), 9001 (Console)
• Credentials: polar/polarpolar
• Volume: minio_data
• Buckets: polar-s3, polar-s3-public

Application Services

api (FastAPI Backend)

• Purpose: REST API server
• Port: 8000
• Image: Python 3.14 + uvicorn
• Hot-reload: Enabled
• Startup tasks:
• Sync dependencies
• Build email templates
• Run migrations
• Load seed data

worker (Background Jobs)

• Purpose: Async task processing
• Image: Same as API
• Queues: high_priority, medium_priority, low_priority
• Hot-reload: Enabled
• Depends on: API (waits for initialization)

web (Next.js Frontend)

• Purpose: User interface
• Port: 3000
• Image: Node 24 + Turbopack
• Memory limit: 4GB
• Hot-reload: Enabled

Optional Monitoring

prometheus

• Purpose: Metrics collection
• Port: 9090
• Retention: 1 day
• Enable: --monitoring flag

grafana

• Purpose: Dashboards
• Port: 3001
• Credentials: polar/polar
• Enable: --monitoring flag

Container Dependencies

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

Volume Persistence

Network

All services on internal Docker network using service names:

• db:5432
• redis:6379
• minio:9000
• api:8000

Starting the Local Environment

Use dev docker up to start the Polar development environment.

Basic Commands

Start in background (recommended):

dev docker up -d

Start in foreground (see logs directly):

dev docker up

Start specific services:

dev docker up api              # API only
dev docker up web              # Web only
dev docker up api worker       # API and worker
dev docker up -d api web       # API and web in background

Options

Examples

# Full stack in background
dev docker up -d

# Rebuild and start
dev docker up -b -d

# Instance 1 with monitoring
dev docker up -i 1 --monitoring -d

# Just API for backend work
dev docker up -d api

First-Time Startup

On first run: 1. Docker images are built (~5-10 minutes) 2. Dependencies are installed 3. Database migrations run 4. Seed data is loaded 5. Services become available

Service URLs (after startup)

• Web: http://localhost:3000
• API: http://localhost:8000
• API Docs: http://localhost:8000/docs
• MinIO: http://localhost:9001

Stopping the Local Environment

Stop Services

Stop all services:

dev docker down

This stops and removes containers but preserves data volumes.

Stop specific instance:

dev docker down -i 1

Complete Cleanup

Remove containers AND volumes (fresh start):

dev docker cleanup

WARNING: This deletes:

• Database data
• Uploaded files (MinIO)
• Redis cache
• All stored state

Use cleanup when:

• Starting fresh
• Fixing corrupted data
• Testing initial setup
• Changing database schema significantly

Restart vs Stop

Restart (keeps containers, faster):

dev docker restart
dev docker restart api

Stop/Start (recreates containers):

dev docker down
dev docker up -d

Prefer restart for quick changes. Use stop/start when:

• Changing Docker configuration
• Updating environment variables
• Containers are in bad state

Troubleshooting Common Issues

Service Won't Start

Check if ports are in use:

lsof -i :8000    # API port
lsof -i :3000    # Web port
lsof -i :5432    # Database port

Verify Docker is running:

docker info

Check container logs:

dev docker logs api
dev docker logs web

Try stop and restart:

dev docker down
dev docker up -d

Database Connection Failed

Wait for health check (up to 40 seconds on first start)

Check db container:

dev docker ps
dev docker logs db

Verify database is healthy:

dev docker shell db
psql -U polar -d polar -c "SELECT 1"

Hot-Reload Not Working

Check file mounting:

dev docker shell api
ls -la /app/server/polar/

Restart the service:

dev docker restart api

If still broken, rebuild:

dev docker build api
dev docker restart api

Out of Memory

Check Docker memory settings (should be 8GB+)

Stop unused instances:

dev docker down -i 1
dev docker down -i 2

Clean up Docker:

docker system prune

MinIO/S3 Issues

Check minio-setup logs:

dev docker logs minio-setup

Access MinIO console:

• URL: http://localhost:9001
• User: polar
• Password: polarpolar

Verify buckets exist in console UI

Frontend Build Errors

Clear Next.js cache:

dev docker shell web
rm -rf .next
exit
dev docker restart web

Reinstall dependencies:

dev docker shell web
pnpm install
exit
dev docker restart web

Migration Issues

Check current migration state:

dev docker shell api
uv run alembic current

Run pending migrations:

uv run alembic upgrade head

Rollback if needed:

uv run alembic downgrade -1

Complete Reset

When all else fails:

dev docker cleanup -f
dev docker up -b -d

This removes all data and rebuilds from scratch.

Getting Help

1. Check logs: dev docker logs 2. Check status: dev docker ps 3. Check Docker: docker info 4. Try restart: dev docker restart 5. Try cleanup: dev docker cleanup

Viewing Service Logs

Commands

View all logs (last output):

dev docker logs

Follow logs in real-time:

dev docker logs -f

Specific service logs:

dev docker logs api
dev docker logs worker
dev docker logs web
dev docker logs db
dev docker logs redis
dev docker logs minio

Follow specific service:

dev docker logs -f api

Instance-specific logs:

dev docker logs -i 1 api

Log Interpretation

API Logs

Successful request:

INFO: 127.0.0.1:54321 - "GET /api/v1/users HTTP/1.1" 200

Error:

ERROR: Exception in endpoint
Traceback (most recent call last):
  ...

Worker Logs

Task started:

[dramatiq.MainProcess] Task started: polar.tasks.example:process

Task completed:

[dramatiq.MainProcess] Task completed in 0.123s

Web Logs

Page compiled:

✓ Compiled /dashboard in 234ms

Error:

Error: Cannot find module 'xxx'

Debugging Tips

1. Follow API logs during development:

   dev docker logs -f api

2. Check worker for background job issues:

   dev docker logs -f worker

3. Database issues - check db:

   dev docker logs db

4. Startup issues - check all:

   dev docker logs