bede/tfm_ainventory
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
0e356e6c893e7ea3a68797d344a720428e06be5c
tfm_ainventory/.planning/phases/06-deployment-scale/CONTEXT.md
Daniel Bedeleanu be3555d7cd docs(phase-6): add dual-deployment requirement - docker and standalone modes 
- 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
2026-04-22 18:21:12 +03:00

7.5 KiB
Raw Blame History

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)

  • Phase 5 complete + all tests passing
  • 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)

Reference in New Issue View Git Blame Copy Permalink