Skip to content

DEPLOYMENT.md

Latest commit

 

History

History
206 lines (148 loc) · 7 KB

DEPLOYMENT.md

File metadata and controls

206 lines (148 loc) · 7 KB

Trinity Local Development Guide

This guide covers setting up Trinity for local development.

Deploying to a server? Use the trinity-ops-public ops agent — a Claude Code agent that manages any Trinity instance (health checks, updates, rollback, log triage, provisioning guides for Hetzner / GCP / AWS / DigitalOcean).

Prerequisites

  • Docker and Docker Compose v2+
  • 8 GB RAM minimum (recommended: 16 GB for multiple agents)

Quick Start

# 1. Clone the repository
git clone https://github.com/abilityai/trinity.git
cd trinity

# 2. Copy and configure environment
cp .env.example .env
# Edit .env with your settings (see Configuration section)

# 3. Build the base agent image
./scripts/deploy/build-base-image.sh

# 4. Start all services
./scripts/deploy/start.sh

# 5. Access the platform
# Web UI: http://localhost
# API Docs: http://localhost:8000/docs

Configuration

Required Environment Variables

Edit .env with these required settings:

# Security - REQUIRED (generate with: openssl rand -hex 32)
SECRET_KEY=your-secret-key-here

# Admin credentials for dev mode
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-secure-password

# Anthropic API Key - Required for Claude-powered agents
ANTHROPIC_API_KEY=sk-ant-your-api-key

Google API Key (Optional - for Gemini-powered agents)

To use Gemini CLI as an alternative runtime (free tier with 1M token context):

# Get from: https://makersuite.google.com/app/apikey
GOOGLE_API_KEY=your-google-api-key

See Gemini Support Guide for details on multi-runtime configuration.

GitHub Templates (Optional)

To use GitHub-based agent templates (private repositories), add your GitHub Personal Access Token:

# GitHub PAT for cloning private template repos
# Get from: https://github.com/settings/tokens (classic token with 'repo' scope)
GITHUB_PAT=github_pat_xxxxx

How it works:

  • On startup, the backend automatically uploads the PAT to Redis
  • GitHub templates in config.py reference this credential
  • When creating an agent from a GitHub template, the PAT is used to clone the repo

Note: The PAT is stored in Redis with a fixed credential ID (github-pat-templates). If you update the PAT in .env, restart the backend to sync it to Redis.

Authentication

Trinity supports two login methods:

Email Login (Primary)

Users enter email → receive 6-digit code → login. Configure email provider:

EMAIL_PROVIDER=console  # console (dev), smtp, sendgrid, resend

For local development, use console - codes are printed to backend logs.

Manage allowed emails in Settings → Email Whitelist.

Admin Login

Password-based login for admin user:

ADMIN_PASSWORD=your-secure-password

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Trinity Platform                        │
├─────────────────────────────────────────────────────────────┤
│  Frontend (Vue.js)  │  Backend (FastAPI)  │  MCP Server     │
│      Port 80        │     Port 8000       │    Port 8080    │
├─────────────────────────────────────────────────────────────┤
│  Redis (secrets)    │  SQLite (data)      │  Vector (logs)  │
│   Internal only     │   /data volume      │    Port 8686    │
├─────────────────────────────────────────────────────────────┤
│                    Agent Containers                          │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐                     │
│  │ Agent 1 │  │ Agent 2 │  │ Agent N │  ...                │
│  │ SSH:2222│  │ SSH:2223│  │ SSH:222N│                     │
│  └─────────┘  └─────────┘  └─────────┘                     │
└─────────────────────────────────────────────────────────────┘

Data Persistence

Data Location Backup Strategy
SQLite (users, agents) ~/trinity-data/trinity.db Regular file backup
Redis (credentials) Docker volume Redis RDB snapshots
Agent workspaces Docker volumes Per-agent backup

Backup Script

# Backup database
./scripts/deploy/backup-database.sh ./backups/

# Restore from backup
./scripts/deploy/restore-database.sh ./backups/trinity_backup.db

Troubleshooting

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f backend
docker compose logs -f frontend

# Agent container
docker logs agent-myagent

Common Issues

Agent creation fails

  • Check if trinity-agent-base image exists: docker images | grep trinity-agent-base
  • Rebuild: ./scripts/deploy/build-base-image.sh

Redis connection errors

  • Ensure Redis is running: docker compose ps redis
  • Check Redis logs: docker compose logs redis

Email login not working

  • Check backend logs: docker compose logs backend
  • Verify EMAIL_PROVIDER is set correctly
  • For local dev, use console (codes printed to logs)

OpenTelemetry Metrics (Optional)

Trinity agents can export metrics to an OpenTelemetry collector for external observability tools like Prometheus and Grafana. This leverages Claude Code's built-in OTel support.

What You Get

Metric Description
claude_code.cost.usage Cost per API call in USD
claude_code.token.usage Token consumption (input/output/cache)
claude_code.lines_of_code.count Code added/removed
claude_code.session.count Session lifecycle tracking
claude_code.active_time.total Active usage duration

Quick Start

  1. Enable OTel in your .env:

    OTEL_ENABLED=1
OTEL_COLLECTOR_ENDPOINT=http://trinity-otel-collector:4317

  2. Restart the backend:

    docker-compose restart backend

  3. Create new agents - They will automatically export metrics

See docs/drafts/OTEL_INTEGRATION.md for full collector configuration and Grafana dashboard setup.

Security Recommendations

  1. Never expose Redis externally - Keep it internal only
  2. Use strong SECRET_KEY - Generate with openssl rand -hex 32
  3. Use email whitelist - Restrict access to approved email addresses only
  4. Regular backups - Automate database backups
  5. Keep Docker updated - Regular security patches