feat(FN-002): complete Step 4 — Documentation Structure and Environment Examples

2026-05-14 01:40:58 +02:00
parent 9eaf4cfa36
commit 1f1c95cdde
10 changed files with 478 additions and 34 deletions
@@ -0,0 +1,60 @@
+# 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:
+
+```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.