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:

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