diff --git a/DEPLOYMENT_STEPS_QUICK.md b/DEPLOYMENT_STEPS_QUICK.md new file mode 100644 index 0000000..47a45bb --- /dev/null +++ b/DEPLOYMENT_STEPS_QUICK.md @@ -0,0 +1,215 @@ +# πŸš€ Deployment Steps - Quick Reference + +**Total Time**: ~10 minutes | **Risk Level**: LOW | **Difficulty**: Easy + +--- + +## ⏸️ Phase 1: Pre-Deployment (Before you start) + +### Step 1: Identify Target IP +Determine what IP your host will have **after** restart: +```bash +TARGET_IP=192.168.0.121 # Example: your static production IP +``` + +### Step 2: Generate SECRET_KEY +```bash +python -c "import secrets; print(secrets.token_urlsafe(32))" +# Copy output - you'll need this +``` + +### Step 3: Create .env File +```bash +cp .env.example .env +``` + +### Step 4: Configure .env +```bash +nano .env +``` + +Edit these values in `.env`: +``` +SECRET_KEY= +ADMIN_PASSWORD= +HOST_IP=192.168.0.121 +DOMAIN=digiserver.local +TRUSTED_PROXIES=192.168.0.0/24 +``` + +--- + +## πŸ”¨ Phase 2: Build & Start (Still on current network) + +### Step 5: Build Docker Images +```bash +docker-compose build +``` + +### Step 6: Start Containers +```bash +docker-compose up -d +``` + +### Step 7: Initialize Database +```bash +docker-compose exec digiserver-app flask db upgrade +``` + +### Step 8: Wait for Startup +```bash +# Wait ~30 seconds for containers to be healthy +sleep 30 + +# Verify containers are healthy +docker-compose ps +# Look for "healthy" status on both containers +``` + +--- + +## 🌐 Phase 3: Move Host to Target Network + +### Step 9: Network Configuration +- Physically disconnect host from current network +- Connect to production network (e.g., 192.168.0.0/24) +- Host will receive/retain static IP (192.168.0.121) + +--- + +## βœ… Phase 4: Verification + +### Step 10: Test Health Endpoint +```bash +curl -k https://192.168.0.121/api/health + +# Expected response: +# {"status":"healthy","timestamp":"...","version":"2.0.0"} +``` + +### Step 11: Check Logs +```bash +docker-compose logs --tail=50 digiserver-app + +# Look for any ERROR messages +# Should see Flask running on port 5000 +``` + +### Step 12: Test API with CORS +```bash +curl -i -k https://192.168.0.121/api/playlists + +# Verify CORS headers present: +# access-control-allow-origin: * +# access-control-allow-methods: GET, POST, PUT, DELETE, OPTIONS +``` + +--- + +## πŸ“‹ Command Cheat Sheet + +```bash +# Create environment +cp .env.example .env && nano .env + +# Build and start +docker-compose build +docker-compose up -d + +# Initialize database +docker-compose exec digiserver-app flask db upgrade + +# Check status +docker-compose ps + +# View logs +docker-compose logs -f digiserver-app + +# Health check +curl -k https://192.168.0.121/api/health + +# Stop services +docker-compose down + +# Restart services +docker-compose restart +``` + +--- + +## ⏱️ Timing Breakdown + +| Phase | Duration | Notes | +|-------|----------|-------| +| Pre-deployment setup | 5 min | Configure .env | +| Docker build | 2-3 min | First time only | +| Containers start | 30 sec | Automatic | +| Database init | 10 sec | Flask migrations | +| Network move | Instant | Plug/Unplug | +| Verification | 2 min | Health checks | +| **Total** | **~10 min** | Ready to go | + +--- + +## ✨ Post-Deployment + +Once verified working: + +- **Backup .env** (contains secrets) + ```bash + cp .env /backup/.env.backup + chmod 600 /backup/.env.backup + ``` + +- **Enable backups** (optional) + ```bash + # Add to crontab for daily backups + 0 2 * * * docker-compose exec digiserver-app \ + cp instance/dashboard.db /backup/db.$(date +\%Y\%m\%d) + ``` + +- **Monitor logs** (first 24 hours) + ```bash + docker-compose logs -f digiserver-app + ``` + +--- + +## πŸ†˜ Troubleshooting Quick Fixes + +| Issue | Fix | +|-------|-----| +| Build fails | Run: `docker-compose build --no-cache` | +| Port already in use | Run: `docker-compose down` first | +| Container won't start | Check logs: `docker-compose logs digiserver-app` | +| Health check fails | Wait 30 sec longer, networks take time | +| Can't reach API | Verify host IP: `ip addr \| grep 192.168` | +| Certificate error | Curl with `-k` flag (self-signed cert) | + +--- + +## 🎯 Success Criteria + +βœ… All steps completed when: + +- [ ] `docker-compose ps` shows both containers "Up" and "healthy" +- [ ] `curl -k https://192.168.0.121/api/health` returns 200 +- [ ] CORS headers present in API responses +- [ ] No ERROR messages in logs +- [ ] Admin panel accessible at https://192.168.0.121/admin + +--- + +## πŸ“ž Need Help? + +See detailed guides: +- **General deployment**: [MASTER_DEPLOYMENT_PLAN.md](MASTER_DEPLOYMENT_PLAN.md) +- **IP configuration**: [PRE_DEPLOYMENT_IP_CONFIGURATION.md](PRE_DEPLOYMENT_IP_CONFIGURATION.md) +- **All commands**: [deployment-commands-reference.sh](deployment-commands-reference.sh) +- **Verify setup**: [verify-deployment.sh](verify-deployment.sh) + +--- + +**Status**: Ready to deploy +**Last Updated**: 2026-01-16 +**Deployment Type**: Network transition (deploy on one network, run on another) diff --git a/DOCUMENTATION_INDEX.md b/DOCUMENTATION_INDEX.md index c2e76f3..85fde9e 100644 --- a/DOCUMENTATION_INDEX.md +++ b/DOCUMENTATION_INDEX.md @@ -3,10 +3,11 @@ ## 🎯 Quick Links ### **For Immediate Deployment** πŸ‘ˆ START HERE +- **[DEPLOYMENT_STEPS_QUICK.md](DEPLOYMENT_STEPS_QUICK.md)** - ⭐ **QUICKEST** - 4 phases, 12 steps, ~10 min - **[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 +- **[PRE_DEPLOYMENT_IP_CONFIGURATION.md](PRE_DEPLOYMENT_IP_CONFIGURATION.md)** - For network transitions ### **Detailed Reference** - **[PRODUCTION_DEPLOYMENT_GUIDE.md](PRODUCTION_DEPLOYMENT_GUIDE.md)** - Full deployment procedures @@ -20,7 +21,8 @@ ### **Deployment Documentation (New)** ``` Project Root (/srv/digiserver-v2/) -β”œβ”€β”€ πŸš€ MASTER_DEPLOYMENT_PLAN.md ← START HERE +β”œβ”€β”€ ⭐ DEPLOYMENT_STEPS_QUICK.md ← START HERE (QUICKEST) +β”œβ”€β”€ πŸš€ MASTER_DEPLOYMENT_PLAN.md ← START HERE (Detailed) β”œβ”€β”€ πŸ“‹ PRODUCTION_DEPLOYMENT_GUIDE.md β”œβ”€β”€ βœ… DEPLOYMENT_READINESS_SUMMARY.md β”œβ”€β”€ ⭐ PRE_DEPLOYMENT_IP_CONFIGURATION.md ← For network transitions