digiserver-v2/old_code_documentation/HTTPS_EMAIL_UPDATE.md

# HTTPS Email Configuration - Update Guide

## What's New

The HTTPS configuration system now includes an **Email Address** field that is essential for:
- SSL certificate management (Let's Encrypt)
- Certificate expiration notifications
- Certificate renewal reminders

## Changes Made

### 1. **Database Model** (`app/models/https_config.py`)
- Added `email` field to HTTPSConfig model
- Updated `create_or_update()` method to accept email parameter
- Updated `to_dict()` method to include email in output

### 2. **Admin Routes** (`app/blueprints/admin.py`)
- Added email form field handling
- Added email validation (checks for '@' symbol)
- Updated configuration save to store email
- Updated logging to include email in configuration changes

### 3. **Admin Template** (`app/templates/admin/https_config.html`)
- Added email input field in configuration form
- Added email display in status section
- Added help text explaining email purpose
- Email marked as required when HTTPS is enabled

### 4. **CLI Utility** (`https_manager.py`)
- Updated enable command to accept email parameter
- Updated help text to show email requirement
- Example: `python https_manager.py enable digiserver domain.local admin@example.com 10.76.152.164`

### 5. **Database Migration** (`migrations/add_email_to_https_config.py`)
- New migration script to add email column to existing database

## Update Instructions

### Step 1: Run Database Migration
```bash
# Add email column to existing https_config table
python /app/migrations/add_email_to_https_config.py
```

### Step 2: Restart Application
```bash
docker-compose restart
```

### Step 3: Configure Email via Admin Panel
1. Navigate to: **Admin Panel → 🔒 HTTPS Configuration**
2. Fill in the new **Email Address** field
3. Example: `admin@example.com`
4. Click **Save HTTPS Configuration**

## Configuration Form - New Field

```html
<!-- Email Field -->
<label for="email">Email Address *</label>
<input type="email" id="email" name="email" 
       value="admin@example.com"
       placeholder="e.g., admin@example.com"
       required>
<p>Email address for SSL certificate notifications and Let's Encrypt communications</p>
```

## CLI Usage - New Syntax

**Old (still works for HTTP):**
```bash
python https_manager.py enable digiserver domain.local 10.76.152.164 443
```

**New (with email - recommended):**
```bash
python https_manager.py enable digiserver domain.local admin@example.com 10.76.152.164 443
```

## Status Display - Updated

The status card now shows:
```
✅ HTTPS ENABLED
Domain: digiserver.sibiusb.harting.intra
Hostname: digiserver
Email: admin@example.com  ← NEW
IP Address: 10.76.152.164
Port: 443
Access URL: https://digiserver.sibiusb.harting.intra
Last Updated: 2026-01-14 15:30:45 by admin
```

## Validation

The system now validates:
- ✅ Email format (must contain '@')
- ✅ Email is required when HTTPS is enabled
- ✅ Email is stored in database
- ✅ Email is logged when configuration changes

## Benefits

📧 **Proper SSL Certificate Management**
- Let's Encrypt sends notifications to configured email
- Certificate expiration warnings before renewal

📋 **Better Configuration**
- Email is persisted in database
- No need to set environment variables
- Fully managed through admin panel

🔐 **Professional Setup**
- Real email address for certificate notifications
- Easier to manage multiple servers
- Complete audit trail with email address

## Backwards Compatibility

If you have an existing HTTPS configuration without an email:
1. The email field will be NULL
2. You'll see an error when trying to use HTTPS without email
3. Simply add the email through the admin panel and save
4. Configuration will be complete

## Database Schema Update

```sql
ALTER TABLE https_config ADD COLUMN email VARCHAR(255);
```

New schema:
```
https_config table:
├── id (PK)
├── https_enabled (BOOLEAN)
├── hostname (VARCHAR)
├── domain (VARCHAR)
├── ip_address (VARCHAR)
├── email (VARCHAR) ← NEW
├── port (INTEGER)
├── created_at (DATETIME)
├── updated_at (DATETIME)
└── updated_by (VARCHAR)
```

## Example Configuration

**Complete HTTPS Setup:**
```
Hostname: digiserver
Domain: digiserver.sibiusb.harting.intra
Email: admin@example.com
IP: 10.76.152.164
Port: 443
Status: ✅ ENABLED
```

## Troubleshooting

### Email Field Not Showing?
1. Clear browser cache (Ctrl+Shift+Del)
2. Reload the page
3. Check that containers restarted: `docker-compose restart`

### Migration Error?
If migration fails:
```bash
# Option 1: Add column manually
docker-compose exec digiserver-app python -c "
from app.app import create_app
from app.extensions import db
from sqlalchemy import text
app = create_app()
with app.app_context():
    db.engine.execute(text('ALTER TABLE https_config ADD COLUMN email VARCHAR(255)'))
"

# Option 2: Reset database (if testing)
rm instance/digiserver.db
python /app/migrations/add_https_config_table.py
```

### "Email Required" Error When HTTPS Enabled?
- Admin panel: Fill in the Email Address field before saving
- CLI: Include email in command: `python https_manager.py enable ... email@example.com ...`

## Next Steps

1. Run the database migration
2. Restart the application
3. Navigate to HTTPS Configuration
4. Enter a valid email address (e.g., `admin@example.com`)
5. Enable HTTPS
6. System will use this email for Let's Encrypt notifications

## Support

For issues or questions:
- Check `HTTPS_CONFIGURATION.md` for detailed documentation
- See `HTTPS_QUICK_REFERENCE.md` for quick examples
- Review server logs in admin panel for configuration changes