digiserver-v2/PRE_DEPLOYMENT_IP_CONFIGURATION.md

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:

# 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

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):

# 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:

# 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

# 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)

DOMAIN=digiserver.local
HOST_IP=192.168.0.121
TRUSTED_PROXIES=192.168.0.0/24

Scenario 2: Cloud Deployment (AWS)

DOMAIN=digiserver.company.com
HOST_IP=10.0.1.50
TRUSTED_PROXIES=10.0.0.0/8

Scenario 3: Multiple Networks

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

  # What will this host's IP be after deployment?
  TARGET_IP=192.168.0.121
  

• Create .env file

  cp .env.example .env
  nano .env  # Edit with target IP
  

• Verify values in .env

  grep "DOMAIN\|HOST_IP\|TRUSTED_PROXIES" .env
  

• Check SSL certificate

  ls -la data/nginx-ssl/
  openssl x509 -enddate -noout -in data/nginx-ssl/cert.pem
  

• Generate new cert if needed

  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

  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):

# 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:

# 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

# 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

# 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

# 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:

# 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