headquarter/docs/deployment.md

Deployment Guide

Overview

The MVP deployment target is a Portainer-managed Docker Compose stack with an existing Traefik reverse proxy.

This document covers the scaffold-level deployment assumptions created in FN-002. Detailed deployment automation (dynamic labels for spawned tool containers, secret rotation, CI/CD pipelines) is follow-up scope for FN-006.

Stack Assumptions

• Reverse proxy: Traefik (already running on the target host)
• Orchestration: Portainer managing Docker Compose stacks
• Network: External Traefik network named traefik (or as configured)
• Routing: Subdomain-based ({tool}-{project}-{user}.tools.{ROOT_DOMAIN})
• TLS: Traefik cert resolver (e.g., letsencrypt or Cloudflare)

Deployment Files

The following files will be added as part of the Docker Compose skeleton (Step 5):

File	Purpose
docker-compose.yml	Local development (API, web, Postgres)
docker-compose.traefik.yml	Deployment overlay with Traefik labels
deploy/portainer.env.example	Deployment environment variables
deploy/traefik-labels.example.yml	Example Traefik labels for services
deploy/README.md	Deploy skeleton usage notes

Environment Variables

See .env.example for the full variable list. Key deployment variables:

APP_NAME=Headquarter
ROOT_DOMAIN=example.com
TOOL_DOMAIN=tools.example.com
TRAEFIK_NETWORK=traefik
TRAEFIK_ENTRYPOINT=websecure
TRAEFIK_CERT_RESOLVER=letsencrypt
AUTHENTIK_ISSUER_URL=https://auth.example.com/application/o/headquarter/
AUTHENTIK_CLIENT_ID=
AUTHENTIK_CLIENT_SECRET=
POSTGRES_PASSWORD=
SECRET_ENCRYPTION_KEY=

Local vs Production

• Local: docker compose up --build -d uses docker-compose.yml only.
• Production: Portainer deploys the stack using the main compose file plus the Traefik overlay.

Scoped Secrets

Do not commit real secrets. Use:

• Portainer environment variables (stored in Portainer, not in Git)
• .env files (ignored by Git, documented in .env.example)
• Docker secrets (to be evaluated in FN-006)

Follow-up Work

• FN-006: Full deployment automation, dynamic Traefik labels for spawned tool containers, Portainer stack definitions, and CI/CD integration.