wrongmove/.claude/skills/dev-environment.md

name	description	author	version	date
dev-environment	Start, stop, rebuild, and manage the local Docker Compose development environment for the realestate-crawler project. Use when: (1) user wants to start/stop the dev environment, (2) needs to rebuild after code changes, (3) wants to check service status or view logs, (4) needs to run database migrations.	Claude Code	1.0.0	2026-02-06

Dev Environment Management

Docker Compose orchestrates the dev environment locally from crawler/. All project commands (pytest, alembic, mypy, python, etc.) must run inside the app container via docker compose exec app <command>. Only docker/kubectl commands run on the host.

Starting the Dev Environment

# Start all services (Redis, MySQL, API, Celery worker, Celery beat)
cd crawler && docker compose up

# Start in detached mode (background)
cd crawler && docker compose up -d

# Rebuild images and start (after Dockerfile or dependency changes)
cd crawler && docker compose up --build

# Or use the start.sh helper
cd crawler && ./start.sh          # foreground
cd crawler && ./start.sh --build  # rebuild first

Stopping the Dev Environment

cd crawler && docker compose down

# Also remove volumes (fresh database, fresh Redis)
cd crawler && docker compose down -v

# Or use the helper
cd crawler && ./start.sh --down

Checking Status

# List running containers
cd crawler && docker compose ps

# Check health status
cd crawler && docker compose ps --format "table {{.Name}}\t{{.Status}}"

Viewing Logs

# Follow all service logs
cd crawler && docker compose logs -f

# Follow specific service logs
cd crawler && docker compose logs -f app
cd crawler && docker compose logs -f celery
cd crawler && docker compose logs -f celery-beat
cd crawler && docker compose logs -f mysql
cd crawler && docker compose logs -f redis

# Or use the helper
cd crawler && ./start.sh --logs

Restarting Individual Services

# Restart just the API (e.g., after config change)
cd crawler && docker compose restart app

# Restart Celery worker
cd crawler && docker compose restart celery

# Rebuild and restart a single service
cd crawler && docker compose up --build app

Running Database Migrations

# Apply pending migrations
cd crawler && docker compose exec app alembic upgrade head

# Create a new migration
cd crawler && docker compose exec app alembic revision -m "description"

Running Tests Inside Container

cd crawler && docker compose exec app pytest tests/ -v --cov=. --cov-report=term-missing

Running Any Command Inside Container

All project commands must be run inside the app container:

# General pattern
cd crawler && docker compose exec app <command>

# Examples
cd crawler && docker compose exec app python main.py dump-listings --type rent
cd crawler && docker compose exec app mypy .
cd crawler && docker compose exec app ruff check .
cd crawler && docker compose exec app poetry install
cd crawler && docker compose exec app bash   # interactive shell

Services and Ports

Service	Container	Port	Description
redis	rec-redis	6379	Celery broker + GeoJSON cache
mysql	rec-mysql	3306	Primary database
app	rec-app	5001	FastAPI server (hot-reload)
celery	rec-celery	-	Background task worker
celery-beat	rec-celery-beat	-	Periodic task scheduler

Environment Variables

Key env vars are set in docker-compose.yml. To override locally, create a .env file in crawler/ (see .env.sample). Key overrides:

• ROUTING_API_KEY - Google Maps API key (passed from host env)
• SCRAPE_SCHEDULES - JSON array of periodic scrape configs (passed from host env)

Notes

• The API server has hot-reload enabled for api/, services/, repositories/, and models/ directories
• Source code is bind-mounted into containers, so local edits are reflected immediately
• Python virtualenv is stored in a named Docker volume (app_venv) shared across app, celery, and celery-beat
• MySQL data persists in the mysql_data volume; Redis data in redis_data
• Use docker compose down -v to reset all data (volumes)