Run a Gateway: Quickstart Guide

Docker Quickstart Guide

Docker Supported Hosts Details

Docker OS Support for Livepeer Gateway

Docker supports running Livepeer Gateway nodes on Linux, macOS, and Windows with different architecture support and feature limitations.

Supported Platforms

OS	Architectures	GPU Compute Support	Notes
Linux	amd64, arm64	NVIDIA (GPU workloads only)	Full feature support
macOS	amd64, arm64	No	CPU-only transcoding
Windows	amd64	No	CPU-only transcoding

NVIDIA drivers are not a baseline requirement for a Gateway. They are only required when the same host is also running GPU workloads such as an Orchestrator or AI worker.

Implementation Details

Docker Build Configuration

The Dockerfile uses a multi-stage build with CUDA base images for GPU support. The build process supports cross-compilation for multiple architectures.

Build Matrix

The CI/CD pipeline builds for:

Linux amd64/arm64 (CPU and GPU variants)
macOS amd64/arm64 (CPU only)
Windows amd64 (CPU only)

Cross-Compilation Support

The Makefile includes cross-compilation configuration for different platforms:

Darwin (macOS) with Intel and Apple Silicon
Linux with x86_64 and ARM64
Windows x86_64

GPU Limitations

GPU transcoding is Linux only . The Docker images include NVIDIA CUDA support but this only works on Linux hosts.

Notes

ARM64 Docker images are built but note that ARM64 support is still experimental
For production use, Linux is recommended for full feature support
macOS and Windows support is primarily for development and testing
The box development environment supports both Linux and macOS:

Box Example Gateway

This guide will install and configure a Gateway to run video & AI workloads.

Docker is the recommended install method for most users.

Choose your Gateway Mode:

Off-Chain Gateway
On-Chain Gateway

Install Gateway Software

Pull the Docker image from Livepeer Docker Hub

Configure Gateway

VideoAICreate the docker-compose.yml file that defines the dual Gateway service.

fix me

See flag details below:

See Example transcoding options json below:

Transcoding Options Example

Run Gateway

Test Gateway

Fix me (onchain nicer)

Video
AI

Send a video stream to the Gateway:From a host terminal (not in Docker or Volume), run this command:After streaming, check the HLS playback output:Tips:

Replace localhost with your Gateway’s IP if running remotely
The stream name (test) becomes part of the HLS playback URL

Monitor Gateway

Needs Review

The -monitor=true flag in the docker-compose.yml already has basic monitoring enabled which exposes metrics in Prometheus format at http://localhost:8935/metrics.Metrics collected include:

Stream metrics (created, started, ended)
Transcoding metrics (success rate, latency)
Payment metrics (tickets sent, deposits)
AI-specific metrics (attempts, Orchestrators available)

See More Metrics Options Below:

Prometheus Metrics

Access Prometheus metrics at:

curl http://localhost:8935/metrics

Key metrics include:

livepeer_stream_created_total - Total streams created
livepeer_current_sessions_total - Active transcoding sessions
livepeer_success_rate - Transcoding success rate
livepeer_ai_live_attempts - AI processing attempts
livepeer_gateway_deposit - Current ETH deposit

CLI Monitoring Commands

CLI Monitoring CommandsCheck Gateway status:

curl http://localhost:5935/status

Monitor available Orchestrators:

curl http://localhost:5935/getOrchestrators

See all CLI options:

Run Livepeer CLI

  livepeer_cli # livepeer_cli --host=localhost --http=5935

Livepeer CLI Output

+-----------------------------------------------------------+
| Welcome to livepeer-cli, your Livepeer command line tool  |
+-----------------------------------------------------------+

What would you like to do? (default = stats)
1. Get node status
2. View protocol parameters
3. List registered orchestrators
4. Invoke "initialize round"
5. Invoke "bond"
...

AI-Specific Monitoring

AI-Specific MonitoringFor AI workflows, the Gateway sends detailed events including:

Stream request events
Orchestrator selection info
Ingest metrics
Error events

Enhanced Monitoring Options

Enhanced Monitoring OptionsAdd to your Docker Compose for more monitoring:

# Enable per-stream metrics
- -metricsPerStream=true

# Expose client IPs in metrics
- -metricsClientIP=true

