AGENTS.md

1# Docker Development
2 
3The Docker development environment uses configurations in `docker/dev/` and the `bin/compose` wrapper script.
4 
5## Setup
6 
7```bash
8# Initial setup (first time only)
9bin/compose setup                         # Installs backend and frontend dependencies
10 
11# Starting services
12bin/compose start                         # Start backend and frontend in background
13bin/compose run                           # Start frontend in background, backend in foreground (for debugging with pry)
14 
15# Running tests
16bin/compose rspec spec/models/user_spec.rb   # Run specific tests in backend-test container
17 
18# Other operations
19bin/compose reset                         # Remove all containers and volumes (requires setup again)
20bin/compose <command>                     # Pass any docker-compose command directly
21```
22 
23## Important Notes
24 
25- **CRITICAL**: `config/database.yml` must NOT exist when using Docker (rename or delete it)
26- Most developers use a local `docker-compose.override.yml` for custom port mappings and configurations
27- Copy `docker-compose.override.example.yml` to `docker-compose.override.yml` and customize as needed
28- Default ports: Backend at http://localhost:3000 (or 4200 for frontend dev server)
29- Services: `backend`, `frontend`, `worker`, `db`, `db-test`, `backend-test`, `cache`
30- Persisted volumes: `pgdata`, `bundle`, `npm`, `tmp`, `opdata` (data survives container restarts)
31- Docker build context: Uses Dockerfiles in `docker/dev/backend/` and `docker/dev/frontend/`
32 
33## Commands Reference
34 
35```bash
36# Setup and lifecycle
37bin/compose setup                        # Setup Docker environment (first time)
38bin/compose start                        # Start all services in background
39bin/compose run                          # Start frontend in background, backend in foreground
40bin/compose reset                        # Remove all containers and volumes
41bin/compose stop                         # Stop all services
42bin/compose down                         # Stop and remove containers
43 
44# Testing
45bin/compose rspec spec/models/user_spec.rb    # Run specific tests
46bin/compose exec backend bundle exec rspec    # Run tests directly in backend container
47 
48# Development
49bin/compose exec backend bundle exec rails console   # Rails console
50bin/compose logs backend                 # View backend logs
51bin/compose logs -f backend              # Follow backend logs
52bin/compose ps                           # List running containers
53 
54# Database
55bin/compose exec backend bundle exec rails db:migrate      # Run migrations
56bin/compose exec backend bundle exec rails db:seed         # Seed data
57 
58# Direct docker-compose commands
59bin/compose up -d                        # Start services
60bin/compose restart backend              # Restart backend service
61```
62