Fusion
63 lines
2.2 KiB
Markdown
63 lines
2.2 KiB
Markdown
# 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 deployment files are part of the scaffold:
|
|
|
|
| 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.
|