project_vollidioten_website/DOCKER-SETUP.md

# Docker Setup for Vollidioten Project

This document describes the Docker setup for the Vollidioten project, including frontend, backend, and database services with Traefik integration.

## 🚀 Quick Start

1. **Create Traefik network** (if not already exists):
   ```bash
   docker network create traefik_network
   ```

2. **Set up environment variables**:
   Create a `.env` file with the following variables:
   ```env
   DISCORD_CLIENT_ID=your_discord_client_id
   DISCORD_CLIENT_SECRET=your_discord_client_secret
   SESSION_SECRET=your_session_secret
   ```

3. **Build and start the containers**:
   ```bash
   docker-compose up -d --build
   ```

4. **Access the application**:
   - Frontend: `https://vollidioten.ceraticsoft.de`
   - phpMyAdmin: `http://localhost:8081`

## 📁 Project Structure

```
.
├── Dockerfile.frontend          # Frontend Dockerfile
├── Dockerfile.backend           # Backend Dockerfile
├── docker-compose.yml           # Docker Compose configuration
├── nginx.conf                   # Nginx configuration with fallback
├── public/
│   ├── mock/                    # Mock data files
│   │   ├── players.json         # Mock player data
│   │   ├── orgs.json            # Mock organization data
│   │   └── projects.json        # Mock project data
│   └── auth-unavailable.html    # Auth unavailable page
└── test-docker-setup.sh         # Test script
```

## 🔧 Services

### Frontend
- **Image**: Custom built from `Dockerfile.frontend`
- **Port**: 80 (internal, exposed via Traefik)
- **Traefik Configuration**:
  - Host: `vollidioten.ceraticsoft.de`
  - EntryPoint: `websecure` (HTTPS)
  - TLS: Let's Encrypt
- **Features**:
  - Automatic fallback to mock data when backend is unavailable
  - Nginx proxy with error handling
  - Static file serving with caching

### Backend
- **Image**: Custom built from `Dockerfile.backend`
- **Port**: 3000 (internal only)
- **Environment Variables**:
  - `DISCORD_CLIENT_ID`: Discord OAuth client ID
  - `DISCORD_CLIENT_SECRET`: Discord OAuth client secret
  - `SESSION_SECRET`: Session encryption secret
  - `CALLBACK_URL`: OAuth callback URL
  - `FRONTEND_URL`: Frontend base URL
  - `DB_*`: Database connection details

### Database (MySQL)
- **Image**: `mysql:8.0`
- **Port**: 3306 (internal only)
- **Credentials**:
  - User: `obsidian_user`
  - Password: `obsidian_pass`
  - Database: `obsidian_db`
- **Persistent Storage**: Docker volume (`db_data`)

### phpMyAdmin
- **Image**: `phpmyadmin/phpmyadmin`
- **Port**: 8081 (localhost only)
- **Access**: `http://localhost:8081`

## 🛡️ Fallback Mechanism

The setup includes a robust fallback mechanism:

1. **Nginx Proxy Fallback**:
   - When the backend is unavailable (502/503/504 errors), nginx automatically serves mock data
   - Mock data is served from `/public/mock/` directory
   - Response headers indicate mock data usage:
     - `X-Mock-Data: true`
     - `X-Backend-Status: unavailable`

2. **Frontend Detection**:
   - The frontend checks for the `X-Mock-Data` header
   - Console warnings indicate when mock data is being used
   - Users see appropriate messages in the UI

3. **Auth Handling**:
   - Auth endpoints fail gracefully when backend is down
   - Users see a friendly error page (`auth-unavailable.html`)
   - Application remains usable in read-only mode

## 🔄 Traefik Integration

The frontend service is configured with Traefik labels:

```yaml
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.vollidioten.rule=Host(`vollidioten.ceraticsoft.de`)"
  - "traefik.http.routers.vollidioten.entrypoints=websecure"
  - "traefik.http.routers.vollidioten.tls.certresolver=lets-encrypt"
  - "traefik.http.services.vollidioten.loadbalancer.server.port=80"
```

## 🧪 Testing

Run the test script to verify the setup:

```bash
./test-docker-setup.sh
```

The script checks:
- Docker is running
- Traefik network exists
- All required files are present
- Docker containers can be built

## 📝 Environment Variables

Create a `.env` file in the project root:

```env
# Discord OAuth
DISCORD_CLIENT_ID=your_client_id
DISCORD_CLIENT_SECRET=your_client_secret

# Session
SESSION_SECRET=your_strong_secret_here
```

## 🔧 Customization

### Adding More Mock Data
Add JSON files to the `public/mock/` directory following the same structure as existing files.

### Updating Nginx Configuration
Edit `nginx.conf` to modify:
- Proxy settings
- Cache headers
- Error handling
- Fallback behavior

### Scaling
The setup supports horizontal scaling:
- Frontend: Can be scaled to multiple instances
- Backend: Can be scaled with proper session handling
- Database: Use external managed database for production

## 🚨 Troubleshooting

**Docker Network Issues**:
```bash
docker network create traefik_network
```

**Permission Issues**:
```bash
chmod +x test-docker-setup.sh
```

**Port Conflicts**:
- Ensure port 8081 is available for phpMyAdmin
- Check Traefik is running and listening on port 443

**SSL Issues**:
- Ensure Traefik is configured with Let's Encrypt
- Check DNS records for `vollidioten.ceraticsoft.de`

## 🎯 Production Notes

1. **Security**:
   - Use strong secrets for all environment variables
   - Configure proper CORS settings
   - Set up database backups

2. **Performance**:
   - Configure proper caching headers
   - Optimize database queries
   - Use CDN for static assets

3. **Monitoring**:
   - Set up health checks
   - Configure logging
   - Monitor backend availability

4. **Updates**:
   - Regularly update Docker images
   - Test updates in staging first
   - Monitor after deployments

## 📚 References

- [Traefik Documentation](https://doc.traefik.io/traefik/)
- [Docker Compose Reference](https://docs.docker.com/compose/)
- [Nginx Configuration Guide](https://nginx.org/en/docs/)