# Phase 6: Deployment & Scale — Context & Strategic Overview **Phase Goal**: Production-ready multi-site deployment with automated setup, scale testing, and operational runbooks. **Duration**: 1 month **Target Version**: v2.0 stable --- ## Phase Overview Phase 6 bridges the gap between fully-featured code (Phases 4.1 + 5) and production deployment at scale. After Phase 5 delivers search, exports, and quick quantity adjustment, the system needs: 1. **Containerization** — Reliable Docker/Compose setup for rapid multi-site rollout 2. **Automation** — Single-command deployment (environment agnostic) 3. **Scale validation** — Prove system handles 10K items + 5 concurrent users without degradation 4. **Performance tuning** — Identify and fix bottlenecks revealed by load testing 5. **Operational readiness** — Backup/restore, disaster recovery, runbook documentation --- ## Key Decisions Made During Planning ### 1. Docker Strategy - **Existing**: docker-compose.yml and Dockerfiles already in place (backend/, proxy/) - **Gap**: Automated deployment scripts, environment templates, CI/CD hooks - **Plan 1 Focus**: Enhance existing Dockerfiles → production-grade, add health checks, optimize layers - **Multi-site**: Single docker-compose.yml template with `.env` overrides per site ### 2. Deployment Automation - **Target**: `./deploy.sh` (single entry point) — no manual steps - **Scope**: Config validation, DB initialization, certificate generation, health checks - **Fallback**: Documented manual steps for troubleshooting - **Testing**: Pre-flight checks (port availability, storage, permissions) ### 3. Scale Testing Approach - **Load Profile**: 10K items + 5 concurrent users (realistic field scenario) - **Tools**: Locust (Python) for backend load testing, Playwright for frontend workflow - **Metrics**: Response time <2s for search/scan, CPU/memory usage, sync reliability - **Plan 2 Focus**: Load testing infrastructure + performance baseline + optimization recommendations ### 4. Backup/Restore Philosophy - **Data**: SQLite DB + config files + certificate state - **Versioning**: Backup includes timestamp + version number for easy rollback - **Testing**: Automated restore test on each backup cycle - **Plan 3 Focus**: Backup automation script, restore validation, documented RTO/RPO ### 5. Operational Documentation - **Audience**: Ops teams deploying to new sites; minimal Docker/Python knowledge required - **Format**: Runbook style (step-by-step checklists) - **Coverage**: Deployment, scaling, troubleshooting, health monitoring, upgrade path --- ## Upstream Dependencies ### Phase 5 Completion Required - ✓ Quick Quantity Adjustment feature (UI + API) - ✓ Search & Filtering feature (modal + backend) - ✓ Export/Reports feature (CSV/Excel + admin UI) - ✓ All tests passing (Vitest + Pytest) - ✓ No critical bugs in dev branch ### Existing Infrastructure - ✓ docker-compose.yml (3 services: backend, frontend, proxy) - ✓ Backend Dockerfile (Python 3.12 + FastAPI) - ✓ Frontend Dockerfile (Node.js + Next.js) - ✓ Caddy proxy with HTTPS (self-signed certs) - ✓ Environment file system (inventory.env) --- ## Technical Approach ### Plan 1: Docker & Deployment Automation (Week 1-2) - Refine Dockerfiles (health checks, logging, layer optimization) - Create deployment automation script (`deploy.sh`) - Environment template with validation - Pre-flight checks + error handling - Docker Compose enhancements (healthchecks, volumes, networking) ### Plan 2: Scale Testing & Performance (Week 2-3) - Load testing framework (Locust) - Database seeding (10K items with realistic categories) - Concurrent user simulation (5 users, multiple workflows) - Metrics collection (response time, CPU, memory) - Bottleneck identification + optimization PR recommendations - Health check automation ### Plan 3: Backup/Restore & Runbook (Week 3-4) - Backup automation script (daily/weekly cycles) - Restore validation + testing - Runbook documentation (deployment, scaling, troubleshooting) - Disaster recovery procedures - Health monitoring guidelines --- ## Success Criteria ### Deployment Automation - [ ] `./deploy.sh` deploys full stack in <5 minutes - [ ] Automatic DB initialization on first run - [ ] Health checks confirm all services running - [ ] Env validation prevents misconfiguration - [ ] Works on clean Ubuntu 22.04+ LTS system ### Scale Testing - [ ] Load test with 10K items + 5 concurrent users completes - [ ] Response times stable: search <500ms, scan <1s, sync <2s - [ ] CPU usage <70%, memory <2GB during load - [ ] Sync reliability 99%+ (no dropped transactions) - [ ] Baseline metrics documented for future comparisons ### Backup/Restore - [ ] Backup script creates timestamped archives - [ ] Restore fully recovers system state (DB + config) - [ ] Zero data loss on restore test - [ ] RTO <10 minutes, RPO 1 day (configurable) ### Documentation - [ ] Deployment runbook (step-by-step, no domain knowledge required) - [ ] Scaling guide (adding more users, larger DB) - [ ] Troubleshooting guide (common issues + solutions) - [ ] Health monitoring checklist --- ## Testing Strategy ### Automated Testing - Pre-deployment validation (docker build, env checks) - Health check validation (all services respond) - Scale testing suite (Locust + Playwright) - Backup/restore automated tests ### Manual Testing - First-time deployment on fresh VM - Multi-site deployment (verify isolation) - Failover testing (service restart, data integrity) ### Success Metrics - All automated tests pass - Manual deployment completes without human intervention - Scale test shows <2s latency at 5 concurrent users - Backup/restore cycle succeeds with zero data loss --- ## Blockers & Workarounds ### Known Constraints 1. **SQLite single-writer limitation** — No true concurrent writes; acceptable for 5 users - Workaround: WAL mode enabled, connection pooling limits contention 2. **Certificate persistence** — Caddy certs need stable volume mount - Workaround: Use persistent named volumes for `/data/caddy_*` 3. **Environment variability** — Different orgs may have different network configs - Workaround: Pre-flight checks validate critical assumptions (ports, storage) ### Potential Issues - Docker daemon availability (some restricted environments) - HTTPS certificate warnings on first-time access - Network isolation (VPN/Tailscale may affect CORS detection) --- ## Execution Checklist - [ ] Phase 5 complete + all tests passing - [ ] Create Phase 6 directory structure - [ ] Write 3 PLAN.md files (Deployment, Scale Testing, Backup/Runbook) - [ ] Execute Plan 1: Docker + deploy.sh - [ ] Execute Plan 2: Load testing + performance baseline - [ ] Execute Plan 3: Backup/restore + runbook - [ ] Integration testing (full deployment cycle) - [ ] Documentation review - [ ] Commit all changes with `feat(6): phase 6 planning complete...` - [ ] Tag v2.0-rc1 for release candidate validation --- **Last Updated**: 2026-04-22 (Planning Phase)