trip-planner/docker/dev

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):

   git clone ssh://git@codeberg.org/lvl0/trip-planner.git
   cd trip-planner
   

2. Create environment file:

   # 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:

   docker compose -f docker-compose.dev.yml up -d
   

4. Wait for services to be ready (check with):

   docker compose -f docker-compose.dev.yml ps
   

5. Run initial Laravel setup:

   # 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

# 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

# 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

# Frontend
VITE_API_URL=http://localhost:8000

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

Common Tasks

Backend Tasks

# 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

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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

# 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:

# 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
• 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