Claude-skill-registry devops-local-dev

Manages the Bestays Docker Compose development environment including service orchestration, Makefile workflows, logs monitoring, and hot-reload development. This skill should be used when starting/stopping development services, checking logs, troubleshooting Docker issues, or managing the local development workflow.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/devops-local-dev" ~/.claude/skills/majiayu000-claude-skill-registry-devops-local-dev && rm -rf "$T"

manifest: skills/data/devops-local-dev/SKILL.md

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:

Detects and stops existing containers
Runs preflight validation (checks dependencies, configs)
Starts all Docker services
Waits for health checks
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:

Stop all services
Delete all volumes (database data, dependencies)
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

.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:

Start session:
```
make dev
```
Watch logs:
```
make logs
```
(or service-specific)
Run tests:
```
make test-server
```
Restart services if needed:
```
make restart-server
```
Health check before testing:
```
make check
```
End session (preserves data):
```
make down
```

Why Docker for Development?

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