# ADR-007: Container & Orchestration Strategy

## STATUS
PROPOSED (2026-02-13)

## CONTEXT
Everything runs in Docker (per project requirements). Need container strategy for: platform services (Conductor, LiteLLM, dashboard), compute node agents, development environment. Must scale from single-node dev to multi-node production.

## OPTIONS EVALUATED

### Option A: Docker Compose (Small) + K3s (Scale)
- **Pros**: Docker Compose is simple for dev and small deployments, K3s is lightweight Kubernetes for production scaling, graduated path from simple to complex
- **Cons**: Two systems to maintain, K3s still has Kubernetes complexity

### Option B: Docker Compose Only
- **Pros**: Simplest possible deployment, everyone knows Docker Compose
- **Cons**: Limited scaling, no service discovery, no rolling updates natively
- **Best For**: Development and single-node deployments

### Option C: Full Kubernetes
- **Pros**: Maximum scaling, full ecosystem
- **Cons**: Extreme complexity for home/small deployments, heavy resource footprint
- **Best For**: Enterprise-only deployment

### Option D: Docker Swarm
- **Pros**: Built-in Docker orchestration, simpler than Kubernetes
- **Cons**: Effectively deprecated, limited community, Docker Inc. focusing on other products
- **Best For**: Legacy deployments

## DECISION
**Docker Compose** for all deployments, with **K3s** as optional upgrade path for scale.

### Deployment Tiers
```
Tier 1: Single Node (Docker Compose)
  - All platform services in one docker-compose.yml
  - Compute node agent as additional container
  - Redis for state
  - Suitable for 1-5 users

Tier 2: Multi-Node (Docker Compose + Node Agents)
  - Platform services on primary node
  - Compute node agents on additional devices (each running Docker)
  - Connected via Headscale/WireGuard mesh (Phase 3 Hive only); Tailscale/Cloudflare for personal remote access (Phase 2)
  - Suitable for 5-50 users

Tier 3: Production (K3s)
  - K3s cluster for platform services
  - Horizontal scaling of Conductor, LiteLLM, dashboard
  - GPU operator for compute node management
  - Suitable for 50+ users
```

## RATIONALE
- Docker Compose is the simplest possible deployment model (per project requirements: everything in Docker)
- Most LLMHosts users will be individuals/small teams (Tier 1-2 sufficient)
- K3s provides Kubernetes compatibility when scaling is needed, without full Kubernetes overhead
- Graduated approach means we don't over-engineer early

## CONSEQUENCES
- All services must have Dockerfiles
- docker-compose.yml must be well-designed for easy configuration
- K3s Helm charts needed for Tier 3 (later phase)
- Node agent must work both as standalone Docker container and as K3s workload
- Testing needed across all three deployment tiers
