docs(phase-6): revise context - single-instance deployment, Docker only, no scale testing
- Lock decision: Single-instance Docker deployment (not multi-site) - Remove scale testing from Phase 6 scope (defer to v3) - Simplify to 2 plans: Docker deployment + operational runbook - Update success criteria to focus on reliability, not performance testing
This commit is contained in:
@@ -1,55 +1,58 @@
|
||||
# Phase 6: Deployment & Scale — Context & Strategic Overview
|
||||
# Phase 6: Docker Deployment — Context & Strategic Overview
|
||||
|
||||
**Phase Goal**: Production-ready multi-site deployment with automated setup, scale testing, and operational runbooks.
|
||||
**Phase Goal**: Production-ready single-instance Docker deployment with automated setup and operational runbooks.
|
||||
|
||||
**Duration**: 1 month
|
||||
**Duration**: 2-3 weeks (simplified scope)
|
||||
|
||||
**Target Version**: v2.0 stable
|
||||
|
||||
**CRITICAL DECISION**: Single-instance deployment (not multi-site). Docker containerization only. No scale testing.
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
Phase 6 delivers containerized deployment for v2.0. 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
|
||||
1. **Containerization** — Reliable Docker/Compose setup for reliable deployment
|
||||
2. **Automation** — Single-command deployment (`./deploy.sh`)
|
||||
3. **Operational readiness** — Health checks, monitoring, runbook documentation
|
||||
4. **Documentation** — Clear deployment and troubleshooting guides for operators
|
||||
|
||||
**OUT OF SCOPE**: Scale testing, multi-site federation, performance optimization, multi-instance clustering
|
||||
|
||||
---
|
||||
|
||||
## Key Decisions Made During Planning
|
||||
|
||||
### 1. Docker Strategy
|
||||
### 1. Docker Strategy (LOCKED)
|
||||
- **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
|
||||
- **Gap**: Automated deployment scripts, environment templates, health checks
|
||||
- **Focus**: Enhance existing Dockerfiles → production-grade, add health checks, optimize layers
|
||||
- **Deployment Target**: Single-instance Docker Compose (local development + production)
|
||||
|
||||
### 2. Deployment Automation
|
||||
### 2. Deployment Automation (LOCKED)
|
||||
- **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
|
||||
### 3. Scale Testing (DEFERRED - NOT IN PHASE 6)
|
||||
- **Decision**: Application is single-instance. Scale testing (10K items + 5 concurrent users) deferred to v3.
|
||||
- **Rationale**: Phase 5 delivered core features. Phase 6 focuses on reliable deployment, not load testing.
|
||||
- **Future**: If multi-instance or multi-site deployment needed later, add scale testing then.
|
||||
|
||||
### 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
|
||||
### 4. Operational Readiness (LOCKED)
|
||||
- **Health Checks**: Docker healthchecks on all services
|
||||
- **Monitoring**: Prometheus-style metrics endpoint (optional, documented)
|
||||
- **Logging**: Centralized logs via Docker (stdout/stderr)
|
||||
- **Documentation**: Runbook for deployment, troubleshooting, health monitoring
|
||||
|
||||
### 5. Operational Documentation
|
||||
- **Audience**: Ops teams deploying to new sites; minimal Docker/Python knowledge required
|
||||
### 5. Operational Documentation (LOCKED)
|
||||
- **Audience**: Ops teams deploying single-instance setups; minimal Docker/Python knowledge required
|
||||
- **Format**: Runbook style (step-by-step checklists)
|
||||
- **Coverage**: Deployment, scaling, troubleshooting, health monitoring, upgrade path
|
||||
- **Coverage**: Deployment, monitoring, troubleshooting, upgrade path
|
||||
- **OUT OF SCOPE**: Multi-site federation, scaling across instances
|
||||
|
||||
---
|
||||
|
||||
@@ -71,59 +74,49 @@ Phase 6 bridges the gap between fully-featured code (Phases 4.1 + 5) and product
|
||||
|
||||
---
|
||||
|
||||
## Technical Approach
|
||||
## Technical Approach (SIMPLIFIED)
|
||||
|
||||
### Plan 1: Docker & Deployment Automation (Week 1-2)
|
||||
### Plan 1: Docker & Deployment Automation (Week 1)
|
||||
- Refine Dockerfiles (health checks, logging, layer optimization)
|
||||
- Create deployment automation script (`deploy.sh`)
|
||||
- Environment template with validation
|
||||
- Create deployment automation script (`./deploy.sh`)
|
||||
- Environment template with validation (single-instance config)
|
||||
- Pre-flight checks + error handling
|
||||
- Docker Compose enhancements (healthchecks, volumes, networking)
|
||||
- Health check integration tests
|
||||
|
||||
### 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 2: Operational Runbook & Documentation (Week 2-3)
|
||||
- Deployment runbook (step-by-step, fresh VM scenario)
|
||||
- Health monitoring checklist (startup, daily, weekly checks)
|
||||
- Troubleshooting guide (common issues + solutions)
|
||||
- Upgrade procedure documentation
|
||||
- Emergency procedures (container restart, data recovery)
|
||||
- Optional: Prometheus metrics endpoint documentation
|
||||
|
||||
### 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
|
||||
**Scale Testing Moved to v3 Backlog** — Focus on single-instance reliability instead.
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
## Success Criteria (SIMPLIFIED FOR SINGLE-INSTANCE)
|
||||
|
||||
### 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
|
||||
- [ ] Works on clean Ubuntu 22.04+ LTS system (local Docker)
|
||||
|
||||
### 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)
|
||||
### Operational Documentation
|
||||
- [ ] Deployment runbook (step-by-step, fresh VM scenario)
|
||||
- [ ] Health monitoring checklist (startup, daily, weekly)
|
||||
- [ ] Troubleshooting guide (common issues + solutions)
|
||||
- [ ] Health monitoring checklist
|
||||
- [ ] Upgrade procedure documented
|
||||
- [ ] Emergency procedures clear (restart, recovery)
|
||||
|
||||
### Quality Gates
|
||||
- [ ] All Docker builds succeed with no warnings
|
||||
- [ ] Health checks pass on fresh deployment
|
||||
- [ ] All services accessible after deployment
|
||||
- [ ] Documentation is accurate and complete
|
||||
|
||||
---
|
||||
|
||||
@@ -151,12 +144,12 @@ Phase 6 bridges the gap between fully-featured code (Phases 4.1 + 5) and product
|
||||
## 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
|
||||
1. **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
|
||||
2. **Environment variability** — Different deployments may have different network configs
|
||||
- Workaround: Pre-flight checks validate critical assumptions (ports, storage)
|
||||
3. **Single-instance limitation** — Application designed for single-instance; no clustering
|
||||
- Accepted constraint for v2 scope
|
||||
|
||||
### Potential Issues
|
||||
- Docker daemon availability (some restricted environments)
|
||||
@@ -165,17 +158,16 @@ Phase 6 bridges the gap between fully-featured code (Phases 4.1 + 5) and product
|
||||
|
||||
---
|
||||
|
||||
## Execution Checklist
|
||||
## Execution Checklist (UPDATED FOR SINGLE-INSTANCE SCOPE)
|
||||
|
||||
- [ ] 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)
|
||||
- [x] Phase 5 complete + all tests passing
|
||||
- [x] Create Phase 6 directory structure
|
||||
- [ ] Update PLAN.md files to match simplified scope (Docker + runbook only)
|
||||
- [ ] Execute Plan 1: Docker + deploy.sh automation
|
||||
- [ ] Execute Plan 2: Operational runbook & documentation
|
||||
- [ ] Integration testing (fresh deployment + health checks)
|
||||
- [ ] Documentation review
|
||||
- [ ] Commit all changes with `feat(6): phase 6 planning complete...`
|
||||
- [ ] Commit all changes with `feat(6): phase 6 deployment automation (single-instance)`
|
||||
- [ ] Tag v2.0-rc1 for release candidate validation
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user