alex
78aaddb2b5
- Add frontend-foundation change (FN-005) with 46 tasks - Add deployment-config change (FN-006) with 27 tasks - Add runfusion-poc/opencode-poc change (FN-008) with 25 tasks - Add config-secrets change (FN-009) with 31 tasks - Add codeserver-spawn change (FN-010) with 38 tasks - Include project specsheet and configuration - Archive completed deployment-config change
68 lines
2.6 KiB
Markdown
68 lines
2.6 KiB
Markdown
## Context
|
|
|
|
The platform routes tool instances via Traefik using subdomain patterns like `https://{tool}-{project}-{user}.{tool_domain}`. Currently, there's no automated label generation or production deployment configuration. This design establishes the deployment architecture.
|
|
|
|
Current state:
|
|
- `docker-compose.yml` for local dev only
|
|
- `docker-compose.traefik.yml` exists but is minimal
|
|
- `deploy/` directory has skeleton files
|
|
- No automated Traefik label generation
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- Generate Traefik labels automatically when spawning tools
|
|
- Provide production-ready Docker Compose stack
|
|
- Support Portainer-managed deployment
|
|
- Enable HTTPS with automatic certificate management
|
|
|
|
**Non-Goals:**
|
|
- Kubernetes deployment (deferred post-MVP)
|
|
- Multi-region or high-availability setup
|
|
- Custom reverse proxy (Traefik is the only supported option)
|
|
- Automatic DNS management
|
|
|
|
## Decisions
|
|
|
|
**1. Label generation in backend, not in Docker Compose**
|
|
- Rationale: Backend has all metadata (user slug, project slug, tool ID). Generating labels at spawn time is more flexible than static Compose files.
|
|
- Implementation: `TraefikLabelGenerator` service class
|
|
|
|
**2. Subdomain pattern: `{tool}-{project}-{user}.{domain}`**
|
|
- Rationale: Unique, deterministic, human-readable
|
|
- Example: `code-server-myapp-alice.headquarter.example.com`
|
|
|
|
**3. Separate Docker networks: `platform` and `tools`**
|
|
- Rationale: Network isolation between platform services and user tools
|
|
- Platform network: API, web, Traefik, database
|
|
- Tools network: Traefik + tool containers only
|
|
|
|
**4. Portainer as the deployment target**
|
|
- Rationale: Docker Compose-native, web UI for operators, supports stacks and webhooks
|
|
- Alternative: Raw Docker Compose on VM - less operator-friendly
|
|
|
|
**5. Let's Encrypt for HTTPS in production**
|
|
- Rationale: Free, automatic, Traefik has built-in support
|
|
- Alternative: Custom certificates - adds operational burden
|
|
|
|
## Risks / Trade-offs
|
|
|
|
**[Risk] Traefik label complexity grows with features**
|
|
→ Mitigation: Keep label generation centralized in one service class. Test label output against Traefik schema.
|
|
|
|
**[Risk] Portainer stack updates require downtime**
|
|
→ Mitigation: Use rolling updates where possible. Document blue-green deployment strategy.
|
|
|
|
**[Risk] Subdomain collision**
|
|
→ Mitigation: Enforce unique project slugs per user. Include user slug in subdomain.
|
|
|
|
## Migration Plan
|
|
|
|
No migration - new deployment stack is additive.
|
|
|
|
## Open Questions
|
|
|
|
1. Should we support custom domains per user/project in MVP?
|
|
2. Do we need basic auth or IP allow-listing for Traefik dashboard?
|
|
3. Should tool containers run on a separate Docker daemon for security?
|