Devops Local Dev

Overview

Manage the Bestays Docker Compose development environment with 4 core services (PostgreSQL, FastAPI, SvelteKit, Redis) using Makefile commands for orchestration, monitoring, and troubleshooting.

When to Use This Skill

Use this skill when:

• Starting a new development session (make dev, make up)
• Stopping or restarting services (make down, make restart)
• Checking service logs (make logs, make logs-server, make logs-frontend)
• Troubleshooting service health or connectivity issues
• Accessing service shells (make shell-server, make shell-db)
• Resetting the development environment (make reset)
• Understanding the Docker Compose architecture

Docker Compose Architecture

Services Overview

Service	Container Name	Host Port	Purpose
postgres	bestays-db-dev	5433 → 5432	PostgreSQL 16-alpine with pgvector
server	bestays-server-dev	8011 → 8011	FastAPI backend with hot-reload
frontend	bestays-dev-frontend	5183 → 5183	SvelteKit 5 with Vite HMR
redis	bestays-redis-dev	6379 → 6379	Redis 7-alpine for caching/sessions
pgadmin	bestays-pgadmin-dev	5050 → 80	Database UI (optional, --profile tools)

Access URLs:

• Backend API: http://localhost:8011
• API Docs: http://localhost:8011/docs
• Frontend: http://localhost:5183
• Database: localhost:5433 (PostgreSQL client)
• pgAdmin: http://localhost:5050 (when started with make pgadmin)

Persistent Volumes

Volume	Purpose	Survives make down?
postgres_data	Database data	✅ Yes
redis_data	Redis persistence	✅ Yes
server_venv	Python virtual env	✅ Yes
frontend_node_modules	Node dependencies	✅ Yes
pgadmin_data	pgAdmin config	✅ Yes

Note: Use make reset to delete all volumes and start fresh.

Network

All services communicate via bestays-network (bridge network).

• Services use internal names to communicate (e.g., postgres:5432, redis:6379)
• Host machine uses localhost with mapped ports (e.g., localhost:5433)

Development Workflow

Starting a Session

Recommended (with validation):

make dev

This command:

1. Detects and stops existing containers
2. Runs preflight validation (checks dependencies, configs)
3. Starts all Docker services
4. Waits for health checks
5. Verifies service health

Quick start (no validation):

make up

With pgAdmin (database UI):

make pgadmin

Monitoring Services

Follow all logs (recommended during development):

make logs

Service-specific logs:

make logs-server     # Backend FastAPI logs
make logs-frontend   # Frontend SvelteKit/Vite logs
make logs-db         # PostgreSQL logs

Check service status:

make status          # Docker Compose status
make check           # Health check all services
make dev-status      # Comprehensive status + validation

Hot-Reload Development

Backend (FastAPI):

• Auto-reloads on .py file changes in apps/server/
• Restart time: ~1-2 seconds
• Watch logs: make logs-server

Frontend (SvelteKit):

• Vite HMR on .svelte, .ts, .js, .css changes in apps/frontend/
• Reload time: ~100-500ms (instant in browser)
• Watch logs: make logs-frontend

Restart after major changes:

make restart-server     # Restart backend only
make restart-frontend   # Restart frontend only
make restart            # Restart all services

Shell Access

Backend shell (Python environment):

make shell-server
# Inside container: python, pytest, alembic commands

Frontend shell:

make shell-frontend
# Inside container: npm, node commands

Database shell (psql):

make shell-db
# PostgreSQL shell connected to bestays_dev

Stopping Services

Preserve data (recommended):

make down           # or make dev-stop

Stops containers, keeps volumes intact.

Full reset (delete all data):

make reset

Stops containers, deletes volumes, restarts fresh.

Makefile Commands

The project uses a Makefile for Docker Compose orchestration. Run make help to see all available commands.

Common Commands

Session Management:

make dev          # Smart start with validation
make up           # Start all services
make down         # Stop services (preserve data)
make restart      # Restart all services
make reset        # Full reset (delete volumes)

Monitoring:

make logs              # Follow all logs
make logs-server       # Backend logs only
make logs-frontend     # Frontend logs only
make status            # Service status
make check             # Health check

Shell Access:

