Files

T

alex 62640daf36 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

2026-05-14 17:30:03 +02:00

3.3 KiB

Raw Blame History

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:

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)

docker compose -f docker-compose.prod.yml up --build -d

This starts: Traefik, API, web frontend, and PostgreSQL.

3. Deploy to Production (Portainer)

In Portainer, create a new stack
Upload deploy/portainer-stack.yml
Set environment variables from deploy/portainer.env.example
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:

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

docker logs traefik

Check service health:

docker compose -f docker-compose.prod.yml ps

Verify certificates:

curl -v https://api.example.com

3.3 KiB Raw Blame History