trip-planner/docker/dev/README.md

# Trip Planner - Development Environment

This document describes the development Docker setup for Trip Planner.

## Overview

The development environment uses a multi-container architecture with Docker Compose, providing:
- **Hot Module Replacement (HMR)** for frontend development
- **Live code mounting** for instant backend changes
- **Separate services** for easy debugging
- **Development tools** like Mailpit for email testing

## Architecture

```
┌─────────────────────────────────────────────────────┐
│  trip-planner-network (Docker Bridge Network)       │
│                                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────┐ │
│  │   Frontend   │  │   Backend    │  │ Database │ │
│  │  React+Vite  │  │ Laravel+PHP  │  │ MariaDB  │ │
│  │  Port: 5173  │  │  Port: 8000  │  │ Port:3306│ │
│  └──────────────┘  └──────────────┘  └──────────┘ │
│                                                      │
│  ┌──────────────┐  ┌──────────────┐               │
│  │    Redis     │  │   Mailpit    │               │
│  │  Port: 6379  │  │  UI: 8025    │               │
│  └──────────────┘  │  SMTP: 1025  │               │
│                     └──────────────┘               │
└─────────────────────────────────────────────────────┘
```

## Services

### Frontend (trip-planner-frontend-dev)
- **Image**: Built from `docker/frontend/Dockerfile.dev`
- **Port**: 5173
- **Technology**: React 19 + Vite 7
- **Features**: Hot Module Replacement, ESLint
- **Volume**: `./frontend:/app` (live code mounting)

### Backend (trip-planner-backend-dev)
- **Image**: Built from `docker/backend/Dockerfile.dev`
- **Port**: 8000
- **Technology**: Laravel 12 + PHP 8.3
- **Features**: Artisan commands, PHP-FPM
- **Volume**: `./backend:/var/www/html` (live code mounting)

### Database (trip-planner-db-dev)
- **Image**: MariaDB 11
- **Port**: 3306
- **Data**: Persisted in `./docker/data/mysql-data`
- **Credentials**: Configured via `.env.local`

### Redis (trip-planner-redis-dev)
- **Image**: Redis Alpine
- **Port**: 6379
- **Usage**: Cache, sessions, queues
- **Data**: Named volume `redis-data`

### Mailpit (trip-planner-mailpit-dev)
- **Image**: Axllent Mailpit
- **Ports**:
  - SMTP: 1025
  - Web UI: 8025
- **Usage**: Email testing (catches all outgoing emails)

## Getting Started

### Prerequisites

- Docker Engine 20.10+
- Docker Compose 2.0+
- At least 4GB RAM available for Docker

### Initial Setup

1. **Clone the repository** (if not already done):
   ```bash
   git clone ssh://git@codeberg.org/lvl0/trip-planner.git
   cd trip-planner
   ```

2. **Create environment file**:
   ```bash
   # Copy the example environment file
   cp .env.local.example .env.local

   # Edit .env.local with your settings
   nano .env.local
   ```

3. **Start the development environment**:
   ```bash
   docker compose -f docker-compose.dev.yml up -d
   ```

4. **Wait for services to be ready** (check with):
   ```bash
   docker compose -f docker-compose.dev.yml ps
   ```

5. **Run initial Laravel setup**:
   ```bash
   # Generate application key
   docker exec trip-planner-backend-dev php artisan key:generate

   # Run migrations
   docker exec trip-planner-backend-dev php artisan migrate

   # Seed database (optional)
   docker exec trip-planner-backend-dev php artisan db:seed
   ```

6. **Access the application**:
   - Frontend: http://localhost:5173
   - Backend API: http://localhost:8000
   - Mailpit UI: http://localhost:8025

### Daily Development Workflow

```bash
# Start all services
docker compose -f docker-compose.dev.yml up -d

# View logs
docker compose -f docker-compose.dev.yml logs -f

# Stop all services
docker compose -f docker-compose.dev.yml down

# Restart a specific service
docker compose -f docker-compose.dev.yml restart backend
```

## Environment Variables

The development environment reads from `.env.local` in the project root.

### Required Variables

```env
# Application
APP_NAME="Trip Planner"
APP_KEY=base64:your-generated-key-here

# Database
DB_DATABASE=trip_planner
DB_USERNAME=trip_user
DB_PASSWORD=secret

# Mail
MAIL_MAILER=smtp
MAIL_HOST=mailpit
MAIL_PORT=1025
```

### Optional Variables

```env
# Frontend
VITE_API_URL=http://localhost:8000

# Redis
REDIS_HOST=redis
REDIS_PORT=6379
```

## Common Tasks

