ske087/digiserver-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add pre-deployment IP configuration guide for network transitions

Browse Source 
- 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
This commit is contained in:
Deployment System
2026-01-16 22:40:34 +02:00
parent f2470e27ec
commit 52e910346b
4 changed files with 372 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
.env.example
View File

@@ -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

4
DOCUMENTATION_INDEX.md
View File

@@ -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

13
MASTER_DEPLOYMENT_PLAN.md
View File

@@ -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

346
PRE_DEPLOYMENT_IP_CONFIGURATION.md Normal file
View File

@@ -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