Fix homepage Traefik network routing and update configurations

- Add traefik.docker.network=traefik-network label to homepage service - Prevent Traefik from using wrong IP from homelab-network - Resolve 504 Gateway Timeout issues after authentication - Update various docker-compose configurations and templates - Clean up unused configuration files
2026-01-30 23:29:00 -05:00
parent 465c10ae42
commit 90a26a9ac4
88 changed files with 3841 additions and 3626 deletions
--- a/docker-compose/core/.env.template
+++ b/docker-compose/core/.env.template
@@ -0,0 +1,28 @@
+# Environment Variables Template for Core Services
+# Copy this file to .env and fill in your values
+
+# User and Group IDs for file permissions (get with: id -u and id -g)
+PUID=1000
+PGID=1000
+
+TZ=America/New_York
+
+SERVER_IP=192.168.1.100
+SERVER_HOSTNAME=your-server-name
+
+# Domain & DuckDNS Configuration
+DUCKDNS_SUBDOMAINS=your-subdomain  # Without .duckdns.org
+DOMAIN=your-subdomain.duckdns.org
+DUCKDNS_TOKEN=your-duckdns-token-here
+
+# Default credentials (used by multiple services for easier setup)
+DEFAULT_USER=admin
+DEFAULT_PASSWORD=change-this-password
+
+# Authelia Configuration
+AUTHELIA_JWT_SECRET=your-jwt-secret-here
+AUTHELIA_SESSION_SECRET=your-session-secret-here
+AUTHELIA_STORAGE_ENCRYPTION_KEY=your-encryption-key-here
+
+# Let's Encrypt Configuration
+ACME_EMAIL=your-email@example.com
--- a/docker-compose/core/README.md
+++ b/docker-compose/core/README.md
@@ -0,0 +1,171 @@
+# Core Infrastructure Services
+
+This directory contains the core infrastructure services that form the foundation of the homelab. These services should always be running and are critical for the operation of other services.
+
+## Services
+
+### Traefik (v3)
+- **Purpose**: Reverse proxy and SSL termination
+- **Ports**: 80 (HTTP), 443 (HTTPS), 8080 (Dashboard)
+- **Configuration**: Located in `traefik/config/traefik.yml`
+- **SSL**: Let's Encrypt with DNS-01 challenge (configurable provider)
+- **Dashboard**: Available at configured domain
+
+### Authelia (v4.37.5)
+- **Purpose**: Single sign-on authentication service
+- **Port**: 9091 (internal)
+- **Access**: Configured authentication domain
+- **Configuration**: Located in `authelia/config/`
+- **Database**: SQLite database in `authelia/config/db.sqlite3`
+
+### DuckDNS
+- **Purpose**: Dynamic DNS service for domain resolution
+- **Subdomain**: Configurable via environment variables
+- **Token**: Configured in environment variables
+
+## ⚠️ Version Pinning & Breaking Changes
+
+### Authelia Version Pinning
+**Current Version**: `authelia/authelia:4.37.5`
+
+**Breaking Changes Identified**:
+- Authelia v4.39.15+ has breaking configuration changes that are incompatible with the current setup
+- Database schema changes may require migration or recreation
+- Configuration file format changes may break existing setups
+
+**Action Taken**:
+- Pinned to v4.37.5 which is confirmed working
+- Database recreated from scratch to ensure compatibility
+- Configuration files verified and working
+
+**Upgrade Path**:
+- Test upgrades in a separate environment first
+- Backup configuration and database before upgrading
+- Check Authelia changelog for breaking changes
+- Consider using Authelia's migration tools if available
+
+### Traefik Version Pinning
+**Current Version**: `traefik:v3`
+
+**Notes**:
+- Traefik v3 is stable and working with current configuration
+- Configuration format is compatible
+- No breaking changes identified in current setup
+
+## Configuration Requirements
+
+### File Structure
+```
+core/
+├── docker-compose.yml          # Main service definitions
+├── .env                        # Environment variables
+├── authelia/
+│   └── config/
+│       ├── configuration.yml   # Authelia main config
+│       ├── users_database.yml  # User credentials
+│       └── db.sqlite3          # SQLite database
+└── traefik/
+    ├── config/
+    │   └── traefik.yml         # Traefik static config
+    ├── dynamic/                # Dynamic configurations
+    │   ├── routes.yml
+    │   ├── sablier.yml
+    │   └── external-host-*.yml
+    └── letsencrypt/
+        └── acme.json           # SSL certificates
+```
+
+### Environment Variables (.env)
+```bash
+# Required for proper operation
+DUCKDNS_TOKEN=your_duckdns_token_here
+DUCKDNS_SUBDOMAINS=your_subdomain
+DOMAIN=yourdomain.duckdns.org
+TZ=America/New_York
+PUID=1000
+PGID=1000
+```
+
+### Network Requirements
+- Docker network: `traefik-network`
+- External ports: 80, 443 must be accessible
+- DNS resolution: Domain must point to server IP
+
+## Deployment
+
+### Prerequisites
+1. Docker and Docker Compose installed
+2. Ports 80/443 forwarded to server
+3. DuckDNS account with valid token
+4. Domain configured in DuckDNS
+
+### Startup Order
+1. `duckdns` - For DNS updates
+2. `traefik` - Reverse proxy
+3. `authelia` - Authentication service
+
+### Commands
+```bash
+# Start all services
+docker-compose up -d
+
+# Check status
+docker-compose ps
+
+# View logs
+docker-compose logs -f [service-name]
+
+# Restart specific service
+docker-compose restart [service-name]
+```
+
+## Troubleshooting
+
+### Common Issues
+1. **Connection Refused**: Check if Traefik config file is in correct location (`traefik/config/traefik.yml`)
+2. **SSL Certificate Issues**: Verify DuckDNS token and domain configuration
+3. **Authelia Login Issues**: Check database file exists and configuration is valid
+4. **Service Not Starting**: Check Docker logs for error messages
+
+### Backup Strategy
+- Configuration files are backed up automatically (see backup directories)
+- Database should be backed up regularly
+- SSL certificates are stored in `letsencrypt/acme.json`
+- Use `backup.sh` script for automated backups
+
+## Security Notes
+- Authelia provides authentication for protected services
+- All external traffic goes through Traefik with SSL termination
+- Internal services communicate via Docker networks
+- Dashboard access is protected by Authelia middleware
+
+## Maintenance
+- Monitor SSL certificate expiration (Let's Encrypt auto-renews)
+- Keep Authelia version pinned until tested upgrades are available
+- Regularly backup configuration and database files
+- Check logs for security issues or errors
+- Run `./backup.sh` regularly to backup critical files
+
+## Customization
+
+### Domain Configuration
+Update the following files with your domain:
+- `docker-compose.yml`: Traefik labels and Authelia configuration
+- `authelia/config/configuration.yml`: Domain settings
+- `.env`: Domain environment variables
+
+### SSL Certificate Provider
+Modify `traefik/config/traefik.yml` to use different DNS providers:
+```yaml
+certificatesResolvers:
+  letsencrypt:
+    acme:
+      dnsChallenge:
+        provider: cloudflare  # or other supported provider
+```
+
+### Adding New Services
+1. Add service definition to `docker-compose.yml`
+2. Configure Traefik labels for routing
+3. Add middleware for authentication if needed
+4. Update network configuration
--- a/docker-compose/core/authelia/configuration.yml
+++ b/docker-compose/core/authelia/configuration.yml
@@ -1,6 +1,6 @@
-# Authelia Configuration
+# Authelia Configuration Template
 # Copy to /opt/stacks/authelia/configuration.yml
-# IMPORTANT: Replace '${DOMAIN}' with your actual DuckDNS domain
+# IMPORTANT: Replace environment variable placeholders with your actual values

 server:
  host: 0.0.0.0
@@ -35,7 +35,7 @@ access_control:
  default_policy: deny
  
  rules:
-    # Bypass Authelia for Jellyfin (allow app access)
+    # Bypass Authelia for media services (allow app access)
    - domain: jellyfin.${DOMAIN}
      policy: bypass
    
--- a/docker-compose/core/authelia/users_database.yml
+++ b/docker-compose/core/authelia/users_database.yml
@@ -1,12 +1,14 @@
 ###############################################################
 #                         Users Database                      #
 ###############################################################
+# Template - Replace with your actual user information
+# Generate password hash with: docker run authelia/authelia:latest authelia crypto hash generate pbkdf2 --password 'yourpassword'

 users:
-  kelin:
-    displayname: "Admin User"
-    password: "$argon2id$v=19$m=65536,t=3,p=4$a+3pIrywP/li9wy9J6UkMA$+3THyJiAnS/gNYnLaYtlsRCaYfgnnxsUyGZ4D3xGnUg"
-    email: ${DEFAULT_EMAIL}
+  admin:  # Change this username
+    displayname: "Administrator"
+    password: "GENERATE_NEW_PASSWORD_HASH"  # Replace with actual hash
+    email: your-email@example.com  # Replace with your email
    groups:
      - admins
      - users
--- a/docker-compose/core/authelia/users_database.yml.template
+++ b/docker-compose/core/authelia/users_database.yml.template
@@ -3,10 +3,11 @@
 ###############################################################

 users:
-  kelin:
-    displayname: "Admin User"
-    password: "$argon2id$v=19$m=65536,t=3,p=4$a+3pIrywP/li9wy9J6UkMA$+3THyJiAnS/gNYnLaYtlsRCaYfgnnxsUyGZ4D3xGnUg"
+  ${DEFAULT_USER}:
+    displayname: "Administrator"
+    password: "${DEFAULT_PASSWORD_HASH}"  # Generate with: docker run authelia/authelia:latest authelia crypto hash generate pbkdf2 --password 'yourpassword'
    email: ${DEFAULT_EMAIL}
    groups:
      - admins
      - users
+      - users
--- a/docker-compose/core/backup.sh
+++ b/docker-compose/core/backup.sh
@@ -0,0 +1,48 @@
+#!/bin/bash
+# Core Services Backup Script
+# Run this script to backup critical configuration files and database
+
+BACKUP_DIR="/opt/stacks/core/backups"
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+BACKUP_NAME="core_backup_${TIMESTAMP}"
+
+echo "Creating backup: ${BACKUP_NAME}"
+
+# Create backup directory
+mkdir -p "${BACKUP_DIR}/${BACKUP_NAME}"
+
+# Backup Authelia configuration and database
+echo "Backing up Authelia..."
+cp -r /opt/stacks/core/authelia/config "${BACKUP_DIR}/${BACKUP_NAME}/"
+
+# Backup Traefik configuration (excluding certificates for security)
+echo "Backing up Traefik configuration..."
+mkdir -p "${BACKUP_DIR}/${BACKUP_NAME}/traefik"
+cp -r /opt/stacks/core/traefik/config "${BACKUP_DIR}/${BACKUP_NAME}/traefik/"
+cp -r /opt/stacks/core/traefik/dynamic "${BACKUP_DIR}/${BACKUP_NAME}/traefik/"
+# Note: letsencrypt/acme.json contains private keys - backup separately if needed
+
+# Backup docker-compose.yml
+echo "Backing up docker-compose.yml..."
+cp /opt/stacks/core/docker-compose.yml "${BACKUP_DIR}/${BACKUP_NAME}/"
+
+# Backup environment file (contains sensitive data - handle carefully)
+echo "Backing up .env file..."
+cp /opt/stacks/core/.env "${BACKUP_DIR}/${BACKUP_NAME}/"
+
+# Create archive
+echo "Creating compressed archive..."
+cd "${BACKUP_DIR}"
+tar -czf "${BACKUP_NAME}.tar.gz" "${BACKUP_NAME}"
+
+# Cleanup uncompressed backup
+rm -rf "${BACKUP_NAME}"
+
+echo "Backup completed: ${BACKUP_DIR}/${BACKUP_NAME}.tar.gz"
+echo "Backup size: $(du -h "${BACKUP_DIR}/${BACKUP_NAME}.tar.gz" | cut -f1)"
+
+# Keep only last 10 backups
+echo "Cleaning up old backups..."
+ls -t "${BACKUP_DIR}"/*.tar.gz | tail -n +11 | xargs -r rm -f
+
+echo "Backup script completed successfully"
--- a/docker-compose/core/docker-compose.yml
+++ b/docker-compose/core/docker-compose.yml
@@ -15,9 +15,9 @@ services:
    container_name: duckdns
    restart: unless-stopped
    environment:
-      - PUID=${PUID}
-      - PGID=${PGID}
-      - TZ=${TZ}
+      - PUID=1000
+      - PGID=1000
+      - TZ=America/New_York
      - SUBDOMAINS=${DUCKDNS_SUBDOMAINS}
      - TOKEN=${DUCKDNS_TOKEN}
    volumes:
@@ -27,6 +27,8 @@ services:
  
  traefik:
    # Reverse proxy and SSL termination - core routing service, must always run
+    # CONFIGURATION REQUIREMENT: traefik.yml MUST be in ./traefik/config/ directory
+    # VOLUME MOUNT: ./traefik/config:/config - config file location is critical
    image: traefik:v3
    container_name: traefik
    restart: unless-stopped
@@ -62,11 +64,14 @@ services:

  authelia:
    # Single sign-on authentication service - must always run for user authentication
-    image: authelia/authelia:latest
+    # VERSION PINNING: Pinned to v4.37.5 due to breaking changes in v4.39.15+
+    # BREAKING CHANGES: v4.39.15+ has incompatible configuration and database changes
+    # UPGRADE NOTES: Test in separate environment before upgrading. Backup config and DB.
+    image: authelia/authelia:4.37.5
    container_name: authelia
    restart: unless-stopped
    environment:
-      - TZ=${TZ}
+      - TZ=America/New_York
    ports:
      - "9091:9091"
    volumes:
@@ -115,11 +120,12 @@ services:
      - SABLIER_DOCKER_API_VERSION=1.51
      - SABLIER_DOCKER_NETWORK=traefik-network
      - SABLIER_LOG_LEVEL=debug
-      - DOCKER_HOST=tcp://${SERVER_IP}:2376
-      - DOCKER_TLS_VERIFY=1
+      - DOCKER_HOST=unix:///var/run/docker.sock
+      - DOCKER_TLS_VERIFY=0
      - DOCKER_CERT_PATH=/certs
    volumes:
      - ./shared-ca:/certs:ro
+      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - 10000:10000
    labels:
--- a/docker-compose/core/docker-compose.yml.template
+++ b/docker-compose/core/docker-compose.yml.template
@@ -27,6 +27,8 @@ services:
  
  traefik:
    # Reverse proxy and SSL termination - core routing service, must always run
+    # CONFIGURATION REQUIREMENT: traefik.yml MUST be in ./traefik/config/ directory
+    # VOLUME MOUNT: ./traefik/config:/config - config file location is critical
    image: traefik:v3
    container_name: traefik
    restart: unless-stopped
@@ -62,7 +64,10 @@ services:

  authelia:
    # Single sign-on authentication service - must always run for user authentication
-    image: authelia/authelia:latest
+    # VERSION PINNING: Pinned to v4.37.5 due to breaking changes in v4.39.15+
+    # BREAKING CHANGES: v4.39.15+ has incompatible configuration and database changes
+    # UPGRADE NOTES: Test in separate environment before upgrading. Backup config and DB.
+    image: authelia/authelia:4.37.5
    container_name: authelia
    restart: unless-stopped
    environment:
--- a/docker-compose/core/traefik/acme.json
+++ b/docker-compose/core/traefik/acme.json
@@ -1,16 +0,0 @@
-{
-  "letsencrypt": {
-    "Account": {
-      "Email": "kelinfoxy@gmail.com",
-      "Registration": {
-        "body": {
-          "status": "valid"
-        },
-        "uri": "https://acme-v02.api.letsencrypt.org/acme/acct/2959423246"
-      },
-      "PrivateKey": "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",
-      "KeyType": "4096"
-    },
-    "Certificates": null
-  }
-}
--- a/docker-compose/core/traefik/traefik.yml
+++ b/docker-compose/core/traefik/traefik.yml
@@ -27,9 +27,9 @@ entryPoints:
 certificatesResolvers:
  letsencrypt:
    acme:
-      email: kelinfoxy@gmail.com  # Will be replaced by deploy script
-      caServer: https://acme-staging-v02.api.letsencrypt.org/directory
-      storage: /acme.json
+      email: ${ACME_EMAIL}  # Your email for Let's Encrypt notifications
+      caServer: https://acme-v02.api.letsencrypt.org/directory  # Use staging for testing
+      storage: /letsencrypt/acme.json
      # DNS challenge - For wildcard certificates (*.yourdomain.duckdns.org)
      # Works with DuckDNS - requires DUCKDNS_TOKEN in environment
      dnsChallenge: