digiserver-v2/old_code_documentation/HTTPS_CONFIGURATION.md

# HTTPS Configuration Management System

## Overview

The DigiServer v2 now includes a built-in HTTPS configuration management system accessible through the Admin Panel. This allows administrators to enable and manage HTTPS/SSL settings directly from the web interface without needing to manually edit configuration files.

## Features

- **Enable/Disable HTTPS**: Toggle HTTPS on and off from the admin panel
- **Domain Management**: Set the full domain name (e.g., `digiserver.sibiusb.harting.intra`)
- **Hostname Configuration**: Configure server hostname (e.g., `digiserver`)
- **IP Address Management**: Set the IP address for direct access (e.g., `10.76.152.164`)
- **Port Configuration**: Customize HTTPS port (default: 443)
- **Status Tracking**: View current HTTPS status and configuration details
- **Real-time Preview**: See access points as you configure settings

## Workflow

### Step 1: Initial Setup (HTTP Only)
1. Start the application normally: `docker-compose up -d`
2. The app runs on HTTP port 80
3. Access via: `http://<server-ip>`

### Step 2: Enable HTTPS via Admin Panel
1. Log in to the admin panel as an administrator
2. Navigate to: **Admin Panel → 🔒 HTTPS Configuration**
3. Toggle the "Enable HTTPS" switch
4. Fill in the required fields:
   - **Hostname**: Short name for your server (e.g., `digiserver`)
   - **Full Domain Name**: Complete domain (e.g., `digiserver.sibiusb.harting.intra`)
   - **IP Address**: Server IP address (e.g., `10.76.152.164`)
   - **HTTPS Port**: Port number (default: 443)

### Step 3: Verify Configuration
1. The status section shows your HTTPS configuration
2. Access points are displayed:
   - HTTPS: `https://digiserver.sibiusb.harting.intra`
   - HTTP fallback: `http://10.76.152.164`

## Configuration Details

### Database Model (HTTPSConfig)

The configuration is stored in the `https_config` table with the following fields:

```python
- id: Primary key
- https_enabled: Boolean flag for HTTPS status
- hostname: Server hostname
- domain: Full domain name
- ip_address: IPv4 or IPv6 address
- port: HTTPS port (default: 443)
- created_at: Creation timestamp
- updated_at: Last modification timestamp
- updated_by: Username of admin who made the change
```

### Admin Routes

- **GET /admin/https-config**: View HTTPS configuration page
- **POST /admin/https-config/update**: Update HTTPS settings
- **GET /admin/https-config/status**: Get current status as JSON

## Integration with Docker & Caddy

The HTTPS configuration works in conjunction with:

1. **Caddy Reverse Proxy**: Automatically handles SSL/TLS
2. **Let's Encrypt**: Provides free SSL certificates
3. **docker-compose.yml**: Uses the configured domain for Caddy

### Current Setup

**docker-compose.yml** uses `digiserver.sibiusb.harting.intra` as the primary domain.

**Caddyfile** configurations:
- HTTPS: `digiserver.sibiusb.harting.intra` (auto-managed SSL)
- HTTP Fallback: `10.76.152.164` (direct IP access)

## Prerequisites

Before enabling HTTPS, ensure:

1. **DNS Resolution**: Domain must resolve to the server's IP
   ```bash
   # Test DNS resolution
   nslookup digiserver.sibiusb.harting.intra
   ```

2. **Ports Accessible**:
   - Port 80 (HTTP): For Let's Encrypt challenges
   - Port 443 (HTTPS): For secure traffic
   - Port 443/UDP: For HTTP/3 support

3. **Firewall Rules**: Ensure inbound traffic is allowed on ports 80 and 443

4. **Hosts File** (if DNS not available):
   ```
   10.76.152.164 digiserver.sibiusb.harting.intra
   ```

## Database Migration

To set up the HTTPS configuration table, run:

```bash
# From inside the Docker container
python /app/migrations/add_https_config_table.py

# Or from the host machine
docker-compose exec digiserver-app python /app/migrations/add_https_config_table.py
```

## Access Points After Configuration

### HTTPS (Recommended)
- URL: `https://digiserver.sibiusb.harting.intra`
- Protocol: HTTPS with SSL/TLS
- Automatic redirects from HTTP
- Let's Encrypt certificate (auto-renewed)

### HTTP Fallback
- URL: `http://10.76.152.164`
- Protocol: Plain HTTP (no encryption)
- Used when domain is not accessible
- Automatically redirects to HTTPS

## Security Features

✅ Automatic SSL certificate management (Let's Encrypt)
✅ Automatic certificate renewal
✅ Security headers (HSTS, X-Frame-Options, etc.)
✅ HTTP/2 and HTTP/3 support
✅ Admin-only access to configuration

## Logging

All HTTPS configuration changes are logged in the server logs:

```
✓ HTTPS enabled by admin: domain=digiserver.sibiusb.harting.intra, hostname=digiserver, ip=10.76.152.164
✓ HTTPS disabled by admin
```

Check admin panel → Logs for detailed audit trail.

## Troubleshooting

### HTTPS Not Working
1. Verify DNS resolution: `nslookup digiserver.sibiusb.harting.intra`
2. Check Caddy logs: `docker-compose logs caddy`
3. Ensure ports 80 and 443 are open
4. Check firewall rules

### Certificate Issues
1. Check Caddy container logs
2. Verify domain is accessible from internet
3. Ensure Let's Encrypt can validate domain
4. Check email configuration for certificate notifications

### Configuration Not Applied
1. Verify database migration ran: `python migrations/add_https_config_table.py`
2. Restart containers: `docker-compose restart`
3. Check admin panel for error messages
4. Review server logs

## Example Configuration

For a typical setup:

```
Hostname: digiserver
Domain: digiserver.sibiusb.harting.intra
IP Address: 10.76.152.164
Port: 443
HTTPS Status: Enabled ✅
```

Access via:
- `https://digiserver.sibiusb.harting.intra` ← Primary
- `http://10.76.152.164` ← Fallback

## Future Enhancements

Potential improvements for future versions:

- Certificate upload/management interface
- Domain validation checker
- Automatic DNS verification
- Custom SSL certificate support
- Certificate expiration notifications
- A/B testing for domain migration