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

   docker network create traefik_network
   

2. Set up environment variables: Create a .env file with the following variables:

   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:

   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:

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:

./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:

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

docker network create traefik_network

Permission Issues:

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
• Docker Compose Reference
• Nginx Configuration Guide