Add comprehensive Docker development context to AGENTS.md (#21734)

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: akabiru <17295175+akabiru@users.noreply.github.com>

AGENTS.md

@@ -18,7 +18,10 @@
 - Node: `^22.21.0` (see `package.json` engines)
 - Bundler: Latest 2.x
 
-**Local Development Setup:**
+OpenProject supports two development setups: **Local** and **Docker**. Choose one based on your preference.
+
+### Local Development Setup
+
 ```bash
 bundle install                    # Install Ruby gems
 cd frontend && npm ci && cd ..   # Install Node packages
@@ -27,7 +30,34 @@ bin/dev                          # Start all services (Rails, frontend, Good Job
 # Access at http://localhost:3000
 ```
 
-**Docker Setup:** See `docker-compose.yml` and run `bin/compose setup`. Note: `config/database.yml` must NOT exist when using Docker.
+### Docker Development Setup
+
+The Docker development environment uses configurations in `docker/dev/` and the `bin/compose` wrapper script.
+
+```bash
+# Initial setup (first time only)
+bin/compose setup                         # Installs backend and frontend dependencies
+
+# Starting services
+bin/compose start                         # Start backend and frontend in background
+bin/compose run                           # Start frontend in background, backend in foreground (for debugging with pry)
+
+# Running tests
+bin/compose rspec spec/models/user_spec.rb   # Run specific tests in backend-test container
+
+# Other operations
+bin/compose reset                         # Remove all containers and volumes (requires setup again)
+bin/compose <command>                     # Pass any docker-compose command directly
+```
+
+**Important Docker Notes:**
+- **CRITICAL**: `config/database.yml` must NOT exist when using Docker (rename or delete it)
+- Most developers use a local `docker-compose.override.yml` for custom port mappings and configurations
+- Copy `docker-compose.override.example.yml` to `docker-compose.override.yml` and customize as needed
+- Default ports: Backend at http://localhost:3000 (or 4200 for frontend dev server)
+- Services: `backend`, `frontend`, `worker`, `db`, `db-test`, `backend-test`, `cache`
+- Persisted volumes: `pgdata`, `bundle`, `npm`, `tmp`, `opdata` (data survives container restarts)
+- Docker build context: Uses Dockerfiles in `docker/dev/backend/` and `docker/dev/frontend/`
 
 ## Project Structure
 
@@ -138,6 +168,8 @@ cd frontend && npm test && cd ..
 
 ## Important Commands Reference
 
+### Local Development Commands
+
 ```bash
 # Setup
 bin/setup              # Initial Rails setup
@@ -162,11 +194,36 @@ cd frontend && npm test                  # Frontend tests
 bundle exec rubocop                      # Ruby linting
 cd frontend && npx eslint src/           # JS/TS linting
 erb_lint {files}                         # ERB linting
+```
 
-# Docker
-bin/compose setup                        # Setup Docker environment
-bin/compose start                        # Start services
-bin/compose rspec {test_file}            # Run tests in Docker
+### Docker Development Commands
+
+```bash
+# Setup and lifecycle
+bin/compose setup                        # Setup Docker environment (first time)
+bin/compose start                        # Start all services in background
+bin/compose run                          # Start frontend in background, backend in foreground
+bin/compose reset                        # Remove all containers and volumes
+bin/compose stop                         # Stop all services
+bin/compose down                         # Stop and remove containers
+
+# Testing
+bin/compose rspec spec/models/user_spec.rb    # Run specific tests
+bin/compose exec backend bundle exec rspec    # Run tests directly in backend container
+
+# Development
+bin/compose exec backend bundle exec rails console   # Rails console
+bin/compose logs backend                 # View backend logs
+bin/compose logs -f backend              # Follow backend logs
+bin/compose ps                           # List running containers
+
+# Database
+bin/compose exec backend bundle exec rake db:migrate      # Run migrations
+bin/compose exec backend bundle exec rake db:seed         # Seed data
+
+# Direct docker-compose commands
+bin/compose up -d                        # Start services
+bin/compose restart backend              # Restart backend service
 ```
 
 ## Additional Documentation