# 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:

```env
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.