headquarter/openspec/changes/archive/2026-05-14-deployment-config/design.md

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?