docs: update all documentation for OpenCode and deployment
- Update architecture.md with spawn service and auth proxy sections - Update deployment.md with production stack details - Update development.md with spawn workflow documentation - Update mvp-scope.md, project-brief.md, tool-manifest-spec.md - Update conversation-handoff.md with current status - Replace all RunFusion references with OpenCode
This commit is contained in:
+109
-38
@@ -2,61 +2,132 @@
|
||||
|
||||
## Overview
|
||||
|
||||
The MVP deployment target is a **Portainer-managed Docker Compose stack** with an existing **Traefik** reverse proxy.
|
||||
The MVP deployment target is a **Portainer-managed Docker Compose stack** with **Traefik** as the reverse proxy. All services run in Docker containers with automatic TLS via Let's Encrypt.
|
||||
|
||||
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**.
|
||||
## Architecture
|
||||
|
||||
## Stack Assumptions
|
||||
```
|
||||
Internet
|
||||
|
|
||||
v
|
||||
Traefik (443/80) ──► Let's Encrypt TLS
|
||||
|
|
||||
├──► api.example.com ──► FastAPI backend
|
||||
├──► example.com ──► React frontend
|
||||
├──► traefik.example.com ──► Traefik dashboard
|
||||
└──► {tool}-{project}-{user}.tools.example.com ──► Spawned tool containers
|
||||
```
|
||||
|
||||
- **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)
|
||||
## Prerequisites
|
||||
|
||||
- Docker and Docker Compose
|
||||
- A domain with DNS A/AAAA records pointing to your server
|
||||
- Ports 80 and 443 open
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Configure Environment
|
||||
|
||||
Copy the production environment example and fill in all values:
|
||||
|
||||
```bash
|
||||
cp deploy/.env.example deploy/.env
|
||||
```
|
||||
|
||||
Required variables:
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `ROOT_DOMAIN` | Your domain | `example.com` |
|
||||
| `ACME_EMAIL` | Let's Encrypt contact email | `admin@example.com` |
|
||||
| `POSTGRES_PASSWORD` | Database password | (strong random) |
|
||||
| `AUTHENTIK_CLIENT_SECRET` | OIDC client secret | (from Authentik) |
|
||||
| `SECRET_ENCRYPTION_KEY` | Fernet encryption key | (32-byte base64) |
|
||||
|
||||
### 2. Deploy Locally (Testing)
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.prod.yml up --build -d
|
||||
```
|
||||
|
||||
This starts: Traefik, API, web frontend, and PostgreSQL.
|
||||
|
||||
### 3. Deploy to Production (Portainer)
|
||||
|
||||
1. In Portainer, create a new stack
|
||||
2. Upload `deploy/portainer-stack.yml`
|
||||
3. Set environment variables from `deploy/portainer.env.example`
|
||||
4. Deploy the stack
|
||||
|
||||
## 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 |
|
||||
| `docker-compose.prod.yml` | Production compose with Traefik |
|
||||
| `deploy/portainer-stack.yml` | Portainer stack definition |
|
||||
| `deploy/portainer.env.example` | Portainer environment variables |
|
||||
| `deploy/.env.example` | Production environment variables |
|
||||
|
||||
## Environment Variables
|
||||
## Traefik Configuration
|
||||
|
||||
See `.env.example` for the full variable list. Key deployment variables:
|
||||
Traefik handles all routing and TLS:
|
||||
|
||||
```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=
|
||||
- **Entrypoints**: `web` (80) → redirects to `websecure` (443)
|
||||
- **Certificates**: Let's Encrypt via TLS challenge
|
||||
- **Dashboard**: Available at `traefik.${ROOT_DOMAIN}` (protected by middleware)
|
||||
- **Metrics**: Prometheus metrics exposed on `/metrics`
|
||||
|
||||
### Subdomain Routing
|
||||
|
||||
Tool containers are routed via subdomains:
|
||||
|
||||
```
|
||||
{tool}-{project}-{user}.tools.{ROOT_DOMAIN}
|
||||
```
|
||||
|
||||
## Local vs Production
|
||||
Example: `vscode-myproject-john.tools.example.com`
|
||||
|
||||
- **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.
|
||||
## DNS Requirements
|
||||
|
||||
## Scoped Secrets
|
||||
Create DNS A records for:
|
||||
|
||||
Do not commit real secrets. Use:
|
||||
- `example.com` → your server IP
|
||||
- `*.example.com` → your server IP (wildcard for subdomains)
|
||||
- `*.tools.example.com` → your server IP (tool subdomains)
|
||||
|
||||
- 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)
|
||||
## Security
|
||||
|
||||
## Follow-up Work
|
||||
- All services communicate over HTTPS
|
||||
- Traefik adds security headers (HSTS, XSS protection, etc.)
|
||||
- Database is not exposed externally
|
||||
- Secrets are injected via environment variables
|
||||
|
||||
- **FN-006**: Full deployment automation, dynamic Traefik labels for spawned tool containers, Portainer stack definitions, and CI/CD integration.
|
||||
## Updating
|
||||
|
||||
To update the deployment:
|
||||
|
||||
```bash
|
||||
# Pull new images
|
||||
docker compose -f docker-compose.prod.yml pull
|
||||
|
||||
# Restart services
|
||||
docker compose -f docker-compose.prod.yml up -d
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Check Traefik logs:
|
||||
```bash
|
||||
docker logs traefik
|
||||
```
|
||||
|
||||
Check service health:
|
||||
```bash
|
||||
docker compose -f docker-compose.prod.yml ps
|
||||
```
|
||||
|
||||
Verify certificates:
|
||||
```bash
|
||||
curl -v https://api.example.com
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user