### Backend Tasks

```bash
# Run Artisan commands
docker exec trip-planner-backend-dev php artisan <command>

# Examples:
docker exec trip-planner-backend-dev php artisan migrate
docker exec trip-planner-backend-dev php artisan make:controller UserController
docker exec trip-planner-backend-dev php artisan tinker

# Install PHP dependencies
docker exec trip-planner-backend-dev composer install

# Run tests
docker exec trip-planner-backend-dev php artisan test

# Clear caches
docker exec trip-planner-backend-dev php artisan cache:clear
docker exec trip-planner-backend-dev php artisan config:clear
docker exec trip-planner-backend-dev php artisan route:clear
```

### Frontend Tasks

```bash
# Install npm dependencies
docker exec trip-planner-frontend-dev npm install

# Run linter
docker exec trip-planner-frontend-dev npm run lint

# Build for preview
docker exec trip-planner-frontend-dev npm run build
```

### Database Tasks

```bash
# Access MySQL shell
docker exec -it trip-planner-db-dev mysql -u trip_user -p trip_planner

# Backup database
docker exec trip-planner-db-dev mysqldump -u trip_user -p trip_planner > backup.sql

# Restore database
docker exec -i trip-planner-db-dev mysql -u trip_user -p trip_planner < backup.sql

# Reset database
docker compose -f docker-compose.dev.yml down -v  # Removes volumes!
docker compose -f docker-compose.dev.yml up -d
docker exec trip-planner-backend-dev php artisan migrate --seed
```

### Viewing Logs

```bash
# All services
docker compose -f docker-compose.dev.yml logs -f

# Specific service
docker compose -f docker-compose.dev.yml logs -f backend

# Laravel logs
docker exec trip-planner-backend-dev tail -f storage/logs/laravel.log
```

## Troubleshooting

### Services won't start

**Check for port conflicts:**
```bash
# Check what's using the ports
lsof -i :5173  # Frontend
lsof -i :8000  # Backend
lsof -i :3306  # Database

# Stop conflicting services or change ports in docker-compose.dev.yml
```

### Frontend HMR not working

**SELinux issue (Fedora/RHEL):**
The `:Z` flag in volume mounts handles this, but if HMR still doesn't work:
```bash
# Check if SELinux is enforcing
getenforce

# If needed, you can temporarily set to permissive
sudo setenforce 0
```

### Backend not connecting to database

**Wait for database to be fully ready:**
```bash
# Check database status
docker compose -f docker-compose.dev.yml ps database

# Check database logs
docker compose -f docker-compose.dev.yml logs database

# Verify connection
docker exec trip-planner-backend-dev php artisan migrate:status
```

### Permission issues

**Vendor/node_modules ownership:**
```bash
# Fix backend vendor permissions
docker exec trip-planner-backend-dev chown -R www-data:www-data vendor

# Fix frontend node_modules (usually not needed with named volumes)
docker compose -f docker-compose.dev.yml down
docker volume rm trip-planner_node_modules
docker compose -f docker-compose.dev.yml up -d
```

### Clean slate rebuild

```bash
# Stop everything
docker compose -f docker-compose.dev.yml down -v

# Remove images
docker rmi trip-planner-frontend-dev trip-planner-backend-dev

# Rebuild and start
docker compose -f docker-compose.dev.yml up --build
```

## Performance Tips

### Disable Features You Don't Need

If a service is not needed for your current task:
```bash
# Start only specific services
docker compose -f docker-compose.dev.yml up -d backend database redis
```

### Use Cached Volumes

The dev setup uses named volumes for `node_modules` and `vendor` to improve performance:
- `node_modules`: Frontend dependencies
- `vendor`: Backend PHP dependencies

These are NOT mounted from your host, keeping filesystem operations fast.

## Differences from Production

| Feature | Development | Production |
|---------|------------|------------|
| Code loading | Live mounted volumes | Copied into image |
| Caching | Disabled/minimal | Aggressive (OPcache, etc.) |
| Error display | Verbose | Hidden |
| Debug mode | Enabled | Disabled |
| Privileges | Elevated for convenience | Minimal (security) |
| Rebuilding | Rarely needed | Required for changes |

## Security Note

⚠️ **The development environment is NOT secure** - it runs with `privileged: true` for convenience and mounts source code directly. **Never use this setup in production!**

## Need Help?

- Check the main [docker/README.md](../README.md)
- Review Laravel logs: `docker exec trip-planner-backend-dev tail -f storage/logs/laravel.log`
- Check container health: `docker compose -f docker-compose.dev.yml ps`
- Inspect a container: `docker inspect trip-planner-backend-dev`