# Kafka integration (requires setup)
- -kafkaBootstrapServers=kafka:9092
- -kafkaUser=username
- -kafkaPassword=password
- -kafkaGatewayTopic=livepeer-gateway

Log Monitoring

Log MonitoringMonitor logs in real-time:

docker logs -f dual-gateway

Look for key events:

“Received live video AI request”
“Orchestrator selected”
“Transcoding completed”
Payment processing events

Gateway Tips

See all available config flags:Useful CLI Commands

This guide will set up a Livepeer Gateway on the Arbitrum One Mainnet.

Looking for a 'testnet'?

While Livepeer contracts are deployed to Arbitrum Testnet, there is currently no reliable Orchestrator services on this chain.

If you would like to use the Aribtum Testnet for testing, you will need to run your own Orchestrator node there to connect to.

There are conversations underway to enable a public “testnet” in the future.Follow & contribute to the discussion on the Discord and Forum

Install Gateway Software

Pull the Docker image from Livepeer Docker Hub

Configure Gateway

VideoAICreate the docker-compose.yml file that defines the dual Gateway service.

Needs edit, better explanation & format

See flag details below:

See Configuration File Examples below:

Transcoding Options Example

AI Capability Pricing Example

Run Gateway

Connect Gateway

For on-chain mode, Orchestrator discovery happens automatically.

On-chain discovery requires ETH in your Gateway account for transactions
The Gateway will show “No Orchestrator specified; transcoding will not happen” if discovery fails

The Livepeer Explorer Orchestrator Performance Leaderboard can also show you a list of all available Orchestrators & their capabilities & services.

Test Gateway

Verify Configuration

*Verify Ethereum connection Docker logs dual-Gateway | grep -i “Ethereum|ETH|blockchain”Check account address curl http://localhost:5935/status | jq ’.ETH.accountAddr’

Basic Connectivity Tests

Basic Connectivity Tests:These tests verify the Gateway is running and can discover Orchestrators:

On-Chain Specific Tests

On-Chain Specific Tests:Before testing, ensure your on-chain Gateway is properly configured. The Gateway must have an active Ethereum connection and valid account:

Payment Tests

Payment Tests:For on-chain Gateways, test the payment system:

Advanced On-Chain Tests

Advanced On-Chain TestsTest smart contract interactions:

Video Ingest Tests

Video Tests:

AI Tests

AI Tests:AI Capability Tests:

Expected Results

Expected ResultsSuccessful Test Indicators

Status endpoint returns valid Ethereum address
Orchestrators list shows pricing and ticket parameters
Video streams generate HLS playlists
AI endpoints return processed results
Payment operations complete without errors

Common Issues

No Orchestrators found: Check -orchAddr configuration
Payment errors: Verify ETH balance and gas settings
AI failures: Ensure -aiServiceRegistry is set for on-chain AI
Connection timeouts: Check firewall and network settings

Notes

On-chain tests require ETH in the Gateway account for transactions
Test on a testnet first (e.g., Arbitrum-one-goerli) before using mainnet
Monitor gas costs during testing
The test suite includes on-chain validation tests test_args.sh
Use -localVerify=false to skip local verification if needed

Monitor Gateway

The -monitor=true flag in the docker-compose.yml already has basic monitoring enabled which exposes metrics in Prometheus format at http://localhost:8935/metrics.Metrics collected include:

Stream metrics (created, started, ended)
Transcoding metrics (success rate, latency)
Payment metrics (tickets sent, deposits)
AI-specific metrics (attempts, Orchestrators available)

See More Metrics Options Below:

Prometheus Metrics

Access Prometheus metrics at:

curl http://localhost:8935/metrics

Key metrics include:

livepeer_stream_created_total - Total streams created
livepeer_current_sessions_total - Active transcoding sessions
livepeer_success_rate - Transcoding success rate
livepeer_ai_live_attempts - AI processing attempts
livepeer_gateway_deposit - Current ETH deposit

CLI Monitoring Commands

CLI Monitoring CommandsCheck Gateway status:

curl http://localhost:5935/status

Monitor available Orchestrators:

curl http://localhost:5935/getOrchestrators

See all CLI options:

Run Livepeer CLI

  livepeer_cli # livepeer_cli --host=localhost --http=5935

Livepeer CLI Output

+-----------------------------------------------------------+
| Welcome to livepeer-cli, your Livepeer command line tool  |
+-----------------------------------------------------------+

