trip-planner/docker/README.md

# Trip Planner - Docker Setup

This directory contains Docker configurations for both development and production environments.

## Directory Structure

```
docker/
├── README.md                    # This file
├── dev/                        # Development environment documentation
│   └── README.md
├── prod/                       # Production environment documentation
│   └── README.md
├── backend/                    # Backend service configurations
│   ├── Dockerfile.dev
│   ├── Dockerfile.prod
│   └── supervisord.conf
├── frontend/                   # Frontend service configurations
│   ├── Dockerfile.dev
│   └── Dockerfile.prod
├── nginx/                      # Nginx configurations
│   ├── backend.conf           # Backend API nginx config
│   ├── frontend.conf          # Frontend SPA nginx config
│   └── production.conf        # All-in-one production nginx config
├── supervisord.conf           # Supervisord config for production
└── entrypoint.sh              # Production container entrypoint script
```

## Environments

### Development Environment

**Architecture**: Multi-container setup with separate services
- Frontend (React + Vite dev server)
- Backend (Laravel + PHP-FPM)
- Database (MariaDB)
- Redis
- Mailpit (email testing)

**Use case**: Local development with hot-reloading and debugging

**Documentation**: See [dev/README.md](dev/README.md)

**Docker Compose**: `docker-compose.dev.yml` (in project root)

### Production Environment

**Architecture**: Single all-in-one container with all services
- Frontend (built React app served by Nginx)
- Backend (Laravel + PHP-FPM + Nginx)
- Database (MariaDB - internal)
- Redis (internal)
- All managed by Supervisord

**Use case**: Production deployment with minimal footprint

**Documentation**: See [prod/README.md](prod/README.md)

**Docker Compose**: `docker-compose.prod.yml` (in project root)

## Key Differences

| Aspect | Development | Production |
|--------|------------|------------|
| **Containers** | Multiple (5 services) | Single all-in-one |
| **Frontend** | Vite dev server with HMR | Pre-built static files |
| **Backend** | Live code mounting | Copied into image |
| **Database** | Separate container | Internal to main container |
| **Redis** | Separate container | Internal to main container |
| **Volumes** | Source code mounted | Persistent data only |
| **Ports** | Multiple (5173, 8000, 3306, etc.) | Single port (80) |
| **Size** | ~2GB+ | ~800MB |

## Port Allocation

### Development (default ports)
- Frontend: 5173
- Backend: 8000
- Database: 3306
- Redis: 6379
- Mailpit UI: 8025
- Mailpit SMTP: 1025

### Production (default ports)
- Application: 8080 (configurable via `APP_PORT`)

**Note**: When running both dev and production locally, ensure they don't use conflicting ports. The production setup defaults to port 8080 to avoid conflicts with the dev setup.

## Quick Start

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

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

### Production (Local Testing)
```bash
# Build and start production container
docker compose -f docker-compose.prod.yml up --build

# Stop production container
docker compose -f docker-compose.prod.yml down
```

## Environment Variables

Both environments use environment variables for configuration:

- **Development**: `.env.local` in project root
- **Production**: `.env` or pass via docker-compose environment section

See the respective README files for detailed environment variable documentation.

## Building Images

### Development
Development images are built automatically when you run `docker compose up`.

### Production
```bash
# Build the production image
docker build -f Dockerfile.prod -t trip-planner:latest .

# Or use docker-compose
docker compose -f docker-compose.prod.yml build
```

## CI/CD

The production image is automatically built and pushed to Codeberg Container Registry when changes are merged to the `main` branch.

See `.woodpecker.yml` in the project root for pipeline configuration.

## Troubleshooting

### Development Issues
See [dev/README.md](dev/README.md#troubleshooting)

### Production Issues
See [prod/README.md](prod/README.md#troubleshooting)

## Security Notes

- Development setup runs with elevated privileges for convenience
- Production setup follows security best practices:
  - Non-root users where possible
  - Minimal base images
  - No unnecessary privileges
  - Security headers configured
  - Internal services (DB, Redis) bound to localhost only

## Need Help?

- Check the specific environment README files in `dev/` or `prod/`
- Review the main project documentation
- Check container logs: `docker logs <container-name>`