Daniel Bedeleanu
be3555d7cd
- Both Docker and start_server.sh standalone modes required - Shared config files between both modes (no duplication) - Single config source of truth (inventory.env) - Both modes available for development and production use
195 lines
7.5 KiB
Markdown
195 lines
7.5 KiB
Markdown
# Phase 6: Docker Deployment — Context & Strategic Overview
|
|
|
|
**Phase Goal**: Production-ready single-instance Docker deployment with automated setup and operational runbooks.
|
|
|
|
**Duration**: 2-3 weeks (simplified scope)
|
|
|
|
**Target Version**: v2.0 stable
|
|
|
|
**CRITICAL DECISIONS** (LOCKED):
|
|
- Single-instance deployment (not multi-site)
|
|
- **TWO deployment modes**: Docker AND Standalone (start_server.sh)
|
|
- **Shared config files** between both modes
|
|
- No scale testing
|
|
|
|
---
|
|
|
|
## Phase Overview
|
|
|
|
Phase 6 delivers dual-mode deployment for v2.0. After Phase 5 delivers search, exports, and quick quantity adjustment, the system needs:
|
|
|
|
1. **Docker Deployment** — Reliable Docker/Compose setup for containerized deployments
|
|
2. **Standalone Deployment** — `./start_server.sh` script for direct server startup (development + deployment)
|
|
3. **Shared Configuration** — Both modes use the same config files (no duplication)
|
|
4. **Automation** — Single-command setup for both modes
|
|
5. **Operational readiness** — Health checks, monitoring, runbook documentation
|
|
6. **Documentation** — Clear deployment guides for both modes
|
|
|
|
**OUT OF SCOPE**: Scale testing, multi-site federation, performance optimization, multi-instance clustering
|
|
|
|
---
|
|
|
|
## Key Decisions Made During Planning
|
|
|
|
### 1. Dual-Mode Deployment Strategy (LOCKED)
|
|
|
|
**Mode 1: Docker Deployment**
|
|
- **Existing**: docker-compose.yml and Dockerfiles already in place (backend/, proxy/)
|
|
- **Gap**: Automated deployment scripts, environment templates, health checks
|
|
- **Focus**: Enhance existing Dockerfiles → production-grade, add health checks, optimize layers
|
|
- **Target**: `./deploy.sh` orchestrates Docker Compose
|
|
|
|
**Mode 2: Standalone Deployment**
|
|
- **New**: `./start_server.sh` script for direct server startup (no Docker required)
|
|
- **Scope**: Backend FastAPI + Frontend Next.js servers managed by script
|
|
- **Target**: Development, testing, and deployment without Docker
|
|
- **Config**: Uses same config files as Docker mode (shared inventory.env)
|
|
|
|
**Shared Configuration**
|
|
- Both modes read from same `inventory.env` and config files
|
|
- No environment-specific duplication
|
|
- Single config source of truth
|
|
|
|
### 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 (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. 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 (LOCKED)
|
|
- **Audience**: Ops teams deploying single-instance setups; minimal Docker/Python knowledge required
|
|
- **Format**: Runbook style (step-by-step checklists)
|
|
- **Coverage**: Deployment, monitoring, troubleshooting, upgrade path
|
|
- **OUT OF SCOPE**: Multi-site federation, scaling across instances
|
|
|
|
---
|
|
|
|
## 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 (SIMPLIFIED)
|
|
|
|
### Plan 1: Docker & Deployment Automation (Week 1)
|
|
- Refine Dockerfiles (health checks, logging, layer optimization)
|
|
- 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: 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
|
|
|
|
**Scale Testing Moved to v3 Backlog** — Focus on single-instance reliability instead.
|
|
|
|
---
|
|
|
|
## 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 (local Docker)
|
|
|
|
### Operational Documentation
|
|
- [ ] Deployment runbook (step-by-step, fresh VM scenario)
|
|
- [ ] Health monitoring checklist (startup, daily, weekly)
|
|
- [ ] Troubleshooting guide (common issues + solutions)
|
|
- [ ] 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
|
|
|
|
---
|
|
|
|
## 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. **Certificate persistence** — Caddy certs need stable volume mount
|
|
- Workaround: Use persistent named volumes for `/data/caddy_*`
|
|
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)
|
|
- HTTPS certificate warnings on first-time access
|
|
- Network isolation (VPN/Tailscale may affect CORS detection)
|
|
|
|
---
|
|
|
|
## Execution Checklist (UPDATED FOR SINGLE-INSTANCE SCOPE)
|
|
|
|
- [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 deployment automation (single-instance)`
|
|
- [ ] Tag v2.0-rc1 for release candidate validation
|
|
|
|
---
|
|
|
|
**Last Updated**: 2026-04-22 (Planning Phase)
|