headquarter/openspec/changes/deployment-config/design.md at 8b4784f5edfe99de6db5fec32729485f2b4b9ae0

alex/headquarter

Fork 0

Files

T

alex 78aaddb2b5

CI / Web CI (push) Failing after 12s

Details

CI / API CI (push) Failing after 1m1s

Details

docs(openspec): add OpenSpec changes for FN-005, FN-006, FN-008, FN-009, FN-010

- 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

2026-05-14 17:35:20 +02:00

2.6 KiB

Raw Blame History

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

Should we support custom domains per user/project in MVP?
Do we need basic auth or IP allow-listing for Traefik dashboard?
Should tool containers run on a separate Docker daemon for security?

2.6 KiB Raw Blame History