Deployment Overview

Operator-owned deployment

Self-hosting gives you the full FrameWorks control plane and media plane on your own infrastructure. Treat it like operating a SaaS platform: validate capacity, DNS, TLS, backups, secrets, monitoring, and upgrade runbooks before carrying production traffic.

Deploying FrameWorks gives you full ownership of your video infrastructure.

Quick Start

Production Deployment (Recommended):

# 1. Install CLI
curl -sSfL https://github.com/Livepeer-FrameWorks/monorepo/releases/latest/download/install.sh | sh

# 2. Review prerequisites
# See: /operators/prerequisites

# 3. Create cluster manifest + secrets file
# See: /operators/cluster-manifest
# Copy config/env/secrets.env.example → gitops/secrets/production.env

# 4. Detect hosts (verify SSH connectivity)
frameworks cluster detect --manifest cluster.yaml

# 5. Provision + init + static seeds (one command, usable platform)
frameworks cluster provision --manifest cluster.yaml \
  --bootstrap-admin-email you@co --bootstrap-admin-password-env DEPLOY_PW

# 6. Verify health — subsequent commands pick up the saved manifest path
#    from the active context, so no need to re-pass --manifest.
frameworks cluster doctor

Context-fed defaults

After a successful cluster provision, the CLI remembers the manifest path and the system tenant ID in the active context. Follow-up commands like cluster doctor, cluster status, and admin users create use those automatically and announce when they do:

Using manifest from context: /etc/frameworks/cluster.yaml
Using tenant from context: 7c2d…

Explicit flags always win. Set FRAMEWORKS_NO_HINTS=1 or CI=1 to suppress next-step blocks in pipelines.

GitOps Deployment (from a GitHub repo):

If your manifests are in a gitops repo managed by a GitHub App:

# Configure GitHub App credentials (once)
frameworks config set github.app-id 12345
frameworks config set github.installation-id 67890
frameworks config set github.private-key /path/to/key.pem
frameworks config set github.repo org/gitops

# Provision from the repo (fetches cluster.yaml, hosts, .env, etc.)
frameworks cluster provision --github-repo org/gitops --cluster production

# If secrets are SOPS-encrypted (recommended), specify an age key:
frameworks cluster provision --github-repo org/gitops --cluster production --age-key ~/.config/sops/age/keys.txt

This fetches the cluster manifest and referenced files (env files, host inventory) from the repo, then runs the standard provision pipeline. SOPS-encrypted files — both env files and host inventory YAML — are decrypted automatically if an age key is available (see External Services). Operators manage config changes via pull requests.

Provisioning Phases

The CLI provisions in dependency order:

1. Infrastructure — Postgres, Kafka, ClickHouse (parallel)
2. Quartermaster — Control plane bootstrap (tenant, clusters, nodes, tokens)
3. Privateer — Mesh agent on ALL hosts → mesh health verification
4. Application services — All other services (parallel)
5. Ingress & interfaces — Nginx, Chartroom, Foredeck, Logbook (parallel)

Use --only infrastructure|applications|interfaces to run a single phase.

For application/all phases, cluster provision runs cluster init, static reference seeds (cluster seed), service-owned bootstrap reconciliation, and edge release target sync as part of the provision run. For PostgreSQL/YugabyteDB, cluster init applies baseline schemas first and then embedded expand migrations from the database/version/phase migration layout. Demo tenant/user/ stream data is intentionally not part of provisioning; use frameworks cluster seed --demo only for local development/test stacks.

Local Development:

# Quick local stack with Docker Compose
cd monorepo
cp config/env/secrets.env.example config/env/secrets.env  # First time only
make env                  # Generate .env from layered config
docker-compose up -d

See root README.md for local endpoints and ports.

Tip

For multi-cluster deployments (separate control and media planes, multiple regions), define a clusters section in your manifest. The CLI creates all clusters, registers nodes under the correct cluster, and injects CLUSTER_ID into each service. See the Cluster Manifest Reference for details.

Deployment Paths

1. CLI Deployment (Recommended)

The FrameWorks CLI automates the complex orchestration of multi-tier infrastructure, handling everything from SSH keys to database migrations (via internal provisioners; Ansible is used for some infrastructure components).

Features:

• Multi-host SSH deployment
• Docker and native (systemd) support
• GitOps version management
• Automated health validation
• Backup/restore operations
• Comprehensive diagnostics

CLI Reference Grouped operator CLI overview.

Cluster Manifest Configure your deployment.

Prerequisites System requirements and setup.

External Services Third-party integrations.

2. Manual Deployment Reference

For operators who need to understand or debug what the CLI configures:

• Manual Deployment - Advanced deployment explainer and break-glass reference
• Operations Reference - Post-deployment operations, debugging, tuning
• Listmonk Setup - Newsletter backend post-provision configuration
• Chatwoot Setup - Support inbox and Deckhand integration setup
• Mesh Networking

Architecture

For detailed architecture documentation including service tables, ports, deployment tiers, and data flow diagrams, see Architecture Overview.

Security

Network Security

• Backend nodes (central/regional) communicate over a private mesh (WireGuard or equivalent). Edge nodes do not join the mesh.
• When running more than one backend node, a private mesh is required for databases, Kafka, and service-to-service calls.
• TLS termination varies by tier:
  • Development: Nginx reverse proxy (optional TLS)
  • Edge nodes: Caddy (automatic HTTPS via HTTP-01)
  • Central/Regional: Navigator-issued certificates (DNS-01) or operator-managed proxies
• Firewall rules restrict access to required ports

Data Security

• TLS at ingress (Caddy/Navigator/proxies) should be enabled; internal gRPC TLS is not enabled yet (RFC draft exists).
• Kafka inter-broker encryption is not enabled yet; the mesh provides the current security boundary.
• Service-to-service authentication uses SERVICE_TOKEN (RFC draft exists for stronger service identity).
• Secrets are currently managed via flat env files pushed during provisioning. This is an interim solution — a HashiCorp Vault integration is planned (RFC draft exists) to replace plaintext env files with dynamic secret injection.

Access Control

• Multi-tenant isolation at application layer
• User roles exist, but API tokens are currently full-access; RBAC and finer permissions are planned.
• The Gateway has tenant-aware rate-limit middleware. Free-tier product limits are enforced at Foghorn admission with a three-tier cluster-load policy: under 50% load all free traffic admitted; 50–95% load rejects new ingest from over-allowance free streams; at the 95% redline all new free ingest is rejected. Viewer admission follows the same shape with a higher first threshold (80% / 95%). Free tenants are also capped at 3 concurrent live streams and 200 concurrent viewers. Active sessions are never killed mid-stream. Recordings, VOD uploads, and clip exports are rejected at the per-tenant 10 GB storage cap.
• SSH key-based authentication for deployments

For monitoring, operations, and CLI commands, see CLI Reference and Operations.