Add pre-deployment IP configuration guide for network transitions

- Add HOST_IP field to .env.example with documentation
- Improve TRUSTED_PROXIES comments with examples
- Create PRE_DEPLOYMENT_IP_CONFIGURATION.md guide
- Update deployment docs with network transition workflow
- Add comprehensive IP configuration checklist

.env.example

@@ -21,7 +21,10 @@ ADMIN_EMAIL=admin@your-domain.com
 # DATABASE_URL=
 
 # Server Configuration
+# Set BEFORE deployment if host will have static IP after restart
+# This IP/domain will be used for SSL certificates and nginx configuration
 DOMAIN=your-domain.com
+HOST_IP=192.168.0.121
 EMAIL=admin@your-domain.com
 PREFERRED_URL_SCHEME=https
 
@@ -50,4 +53,10 @@ SESSION_COOKIE_HTTPONLY=true
 SESSION_COOKIE_SAMESITE=Lax
 
 # Proxy Configuration (configured in app.py)
-TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
+# IMPORTANT: Set this to your actual network range or specific proxy IP
+# Examples:
+#   - 192.168.0.0/24 (local network with /24 subnet)
+#   - 10.0.0.0/8 (AWS or similar cloud)
+#   - 172.16.0.0/12 (Docker networks)
+# For multiple IPs: 192.168.0.121,10.0.1.50
+TRUSTED_PROXIES=192.168.0.0/24

DOCUMENTATION_INDEX.md

@@ -6,6 +6,7 @@
 - **[MASTER_DEPLOYMENT_PLAN.md](MASTER_DEPLOYMENT_PLAN.md)** - Complete 5-minute deployment guide
 - **[.env.example](.env.example)** - Environment configuration template
 - **[DEPLOYMENT_READINESS_SUMMARY.md](DEPLOYMENT_READINESS_SUMMARY.md)** - Current status verification
+- **[PRE_DEPLOYMENT_IP_CONFIGURATION.md](PRE_DEPLOYMENT_IP_CONFIGURATION.md)** - ⭐ **NEW** - For network transitions
 
 ### **Detailed Reference**
 - **[PRODUCTION_DEPLOYMENT_GUIDE.md](PRODUCTION_DEPLOYMENT_GUIDE.md)** - Full deployment procedures
@@ -22,6 +23,7 @@ Project Root (/srv/digiserver-v2/)
 ├── 🚀 MASTER_DEPLOYMENT_PLAN.md              ← START HERE
 ├── 📋 PRODUCTION_DEPLOYMENT_GUIDE.md
 ├── ✅ DEPLOYMENT_READINESS_SUMMARY.md
+├── ⭐ PRE_DEPLOYMENT_IP_CONFIGURATION.md      ← For network transitions
 ├── 🔧 .env.example
 ├── 📖 deployment-commands-reference.sh
 └── ✔️ verify-deployment.sh

MASTER_DEPLOYMENT_PLAN.md

@@ -27,6 +27,19 @@ OVERALL: 95% READY FOR PRODUCTION
 
 ## 🚀 Five-Minute Deployment
 
