Skip to content
FrameWorks Docs
Blog

Prerequisites

Check these hardware, network, and access requirements before running the CLI.

Hardware & OS Requirements

Section titled “Hardware & OS Requirements”

Minimum Development Requirements

Section titled “Minimum Development Requirements”

For testing or small-scale deployments, you can run a consolidated stack on a single node:

  • Single Node: 4+ cores, 16GB RAM, 100GB SSD.
  • Note: Performance will be limited for high-concurrency streaming or heavy analytics loads.
Section titled “Hardware (recommended)”

Central Tier:

  • CPU: 8+ cores
  • RAM: 32GB+ (64GB recommended if running database services on the same node)
  • Disk: 500GB+ SSD
  • Network: 1Gbps+ connectivity

Regional Tier:

  • CPU: 4+ cores
  • RAM: 16GB+
  • Disk: 250GB+ SSD
  • Network: 1Gbps+ connectivity

Edge Tier:

  • CPU: 8+ cores
  • RAM: 16GB+
  • Disk: 1TB+ SSD (for recordings)
  • Network: 10Gbps+ connectivity (for high-bandwidth streaming)

Required Software

Section titled “Required Software”

Docker Deployment:

  • Docker Engine (24.0+) and Docker Compose (2.20+) for containerized service deployment.

Native Deployment (Linux):

  • systemd for service management.
  • PostgreSQL client tools (or Postgres-compatible).
  • Basic build tools (GCC, Make, Git) for native compilation.

Native Deployment (macOS):

  • macOS 14.0+ (Sonoma or later), Apple Silicon (arm64) only.
  • launchd for service management (built into macOS).
  • Homebrew for dependency management.

Both:

  • SSH server with key-based authentication.
  • curl, wget, tar, gzip.
  • netstat, ss, or lsof for network diagnostics.

Install the CLI

Section titled “Install the CLI”

Script (Linux & macOS):

Terminal window
curl -sSfL https://github.com/Livepeer-FrameWorks/monorepo/releases/latest/download/install.sh | sh

This installs the frameworks binary to /usr/local/bin. Override the install directory with FRAMEWORKS_INSTALL_DIR or the version with FRAMEWORKS_VERSION.

Homebrew (macOS):

Terminal window
brew tap livepeer-frameworks/tap
brew install frameworks-cli

Network Prerequisites

Section titled “Network Prerequisites”

For multi-host deployments, you need:

  1. WireGuard Mesh Network - Secure communication between backend infrastructure nodes (central/regional/database). See Mesh Networking for the GitOps identity and Privateer bootstrap flow.

  2. systemd-resolved - Production backend hosts must run systemd-resolved so Privateer can route .internal names to the local DNS listener.

  3. Firewall Rules - Open the manifest’s WireGuard listen port between backend nodes and keep internal service ports private to the mesh.

  4. No DHCP search domains - FrameWorks resolves only fully qualified names. A search domain from DHCP or a router advertisement makes the resolver retry a name under that suffix when the upstream drops a query, and a wildcard record there returns a wrong address. Provisioning sets UseDomains=no for DHCPv4, DHCPv6 and router advertisements on every systemd-networkd link (netplan included) on platform hosts and Linux edges; on hosts under another network manager, turn off DHCP-provided search domains yourself.

SSH Access

Section titled “SSH Access”

SSH Key Setup

Section titled “SSH Key Setup”

Generate SSH keys for CLI access:

Terminal window
# Generate ED25519 key (recommended)
ssh-keygen -t ed25519 -C "frameworks-cli" -f ~/.ssh/frameworks_ed25519


# Or RSA key (4096-bit)
ssh-keygen -t rsa -b 4096 -C "frameworks-cli" -f ~/.ssh/frameworks_rsa

Copy public keys to all hosts:

Terminal window
ssh-copy-id -i ~/.ssh/frameworks_ed25519.pub admin@central-01
ssh-copy-id -i ~/.ssh/frameworks_ed25519.pub admin@central-02
# ... repeat for all hosts

