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:**
```caddyfile
{
    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:**
```caddyfile
{
    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
```bash
cat /srv/digiserver-v2/Caddyfile
```

### Manually Reload Caddy
```bash
docker-compose exec caddy caddy reload --config /etc/caddy/Caddyfile
```

### Check Caddy Status
```bash
docker-compose logs caddy --tail=20
```

### Test Access Points
```bash
# 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`