alex
62640daf36
- 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
134 lines
3.3 KiB
Markdown
134 lines
3.3 KiB
Markdown
# Deployment Guide
|
|
|
|
## Overview
|
|
|
|
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.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
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
|
|
```
|
|
|
|
## 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
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `docker-compose.yml` | Local development (API, web, Postgres) |
|
|
| `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 |
|
|
|
|
## Traefik Configuration
|
|
|
|
Traefik handles all routing and TLS:
|
|
|
|
- **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}
|
|
```
|
|
|
|
Example: `vscode-myproject-john.tools.example.com`
|
|
|
|
## DNS Requirements
|
|
|
|
Create DNS A records for:
|
|
|
|
- `example.com` → your server IP
|
|
- `*.example.com` → your server IP (wildcard for subdomains)
|
|
- `*.tools.example.com` → your server IP (tool subdomains)
|
|
|
|
## Security
|
|
|
|
- All services communicate over HTTPS
|
|
- Traefik adds security headers (HSTS, XSS protection, etc.)
|
|
- Database is not exposed externally
|
|
- Secrets are injected via environment variables
|
|
|
|
## 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
|
|
```
|