Key-Only SSH

Section titled “Key-Only SSH”

The node baseline that cluster provision and cluster release apply converge on every host restricts sshd to key authentication:

  • PasswordAuthentication no and KbdInteractiveAuthentication no
  • PermitRootLogin prohibit-password (root may still log in with a key)
  • MaxStartups 10:30:60 and LoginGraceTime 20
  • a fail2ban sshd jail: 5 failed logins within 10 minutes ban the source for 1 hour

These settings live in /etc/ssh/sshd_config.d/00-frameworks.conf, which sorts ahead of distribution and cloud-init drop-ins. Before the first run, make sure every person and tool that logs in to the hosts has a key installed; password logins stop working when the baseline converges. Each rendered file is checked with sshd -t before sshd reloads, and a configuration sshd rejects is rolled back without reloading.

SSH Configuration

Section titled “SSH Configuration”

Configure ~/.ssh/config for convenient access:

# Central Tier
Host central-01
    HostName 10.18.0.10
    User admin
    IdentityFile ~/.ssh/frameworks_ed25519


Host central-02
    HostName 10.18.0.11
    User admin
    IdentityFile ~/.ssh/frameworks_ed25519


# Regional Tier
Host regional-eu-01
    HostName 10.18.1.10
    User admin
    IdentityFile ~/.ssh/frameworks_ed25519


Host regional-us-01
    HostName 10.18.1.11
    User admin
    IdentityFile ~/.ssh/frameworks_ed25519


# Edge Nodes
Host edge-eu-01
    HostName <edge-public-ip>
    User admin
    IdentityFile ~/.ssh/frameworks_ed25519

User Permissions

Section titled “User Permissions”

The CLI user needs non-interactive sudo privileges for the complete set of Ansible and direct-SSH operations used by the selected manifest, including:

  • Installing packages
  • Managing systemd services
  • Configuring network settings
  • Managing Docker (or be in docker group)
Terminal window
# Add user to docker group (Docker deployments)
sudo usermod -aG docker admin


# Verify that automation does not pause for a password prompt
sudo -n true

Grant this to a dedicated automation account reached only through your management VPN and SSH keys. A policy limited to only systemctl and docker is insufficient: provisioning also manages packages, users, files under /etc and /var/lib, network state, databases, and commands run as service accounts. If you maintain a command allowlist instead of NOPASSWD: ALL, derive and test it against the exact pinned playbooks in ansible/playbooks/ and the selected roles; update it whenever those tasks change. The CLI has no interactive become-password flow.

External Services

Section titled “External Services”

FrameWorks requires several external services. See External Services for detailed setup guides.

Required:

  • Cloudflare (required for Navigator-managed root/API/web/admin DNS)
  • Bunny DNS (optional; when configured, Navigator delegates media cluster DNS to Bunny)
  • S3-compatible object storage (Cloudflare R2, Hetzner, or another compatible provider)
  • SSL/TLS certificates (ACME/Let’s Encrypt managed via Navigator/Caddy, or bring your own)
  • SMTP provider (production; used for contact forms, auth emails, billing notifications, and support/newsletter email)

Optional:

  • Stripe (billing)
  • MaxMind GeoIP (geographic routing)

Next Steps

Section titled “Next Steps”

Once prerequisites are complete:

  1. Create Cluster Manifest: See Cluster Manifest Reference
  2. Generate Mesh Identity: frameworks mesh wg generate --manifest <manifest> --hosts-file <hosts.enc.yaml>
  3. Check Mesh Identity: frameworks mesh wg check --manifest <manifest>
  4. Run Host Preflight: frameworks cluster preflight --manifest <manifest>
  5. Provision + Initialize: frameworks cluster provision --manifest <manifest>
  6. Verify Health: frameworks cluster doctor --manifest <manifest>

See CLI Reference for the grouped operator command overview.