app/.docker/development/README.md

Development Docker Setup

This directory contains Docker Compose files for local development using Laravel Sail.

Files

• docker-compose.yml - Base Sail configuration for backend (Laravel) and MySQL
• docker-compose.override.yml - Development overrides:
  • Podman/SELinux compatibility (:Z volume flags)
  • Standard MySQL image (instead of mysql-server)
  • Frontend container (Node.js development server)

Quick Start

Use the automated setup script from the project root:

./bin/start-dev

This script will:

1. Create .env if it doesn't exist
2. Install backend dependencies (composer)
3. Start all containers (backend, MySQL, frontend)
4. Run database migrations
5. Optionally seed the database

Manual Usage

Start all services

docker compose -f .docker/development/docker-compose.yml \
               -f .docker/development/docker-compose.override.yml \
               up -d

View logs

# All services
docker compose -f .docker/development/docker-compose.yml \
               -f .docker/development/docker-compose.override.yml \
               logs -f

# Specific service
docker compose -f .docker/development/docker-compose.yml \
               -f .docker/development/docker-compose.override.yml \
               logs -f frontend

Run backend commands

# Run migrations
docker compose -f .docker/development/docker-compose.yml \
               -f .docker/development/docker-compose.override.yml \
               exec backend php artisan migrate

# Run tinker
docker compose -f .docker/development/docker-compose.yml \
               -f .docker/development/docker-compose.override.yml \
               exec backend php artisan tinker

# Run tests
docker compose -f .docker/development/docker-compose.yml \
               -f .docker/development/docker-compose.override.yml \
               exec backend php artisan test

Stop all services

docker compose -f .docker/development/docker-compose.yml \
               -f .docker/development/docker-compose.override.yml \
               down

Services

Service	Port	Description
backend	8000	Laravel API (PHP 8.4 + Sail)
mysql	3306	MySQL 8.0 database
frontend	5173	Vite dev server (React Router)

Environment Variables

The backend reads from backend/.env. Key variables:

• APP_PORT - Backend port (default: 80, set to 8000 for Podman)
• DB_* - Database connection settings
• FORWARD_DB_PORT - Exposed MySQL port (default: 3306)

Volume Mounts

• backend/ → /var/www/html (backend container)
• frontend/ → /app (frontend container)
• MySQL data persists in named volume sail-mysql

Podman Compatibility

The :Z flag on volumes enables SELinux compatibility for Podman users. This is automatically included in the override file.

Notes

• The frontend container automatically runs npm install and npm run dev on startup
• Laravel Sail handles PHP-FPM, supervisor, and other backend services
• Hot reload is enabled for both frontend (Vite HMR) and backend (file watchers)