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

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.

2.1 KiB Raw Blame History