lvl0/trip-planner
1
0
Fork 0
Code Issues 21 Pull requests 1 Projects Releases Packages Wiki Activity Actions
trip-planner/docker/dev/README.md
myrmidex a5307f3e5d 2 - tmp
2025-11-16 15:53:52 +01:00

9.3 KiB
Raw Permalink Blame History

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:

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