digiserver-v2/old_code_documentation/CADDY_DYNAMIC_CONFIG.md

Caddy Dynamic Configuration Management

Overview

The HTTPS configuration system now automatically generates and manages the Caddy configuration in real-time. When an admin updates settings through the admin panel, the Caddyfile is regenerated and reloaded without requiring a full container restart.

How It Works

1. Configuration Generation

When admin saves HTTPS settings:

1. Settings are saved to database (HTTPSConfig table)
2. CaddyConfigGenerator creates a new Caddyfile based on settings
3. Generated Caddyfile is written to disk

2. Configuration Reload

After Caddyfile is written:

1. Caddy reload API is called via docker-compose exec
2. Caddy validates and applies new configuration
3. No downtime - live configuration update

3. Fallback Configuration

If HTTPS is disabled:

1. System uses default hardcoded configuration
2. Supports localhost, internal domain, and IP address
3. Catch-all configuration for any other requests

Files Involved

New Files

• app/utils/caddy_manager.py - CaddyConfigGenerator class with:
  • generate_caddyfile() - Generates Caddyfile content
  • write_caddyfile() - Writes to disk
  • reload_caddy() - Reloads via Docker

Updated Files

• app/blueprints/admin.py - HTTPS config route now:
  • Generates new Caddyfile
  • Writes to disk
  • Reloads Caddy automatically
  • Reports status to user

Admin Panel Workflow

Step 1: User Fills Form

Admin Panel → HTTPS Configuration
- Hostname: digiserver
- Domain: digiserver.sibiusb.harting.intra
- Email: admin@example.com
- IP: 10.76.152.164
- Port: 443

Step 2: Admin Saves Configuration

• POST /admin/https-config/update
• Settings validated and saved to database
• Caddyfile generated dynamically
• Caddy reloaded with new configuration

Step 3: User Sees Confirmation

✅ HTTPS configuration saved successfully!
✅ Caddy configuration updated successfully!
Server available at https://digiserver.sibiusb.harting.intra

Step 4: Configuration Live

• New domain/IP immediately active
• No container restart needed
• Caddy applying new routes in real-time

Generated Caddyfile Structure

When HTTPS Enabled:

{
    email admin@example.com
}

(reverse_proxy_config) {
    reverse_proxy digiserver-app:5000 { ... }
    request_body { max_size 2GB }
    header { ... }
    log { ... }
}

http://localhost { import reverse_proxy_config }
http://digiserver.sibiusb.harting.intra { import reverse_proxy_config }
http://10.76.152.164 { import reverse_proxy_config }
http://* { import reverse_proxy_config }

When HTTPS Disabled:

{
    email admin@localhost
}

(reverse_proxy_config) { ... }

http://localhost { import reverse_proxy_config }
http://digiserver.sibiusb.harting.intra { import reverse_proxy_config }
http://10.76.152.164 { import reverse_proxy_config }
http://* { import reverse_proxy_config }

Key Features

✅ No Restart Required

• Caddyfile changes applied without restarting containers
• Caddy reload API handles configuration hot-swap
• Zero downtime configuration updates

✅ Dynamic Configuration

• Settings in admin panel → Generated Caddyfile
• Database is source of truth
• Easy to modify in admin UI

✅ Automatic Fallbacks

• Catch-all http://* handles any host
• Always has localhost access
• Always has IP address access

✅ User Feedback

• Admin sees status of Caddy reload
• Error messages if Caddy reload fails
• Logging of all changes

✅ Safe Updates

• Caddyfile validation before reload
• Graceful error handling
• Falls back to previous config if reload fails

Error Handling

If Caddy reload fails:

1. Database still has updated settings
2. Old Caddyfile may still be in use
3. User sees warning with status
4. Admin can manually restart: docker-compose restart caddy

Admin Panel Status Messages

Success (✅)

✅ HTTPS configuration saved successfully!
✅ Caddy configuration updated successfully!
Server available at https://domain.local

Partial Success (⚠️)

✅ HTTPS configuration saved successfully!
⚠️ Caddyfile updated but reload failed. Please restart containers.
Server available at https://domain.local

Configuration Saved, Update Failed (⚠️)

⚠️ Configuration saved but Caddy update failed: [error details]

Testing Configuration

Check Caddyfile Content

cat /srv/digiserver-v2/Caddyfile

Manually Reload Caddy

docker-compose exec caddy caddy reload --config /etc/caddy/Caddyfile

Check Caddy Status

docker-compose logs caddy --tail=20

Test Access Points

# Test all configured domains/IPs
curl http://localhost
curl http://digiserver.sibiusb.harting.intra
curl http://10.76.152.164

Configuration Database

Settings stored in https_config table:

https_enabled: boolean
hostname: string
domain: string
ip_address: string
email: string
port: integer
updated_at: datetime
updated_by: string

When admin updates form → Database updated → Caddyfile regenerated → Caddy reloaded

Workflow Diagram

┌─────────────────────┐
│  Admin Panel Form    │
│  (HTTPS Config)     │
└──────────┬──────────┘
           │ Submit
           ↓
┌─────────────────────┐
│  Validate Input     │
└──────────┬──────────┘
           │ Valid
           ↓
┌─────────────────────┐
│  Save to Database   │
│ (HTTPSConfig)       │
└──────────┬──────────┘
           │ Saved
           ↓
┌─────────────────────┐
│  Generate Caddyfile │
│ (CaddyConfigGen)    │
└──────────┬──────────┘
           │ Generated
           ↓
┌─────────────────────┐
│  Write to Disk      │
│ (/Caddyfile)        │
└──────────┬──────────┘
           │ Written
           ↓
┌─────────────────────┐
│  Reload Caddy       │
│ (Docker exec)       │
└──────────┬──────────┘
           │ Reloaded
           ↓
┌─────────────────────┐
│  Show Status to     │
│  Admin (Success)    │
└─────────────────────┘

Implementation Details

CaddyConfigGenerator Class

generate_caddyfile(config)

• Takes HTTPSConfig from database
• Generates complete Caddyfile content
• Uses shared reverse proxy configuration template
• Returns full Caddyfile as string

write_caddyfile(content, path)

• Writes generated content to disk
• Path defaults to /srv/digiserver-v2/Caddyfile
• Returns True on success, False on error

reload_caddy()

• Runs: docker-compose exec -T caddy caddy reload
• Validates config and applies live
• Returns True on success, False on error

Advantages Over Manual Configuration

Manual	Dynamic
Edit Caddyfile manually	Change via admin panel
Restart container	No restart needed
Risk of syntax errors	Validated generation
No audit trail	Logged with username
Each change is manual	One-time setup

Future Enhancements

Potential improvements:

• Configuration history/backup
• Rollback to previous config
• Health check after reload
• Automatic backup before update
• Configuration templates
• Multi-domain support

Support

For issues:

1. Check admin panel messages for Caddy reload status
2. Review logs: docker-compose logs caddy
3. Check Caddyfile: cat /srv/digiserver-v2/Caddyfile
4. Manual reload: docker-compose exec caddy caddy reload --config /etc/caddy/Caddyfile
5. Full restart: docker-compose restart caddy