+### Step 0: Configure Target IP (If deploying on different network)
+
+**Special case**: If your host will be on a different IP after deployment/restart:
+
+```bash
+# See: PRE_DEPLOYMENT_IP_CONFIGURATION.md for detailed instructions
+# Quick version:
+TARGET_IP=192.168.0.121      # What IP will host have AFTER deployment?
+TARGET_DOMAIN=digiserver.local  # Optional domain name
+```
+
+This must be set in `.env` BEFORE running `docker-compose up -d`
+
 ### Step 1: Prepare (2 minutes)
 ```bash
 cd /opt/digiserver-v2

PRE_DEPLOYMENT_IP_CONFIGURATION.md

@@ -0,0 +1,346 @@
+# Pre-Deployment IP Configuration Guide
+
+## 🎯 Purpose
+
+This guide helps you configure the host IP address **before deployment** when your host:
+- Is currently on a **different network** during deployment
+- Will move to a **static IP** after deployment/restart
+- Needs SSL certificates and nginx config set up for that **future IP**
+
+---
+
+## 📋 Pre-Deployment Workflow
+
+### Step 1: Identify Your Target IP Address
+
+**Before deployment**, determine what IP your host will have **after** it's deployed and restarted:
+
+```bash
+# Example: Your host will be at 192.168.0.121 after deployment
+TARGET_IP=192.168.0.121
+DOMAIN_NAME=digiserver.local  # or your domain
+```
+
+### Step 2: Create .env File with Target IP
+
+```bash
+cp .env.example .env
+
+# Edit .env with your VALUES:
+cat > .env << 'EOF'
+FLASK_ENV=production
+SECRET_KEY=<your-generated-secret-key>
+ADMIN_USERNAME=admin
+ADMIN_PASSWORD=<your-strong-password>
+ADMIN_EMAIL=admin@company.com
+
+# TARGET IP/Domain (where host will be AFTER deployment)
+DOMAIN=digiserver.local
+HOST_IP=192.168.0.121
+EMAIL=admin@company.com
+
+# Network configuration for this subnet
+TRUSTED_PROXIES=192.168.0.0/24
+
+PREFERRED_URL_SCHEME=https
+ENABLE_LIBREOFFICE=true
+LOG_LEVEL=INFO
+EOF
+
+chmod 600 .env
+```
+
+### Step 3: Update nginx.conf with Target IP
+
+If you want nginx to reference the IP (optional, domain is preferred):
+
+```bash
+# View current nginx config
+cat nginx.conf | grep -A 5 "server_name"
+
+# If needed, update server_name in nginx.conf:
+# server_name 192.168.0.121 digiserver.local;
+```
+
+### Step 4: Configure SSL Certificate for Target IP
+
+The self-signed certificate should be generated for your target IP/domain:
+
+```bash
+# Check current certificate
+openssl x509 -in data/nginx-ssl/cert.pem -text -noout | grep -A 2 "Subject:"
+
+# If you need to regenerate for new IP:
+cd data/nginx-ssl/
+
+# Generate new self-signed cert (valid 1 year)
+openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
+  -days 365 -nodes \
+  -subj "/C=US/ST=State/L=City/O=Org/CN=192.168.0.121"
+
+# OR with domain:
+openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
+  -days 365 -nodes \
+  -subj "/C=US/ST=State/L=City/O=Org/CN=digiserver.local"
+```
+
+---
+
+## 🔧 Configuration Reference
+
+### .env Fields for IP Configuration
+
+```bash
+# Primary configuration
+DOMAIN=digiserver.local          # DNS name (preferred over IP)
+HOST_IP=192.168.0.121            # Static IP after deployment
+PREFERRED_URL_SCHEME=https        # Always use HTTPS
+
+# Network security
+TRUSTED_PROXIES=192.168.0.0/24    # Your subnet range
+
+# Application URLs will use these values:
+# - https://digiserver.local/api/health
+# - https://192.168.0.121/admin
+```
+
+### Example Configurations
+
+**Scenario 1: Local Network (Recommended)**
+```bash
+DOMAIN=digiserver.local
+HOST_IP=192.168.0.121
+TRUSTED_PROXIES=192.168.0.0/24
+```
+
+**Scenario 2: Cloud Deployment (AWS)**
+```bash
+DOMAIN=digiserver.company.com
+HOST_IP=10.0.1.50
+TRUSTED_PROXIES=10.0.0.0/8
+```
+
+**Scenario 3: Multiple Networks**
+```bash
+DOMAIN=digiserver.local
+HOST_IP=192.168.0.121
+# Trust multiple networks during transition
+TRUSTED_PROXIES=192.168.0.0/24,10.0.0.0/8
+```
+
+---
+
+## 📝 Deployment Checklist with IP Configuration
+
+Before running `docker-compose up -d`:
+
+- [ ] **Determine target IP/domain**
+  ```bash
+  # What will this host's IP be after deployment?
+  TARGET_IP=192.168.0.121
+  ```
+
+- [ ] **Create .env file**
+  ```bash
+  cp .env.example .env
+  nano .env  # Edit with target IP
+  ```
+
+- [ ] **Verify values in .env**
+  ```bash
+  grep "DOMAIN\|HOST_IP\|TRUSTED_PROXIES" .env
+  ```
+
+- [ ] **Check SSL certificate**
+  ```bash
+  ls -la data/nginx-ssl/
+  openssl x509 -enddate -noout -in data/nginx-ssl/cert.pem
+  ```
+
+- [ ] **Generate new cert if needed**
+  ```bash
+  cd data/nginx-ssl/
+  openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
+    -days 365 -nodes -subj "/C=US/ST=State/L=City/O=Org/CN=192.168.0.121"
+  ```
+
+- [ ] **Deploy**
+  ```bash
+  docker-compose build
+  docker-compose up -d
+  docker-compose exec digiserver-app flask db upgrade
+  ```
+
+---
+
+## 🔄 Network Transition Workflow
+
+### Scenario: Deploy on Network A, Run on Network B
+
+**During Deployment (Network A):**
+```bash
+# Host might be at 10.0.0.50 currently, but will be 192.168.0.121 after
+cp .env.example .env
+
+# SET .env with FUTURE IP
+echo "HOST_IP=192.168.0.121" >> .env
+echo "DOMAIN=digiserver.local" >> .env
+echo "TRUSTED_PROXIES=192.168.0.0/24" >> .env
+
+docker-compose build
+docker-compose up -d
+docker-compose exec digiserver-app flask db upgrade
+```
+
+**After Host Moves to New Network:**
+```bash
+# Host is now at 192.168.0.121
+# Container still uses config from .env (which already has correct IP)
+
+# Verify it's working
+curl -k https://192.168.0.121/api/health
+
+# No additional config needed - already set in .env!
+```
+
+---
+
+## 🛠️ Troubleshooting IP Configuration
+
+### Issue: Certificate doesn't match IP
+
+```bash
+# Check certificate IP
+openssl x509 -in data/nginx-ssl/cert.pem -text -noout | grep -A 2 "Subject Alt"
+
+# Regenerate if needed
+cd data/nginx-ssl/
+rm cert.pem key.pem
+openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
+  -days 365 -nodes -subj "/C=US/ST=State/L=City/O=Org/CN=192.168.0.121"
+
+# Restart nginx
+docker-compose restart nginx
+```
+
+### Issue: Connection refused on new IP
+
+```bash
+# Verify .env has correct IP
+cat .env | grep "HOST_IP\|DOMAIN"
+
+# Check if containers are running
+docker-compose ps
+
+# Check nginx config
+docker-compose exec nginx grep "server_name" /etc/nginx/nginx.conf
+
+# View nginx error logs
+docker-compose logs nginx
+```
+
+### Issue: TRUSTED_PROXIES not working
+
+```bash
+# Verify setting in .env
+grep "TRUSTED_PROXIES" .env
+
+# Check Flask is using it
+docker-compose exec digiserver-app python -c "
+from app.config import ProductionConfig
+print(f'TRUSTED_PROXIES: {ProductionConfig.TRUSTED_PROXIES}')
+"
+
+# If not set, rebuild:
+docker-compose down
+docker-compose build --no-cache
+docker-compose up -d
+```
+
+---
+
+## 📊 IP Configuration Quick Reference
+
+| Setting | Purpose | Example |
+|---------|---------|---------|
+| `DOMAIN` | Primary access URL | `digiserver.local` |
+| `HOST_IP` | Static IP after deployment | `192.168.0.121` |
+| `TRUSTED_PROXIES` | IPs that can forward headers | `192.168.0.0/24` |
+| `PREFERRED_URL_SCHEME` | HTTP or HTTPS | `https` |
+
+---
+
+## ✅ Verification After Deployment
+
+Once host is on its target IP:
+
+```bash
+# Test health endpoint
+curl -k https://192.168.0.121/api/health
+
+# Test with domain (if using DNS)
+curl -k https://digiserver.local/api/health
+
+# Check certificate info
+openssl s_client -connect 192.168.0.121:443 -showcerts
+
+# Verify CORS headers
+curl -i -k https://192.168.0.121/api/playlists
+```
+
+---
+
+## 🔐 Security Notes
+
+1. **Use DOMAIN over IP** when possible (DNS is more flexible)
+2. **TRUSTED_PROXIES** should match your network (not 0.0.0.0/0)
+3. **Certificate** should be valid for your actual IP/domain
+4. **Backup .env** - it contains SECRET_KEY and passwords
+
+---
+
+## 📋 Complete Pre-Deployment Checklist
+
+```
+PRE-DEPLOYMENT IP CONFIGURATION CHECKLIST
+==========================================
+
+Network Planning:
+  [ ] Determine host's TARGET IP address
+  [ ] Determine host's TARGET domain name (if any)
+  [ ] Identify network subnet (e.g., 192.168.0.0/24)
+
+Configuration:
+  [ ] Create .env file from .env.example
+  [ ] Set DOMAIN to target domain/IP
+  [ ] Set HOST_IP to target static IP
+  [ ] Set TRUSTED_PROXIES to your network range
+  [ ] Generate/verify SSL certificate for target IP
+  [ ] Review all sensitive values (passwords, keys)
+
+Deployment:
+  [ ] Run docker-compose build
+  [ ] Run docker-compose up -d
+  [ ] Run database migrations
+  [ ] Wait for containers to be healthy
+
+Verification (After Host IP Change):
+  [ ] Host has static IP assigned
+  [ ] Test: curl -k https://TARGET_IP/api/health
+  [ ] Test: curl -k https://DOMAIN/api/health (if using DNS)
+  [ ] Check SSL certificate matches
+  [ ] Verify CORS headers present
+  [ ] Check logs for errors
+
+Post-Deployment:
+  [ ] Backup .env file securely
+  [ ] Document deployment IP/domain for future ref
+  [ ] Set up backups
+  [ ] Monitor logs for 24 hours
+```
+
+---
+
+**Status**: Ready to use for network transition deployments  
+**Last Updated**: 2026-01-16  
+**Use Case**: Deploy on temp network, run on production network with static IP