# 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)