What would you like to do? (default = stats)
1. Get node status
2. View protocol parameters
3. List registered orchestrators
4. Invoke "initialize round"
5. Invoke "bond"
...

AI-Specific Monitoring

AI-Specific MonitoringFor AI workflows, the Gateway sends detailed events including:

Stream request events
Orchestrator selection info
Ingest metrics
Error events

Enhanced Monitoring Options

Enhanced Monitoring OptionsAdd to your Docker Compose for more monitoring:

# Enable per-stream metrics
- -metricsPerStream=true

# Expose client IPs in metrics
- -metricsClientIP=true

# Kafka integration (requires setup)
- -kafkaBootstrapServers=kafka:9092
- -kafkaUser=username
- -kafkaPassword=password
- -kafkaGatewayTopic=livepeer-gateway

Log Monitoring

Log MonitoringMonitor logs in real-time:

docker logs -f dual-gateway

Look for key events:

“Received live video AI request”
“Orchestrator selected”
“Transcoding completed”
Payment processing events

Gateway Tips

Show Connecting to Orchestrators

The Gateway needs to connect to at least one Orchestrator for services.If you’re running your own Orchestrator, you can use this by setting the -orchAddr flag. For on-chain mode, Orchestrator discovery happens automatically but you need to ensure your Gateway has ETH for transactions.

Show See More Explorer Information

The Livepeer Explorer Orchestrator Performance Leaderboard can also show you a list of all available Orchestrators & their capabilities & services. The Performance Leaderboard is provides real-time operational metrics that directly impact Gateway performance, while the main Orchestrators page helps with understanding the economic landscape and potential delegation opportunities.

Show Automatic Orchestrator Discovery System

When you start an on-chain Gateway (-network arbitrum-one-mainnet), it automatically creates a DBOrchestratorPoolCache that polls the blockchain for registered Orchestrators.Unlike off-chain mode where you specify -orchAddr, on-chain Gateways:

Discover all public Orchestrators automatically
Update the list periodically (every 25 minutes)
Handle failures by trying alternative Orchestrators

Orchestrator Discovery Initialisation The discovery process queries the BondingManager smart contract to get all registered Orchestrators with different validation rules for different node types - transcoders require explicit Orchestrator addresses while Gateways can operate with or without them.The discovery system fetches:

All registered Orchestrators from the BondingManager contract
Their capabilities (video transcoding profiles, AI models)
Pricing information for each capability
Performance metrics and capacity

Capability MatchingWhen processing requests, the Gateway:

Queries discovered Orchestrators for required capabilities discovery.go:160-174
Filters by price limits (-maxPricePerUnit for video, -maxPricePerCapability for AI)
Selects based on performance and availability

Docker Tips & Tricks

Verify these

If you wanted to build a go-livepeer Docker image, you can do so from the root of the repository using this:

Reference Pages

Docker Installation Guide

View Full Installation Guide

Configuration Flags Reference

Gateway Configuration Flag Guide

Setup Checklist

See Prerequisites & Requirements.

On-Chain Setup

See on-chain Setup Checklist.

Run a Gateway

See full Gateway Setup Guide.

Orchestrator Guide

Setup an Orchestrator.

​Let’s Go(-Livepeer) !

​ Docker Quickstart Guide

​Docker OS Support for Livepeer Gateway

​Implementation Details

​Docker Build Configuration

​Build Matrix

​Cross-Compilation Support

​GPU Limitations

​Notes

Install Gateway Software

Configure Gateway

Run Gateway

Test Gateway

AI API

Monitor Gateway

Gateway Tips

Install Gateway Software

Configure Gateway

Run Gateway

Connect Gateway

Test Gateway

Monitor Gateway

Gateway Tips

​Reference Pages

Docker Installation Guide

Configuration Flags Reference

​End-to-end test loop with an Orchestrator

Transcoding Orchestrator Quickstart

​Troubleshooting

Common Issues

​Related Pages

Setup Checklist

On-Chain Setup

Run a Gateway

Orchestrator Guide

Let’s Go(-Livepeer) !

Docker Quickstart Guide

Docker OS Support for Livepeer Gateway

Implementation Details

Docker Build Configuration

Build Matrix

Cross-Compilation Support

GPU Limitations

Notes

Reference Pages

End-to-end test loop with an Orchestrator

Troubleshooting

Related Pages