Self Hosted Livepeer Gateway

Overview

This guide will walk you through the Livepeer Gateway installation and
setup. Steps to install for Ubuntu Linux, Docker, and Windows are provided.
Choose the environment you want, follow install instructions, then continue to
the configuration section.

Note the Livepeer Gateway was previously called the Livepeer Broadcaster so you will see some commands and labels still use the Broadcaster name that haven't been updated in the code.

Quick Links

Docker Installation

Linux Installation

Windows Installation

Configure Transcoding Options

Fund the Livepeer Gateway

Publish Content

Playback Content

Prerequisites

This guide assumes you are familiar with installing software on unix-based
systems. You should be comfortable with command-line syntax, Networking,
Firewalls, and containerized environments. You should have a basic understanding
of the Livepeer protocol. You dont have to be an expert, but troubleshooting
skills will come in handy. For more information view the go livepeer installation guide

This guide was developed using:

  • Ubuntu Linux 22.04
  • Docker 20.10.14
  • Windows
  • Livepeer 0.7.2
  • root user access (sudo is ok)

Have access to an Arbitrum RPC URL. This is required to run Livepeer.
Popular services include Infura and
Alchemy. Be aware that these services have their
own pricing plans. That being said, the latest versions of livepeer should be able
to stay within the request limit for these provider's free tier at least for a single
node. As an alternative, you can self-host your own Arbitrum node, see the
instructions from Offchain Labs.

Install Using Docker

Key folder structure

Livepeer will require files to be placed on the host and within the docker
container. Here is a list of the key folders used by the docker install.

Host Folders

By default, docker will store all volumes in the /var/lib/docker/volumes
directory

This installation will create a volume called: gateway-lpData and it will
be located at /var/lib/docker/volumes/gateway-lpData/_data

Container Folders

Within the docker container, the volume gateway-lpData will be mounted at
/root/.lpData

Install Prerequisites

If docker is already installed, you can skip this step. The installation assumes
you are running Docker 20.10.x. If an older version of docker is installed
remove it with the following command:

As the root user (or sudo), run the following:

apt remove docker*

Install Docker

curl https://releases.rancher.com/install-docker/20.10.sh | sh

Create a Docker volume

docker volume create gateway-lpData

Create Docker Compose file from the root user's home directory /root/

nano docker-compose.yml

Copy and paste the following and save the following

version: '3.9'

services:
  gateway:
    image: livepeer/go-livepeer:<RELEASE_VERSION>
    container_name: "gateway"
    hostname: "gateway"
    ports:
      - 1935:1935
      - 8935:8935
    volumes:
      - gateway-lpData:/root/.lpData
    command: '-ethUrl=https://arb1.arbitrum.io/rpc/
              -ethKeystorePath=/root/.lpData
              -network=arbitrum-one-mainnet
              -cliAddr=gateway:5935
              -broadcaster=true
              -monitor=true
              -v=99
              -blockPollingInterval=20
              -maxPricePerUnit=300
              -pixelsPerUnit=1
              -rtmpAddr=0.0.0.0:1935
              -httpAddr=0.0.0.0:8935
              '
volumes:
  gateway-lpData:
    external: true

Create Livepeer Gateway ETH account

In this step we need to start the Gateway in order to create an Ethereum
account.

docker compose run -it gateway

When prompted for the ETH password, enter a strong password to secure your
Ethereum account. This password is used to decrypt and access the ETH private
key. Make sure to never share or lose access to either the password or the
keystore file.

Note: Keep this password handy, we will use it in the following steps.

After you see the message that the Ethereum account has been unlocked, CTRL+C to
exit the Livepeer docker instance.

Using the previously created ETH password, create the eth-secret file

nano -p /var/lib/docker/volumes/gateway-lpData/_data/eth-secret.txt

Modify Docker compose file to include eth-secret.txt

nano docker-compose.yml

Add the following line below the -ethKeystorePath and save

-ethPassword=/root/.lpData/eth-secret.txt

Here is the full modified version of the docker-compose.yml file

version: '3.9'

services:
  gateway:
    image: livepeer/go-livepeer:<RELEASE_VERSION>
    container_name: "gateway"
    hostname: "gateway"
    ports:
      - 1935:1935
      - 8935:8935
    volumes:
      - gateway-lpData:/root/.lpData
    command: '-ethUrl=<YOUR ARB APC>
              -ethKeystorePath=/root/.lpData
              -ethPassword=/root/.lpData/eth-secret.txt
              -network=arbitrum-one-mainnet
              -cliAddr=gateway:5935
              -broadcaster=true
              -monitor=true
              -v=99
              -blockPollingInterval=20
              -maxPricePerUnit=300
              -pixelsPerUnit=1
              -rtmpAddr=0.0.0.0:1935
              -httpAddr=0.0.0.0:8935
              '
volumes:
  gateway-lpData:
    external: true

Start Livepeer in the background

docker compose up -d

