From 52e910346bee4a83ce416c4949a9d4396e2ce54a Mon Sep 17 00:00:00 2001 From: Deployment System Date: Fri, 16 Jan 2026 22:40:34 +0200 Subject: [PATCH] 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 | 11 +- DOCUMENTATION_INDEX.md | 4 +- MASTER_DEPLOYMENT_PLAN.md | 13 ++ PRE_DEPLOYMENT_IP_CONFIGURATION.md | 346 +++++++++++++++++++++++++++++ 4 files changed, 372 insertions(+), 2 deletions(-) create mode 100644 PRE_DEPLOYMENT_IP_CONFIGURATION.md diff --git a/.env.example b/.env.example index 03768d1..afacb79 100644 --- a/.env.example +++ b/.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 diff --git a/DOCUMENTATION_INDEX.md b/DOCUMENTATION_INDEX.md index 6da629a..c2e76f3 100644 --- a/DOCUMENTATION_INDEX.md +++ b/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 @@ -19,9 +20,10 @@ ### **Deployment Documentation (New)** ``` Project Root (/srv/digiserver-v2/) -├── 🚀 MASTER_DEPLOYMENT_PLAN.md ← START HERE +├── 🚀 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 diff --git a/MASTER_DEPLOYMENT_PLAN.md b/MASTER_DEPLOYMENT_PLAN.md index f8305e1..6a2d2a5 100644 --- a/MASTER_DEPLOYMENT_PLAN.md +++ b/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 diff --git a/PRE_DEPLOYMENT_IP_CONFIGURATION.md b/PRE_DEPLOYMENT_IP_CONFIGURATION.md new file mode 100644 index 0000000..a00af91 --- /dev/null +++ b/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= +ADMIN_USERNAME=admin +ADMIN_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