make shell-server      # Backend container shell
make shell-frontend    # Frontend container shell
make shell-db          # PostgreSQL shell

Development:

make build            # Rebuild containers
make test-server      # Run backend tests
make migrate          # Run database migrations

Guidelines:

• Use make dev for validated startup (runs preflight checks)
• Use make up for quick restart (no validation)
• Use make logs during active development
• Use make reset only when you need a completely fresh start (deletes all data)

Troubleshooting

Services Won't Start

Check if ports are already in use:

lsof -i :5433  # PostgreSQL
lsof -i :8011  # Backend
lsof -i :5183  # Frontend
lsof -i :6379  # Redis

Solution: Stop conflicting processes or change ports in docker-compose.dev.yml

Backend Not Hot-Reloading

Verify volume mount:

make shell-server
ls -la /app
# Should show your source code

Check logs for reload confirmation:

make logs-server
# Look for "Uvicorn running on..." and "Watching for changes..."

Frontend Not Hot-Reloading

Check Vite startup:

make logs-frontend
# Look for "VITE ready in X ms" and HMR connection

Verify browser connection:

• Open browser console
• Look for Vite HMR websocket connection
• Should see: [vite] connected.

Database Connection Errors

Check database health:

make check

Verify connection string (from backend container):

make shell-server
echo $DATABASE_URL
# Should be: postgresql+asyncpg://bestays_user:bestays_password@postgres:5432/bestays_dev

Common issue: Backend tries to connect before PostgreSQL is ready

• Solution: Restart backend: make restart-server
• Health checks should prevent this, but can happen on slow systems

Cannot Access Services from Host

Check if services are running:

make status

Verify port mappings:

docker ps --filter "name=bestays"
# Should show: 0.0.0.0:8011->8011/tcp

Test connectivity:

curl http://localhost:8011/api/health   # Backend
curl http://localhost:5183              # Frontend

Full Reset Required

If nothing works, nuclear option:

make reset

This will:

1. Stop all services
2. Delete all volumes (database data, dependencies)
3. Start fresh

Note: You will lose local database data. Consider backing up first (see devops-database skill).

Environment Variables

Required variables (set in .env file):

# Database
POSTGRES_USER=bestays_user
POSTGRES_PASSWORD=bestays_password
POSTGRES_DB=bestays_dev

# Backend
CLERK_SECRET_KEY=sk_test_...
CLERK_WEBHOOK_SECRET=whsec_...
OPENROUTER_API_KEY=sk-or-v1-...

# Frontend
VITE_CLERK_PUBLISHABLE_KEY=pk_test_...

Location: Copy .env.example to .env and configure.

Validation: Run make dev-validate to check environment configuration.

Common Development Patterns

TDD Workflow

# Terminal 1: Watch backend logs
make logs-server

# Terminal 2: Run tests on changes
make test-server

# Edit code → Tests auto-run → Check logs → Repeat

Frontend Component Development

# Terminal 1: Watch frontend logs
make logs-frontend

# Terminal 2: Browser with DevTools open
# Edit .svelte files → Vite HMR → Instant browser update

API Development

# Start services
make dev

# Access interactive API docs
open http://localhost:8011/docs

# Make changes to Python code → Auto-reload → Refresh docs → Test

Full-Stack Feature Development

# Terminal 1: All logs
make logs

# Terminal 2: Available for commands
make shell-server     # Backend work
make shell-frontend   # Frontend work
make migrate          # Database changes

Related Skills

• devops-database - Database migrations, Alembic, PostgreSQL management

Key Files

• docker-compose.dev.yml - Service definitions
• Makefile - Command shortcuts (run make help)
• .env - Environment variables (copy from .env.example)

Integration with Claude Code

When implementing features, Claude Code will:

1. Start session: make dev
2. Watch logs: make logs (or service-specific)
3. Run tests: make test-server
4. Restart services if needed: make restart-server
5. Health check before testing: make check
6. End session (preserves data): make down

Why Docker for Development?

1. Dev/Prod Parity - Same PostgreSQL version, same environment
2. Easy Resets - make reset gives fresh start
3. Isolated Dependencies - No conflicts with host machine
4. Hot-Reload - Code changes reflect immediately
5. Unified Logs - All service logs in one place
6. Session Management - Easy restart between development sessions