Launch the livepeer_cli

docker exec -it gateway /bin/bash
livepeer_cli -host gateway -http 5935

Jump to
Configure Transcoding Options to
finish configuring the Gateway

Linux Installation

Download the Livepeer binary

sudo wget https://github.com/livepeer/go-livepeer/releases/download/<RELEASE_VERSION>/livepeer-linux-amd64.tar.gz

Unpack and remove the compressed file

sudo tar -zxvf livepeer-linux-amd64.tar.gz
sudo rm livepeer-linux-amd64.tar.gz
sudo mv livepeer-linux-amd64/* /usr/local/bin/

Generate a new keystore file

/usr/local/bin/livepeer -network arbitrum-one-mainnet -ethUrl <ARBITRUM RPC URL> -broadcaster
exit

When generating a new keystore file, the program will prompt you for a password. This password is used to decrypt the keystore file and access the private key. Make sure to never share or lose access to either the password or the keystore file

Create a file containing your Gateway Ethereum password

sudo mkdir /usr/local/bin/lptConfig
sudo nano /usr/local/bin/lptConfig/node.txt

Enter your password and save the file

Create a system service

sudo nano /etc/systemd/system/livepeer.service

Paste and update the following startup script with your personal info:

[Unit]
Description=Livepeer

[Service]
Type=simple
User=root
Restart=always
RestartSec=4
ExecStart=/usr/local/bin/livepeer -network arbitrum-one-mainnet \
-ethUrl=<YOUR ARB RPC URL> \
-cliAddr=127.0.0.1:5935 \
-ethPassword=/usr/local/bin/lptConfig/node.txt \
-maxPricePerUnit=300 \
-broadcaster=true \
-transcodingOptions=/usr/local/bin/lptConfig/transcodingOptions.json \
-rtmpAddr=0.0.0.0:1935 \
-httpAddr=0.0.0.0:8935 \
-monitor=true \
-v 6 

[Install]
WantedBy=default.target

Start the system service

sudo systemctl daemon-reload
sudo systemctl enable --now livepeer

Open the Livepeer CLI

livepeer_cli -host 127.0.0.1 -http 5935

Jump to Configure Transcoding Options to finish configuring the Broadcaster

Windows Installation

Download and unzip the Livepeer binary

https://github.com/livepeer/go-livepeer/releases/download/<RELEASE_VERSION>/livepeer-windows-amd64.zip

Create a bat file to launch Livepeer.

Use the following as a template, adding your personal info and save a .bat file in the same directory as the Livepeer executable.

livepeer.exe -network=arbitrum-one-mainnet -ethUrl=<YOUR ARB RPC> -cliAddr=127.0.0.1:5935 -broadcaster -maxPricePerUnit=300 -pricePerUnit=1 -monitor=true -v=6 -rtmpAddr=0.0.0.0:1935 -httpAddr=0.0.0.0:8935 -blockPollingInterval=20

PAUSE

Start the Livepeer Gateway

Start the Livepeer Gateway using the .bat file.

When prompted enter and confirm a password.

This password is used to decrypt the keystore file and access the private key. Make sure to never share or lose access to either the password or the keystore file

After confirming your password close the terminal.

Create a file containing your Gateway Ethereum password

In C:\Users\YOUR_USER_NAME\.lpData create a txt file named ethsecret.txt with the password you created in the previous step.

Add the -ethPassword flag to your .bat file

Add -ethPassword=C:\Users\YOUR_USER_NAME\.lpData\ethsecret.txt to the previously created .bat file

If you'd like the Gateway to start with Windows you can create a System service using NSSM or the Windows Task Scheduler.

Open the Livepeer CLI, then Jump to Configure Transcoding Options to finish configuring the Gateway

livepeer_cli.exe -host 127.0.0.1 -http 5935

Configure Transcoding Options

To better control your encoding profiles it is recommended to use a json file
to specify the resolution and bitrate for your encoding ladder.

Create the JSON file

Use the following as a template for your json file

[
{
  "name": "480p0",
  "fps": 0,
  "bitrate": 1600000,
  "width": 854,
  "height": 480,
  "profile": "h264constrainedhigh",
  "gop": "1"
},
{
  "name": "720p0",
  "fps": 0,
  "bitrate": 3000000,
  "width": 1280,
  "height": 720,
  "profile": "h264constrainedhigh",
  "gop": "1"
},
{
  "name": "1080p0",
  "fps": 0,
  "bitrate": 6500000,
  "width": 1920,
  "height": 1080,
  "profile": "h264constrainedhigh",
  "gop": "1"
}
]

Modify Docker Config

Create the transcodingOptions.json file using the above template.

nano -p /var/lib/docker/volumes/gateway-lpData/_data/transcodingOptions.json

Modify the docker-compose.yml file from the root user's home directory /root/ and add the following below -pixelsPerUnit=1

-transcodingOptions=/root/.lpData/transcodingOptions.json

Modify Linux Config

Create the transcodingOptions.json file using the above template.

sudo nano /usr/local/bin/lptConfig/transcodingOptions.json

Modify the Linux Service file /etc/systemd/system/livepeer.service and add the following below -pixelsPerUnit=1

-transcodingOptions=/usr/local/bin/lptConfig/transcodingOptions.json \

Modify Windows Config

Create the transcodingOptions.json file using the above template.

Open notepad (or your text editor of choice) paste the template above and save the transcodingOptions.json file in the following location.

Note: Replace YOUR_USER_NAME with your actual user name

C:\Users\YOUR_USER_NAME\.lpData\transcodingOptions.json

Modify Windows bat file to include the following command after -pixelsPerUnit=1

-transcodingOptions=C:\Users\YOUR_USER_NAME\.lpData\transcodingOptions.json

Fund The Livepeer Gateway

The following steps will walk you through adding funds to the newly created
ETH account. This includes funding the ETH account on Ethereum Mainnet,
bridging the funds to Arbritrum's L2 Network, and finally using the Livepeer
CLI to allocate the proper deposit and reserve amounts.

Add Funds to Gateway Wallet

In order to use the Gateway you need to send ETH to your Gateway address
on Ethereum Mainnet and then bridged to Arbitrum's L2 Network.

Note:

  • if you have ETH on the Arbitrum L2 Network, you can simply transfer the funds
    to the newly created Gateway ETH Account.
  • Livepeer runs on the Arbitrium's L2 Network and requires the funds to be
    bridged.

Bridge Funds to Arbitrum

If you need to bridge ETH you can use the official bridge
https://bridge.arbitrum.io/ or use an exchange that supports L2 transfers. For additonal
information on bridging view the Livepeer bridging guide.

Once you have ETH on the Arbitrum network, transfer it to your newly created
Gateway address.

Deposit Gateway Funds via Livepeer CLI

We now need to divide the Gateway funds into a Deposit and Reserve

In this guide we are using a total of 0.1 ETH. This is minimum recommended and
best suited for testing.

To calculate the price your Gateway will pay for transcoding, divide the
Reserve amount by 100. In our example each payment will be 0.0003 ETH (0.03
/ 100)

As you pay for transcoding the amount paid is subtracted from your Deposit, so
make sure to monitor your Deposit balance and top it off to keep your
Gateway transcoding.

Open the Livepeer CLI

Open the Livepeer CLI by following the instructions for your platform.

Choose Option 11. Invoke "deposit broadcasting funds" (ETH)

  • Enter 0.065 for the Deposit and 0.03 for the Reserve amounts when
    prompted.

Choose Option 1. Get node status and confirm that the correct amounts are
visible in the BROADCASTER STATS section.

Publish Content

This section explains how to publish and consume content to the Livepeer Gateway.

This can be done via a command line interface using FFmpeg, or from a graphical user interface using OBS Studio and VLC Media Player.

Command Line Interface

This section explains how to publish content to and from Livepeer Gateway using a command line interface (CLI).

Install FFmpeg

Install FFmpeg for your platform following the instructions on the FFmpeg website.

Run the following command to send an RTMP test stream to the Gateway:

ffmpeg -re -f lavfi -i \
       testsrc=size=1280x720:rate=30,format=yuv420p \
       -f lavfi -i sine -c:v libx264 -b:v 3000k \
       -x264-params keyint=60 -c:a aac -f flv \
       rtmp://<YOUR IP ADDRESS>:1935/test_source
  • test_source is the "stream key" for this publication.
  • size=1280x720 defines the dimensions of the test video source in pixels
  • rate=30 defines the frame rate of the test video in frames per second
  • 1000k defines the bitrate for the stream
  • keyint=60 defines the keyframe interval in frames

Run the following command to send a recorded video file to the Gateway:

ffmpeg \
        -re \
        -i video.mov \
        -codec copy \
        -f flv rtmp://<YOUR IP ADDRESS>:1935/video_file
  • video_file is the "stream key" for this stream.

Graphical User Interface

This section explains how to publish media to the Livepeer Gateway using a graphical user interface (GUI).

Publish content using OBS Studio

OBS Studio can be used to publish streaming media to the Livepeer Gateway:

Download and install OBS Studio

In the Stream section of OBS Studio enter the following:

Service: Custom
Server: rtmp://<YOUR IP ADDRESS>:1935
Stream Key: stream-key

In the main window choose Start Streaming

Playback Content

Playback using VLC Media Player

This section explains how to view content from the Livepeer Gateway.
We will be using VLC Media Player.

  1. Download and install VLC Media Player

  2. Launch VLC Media Player

  3. Select Media > Open Network Stream... (Ctrl-N)

  4. Enter http://<GATEWAY IP ADDRESS>:8935/stream/<YOUR STREAM KEY>.m3u8 as the network URL

  5. Click "Play", and view the content from the obs-studio stream: