Developing Catalyst is currently supported on macOS and Linux.
You’ll need the following things installed locally:
- Docker (or Podman 4.6.0+, which works even better)
- Buildah (for
docker buildx, included with Podman and Docker for Mac)
- Go v1.20+
- Node.js v18+ (Studio development only)
- llvm (
brew install llvmfor compiling MistServer and go-livepeer on MacOS only)
You’ll first need to clone the Catalyst repo if you haven’t already.
git clone https://github.com/livepeer/catalyst.git
Then you’ll need to download/build all the binaries that you’ll need.
make # downloads all the external binaries & builds the local ones
make box # builds the livepeer/in-a-box Docker image
Now you’re ready to boot up your development environment!
Lots and lots of logs will print out while all the dependencies finish booting up. After that, you’ll now have a fully-functioning full-stack Livepeer Studio + Catalyst environment running locally! You can access it like so:
- URL: http://localhost:8888
Customizing the Environment
If you need to add additional parameters to things running inside the box, you
can create a
.env file that contains key-value pairs:
echo "CATALYST_API_CDN_REDIRECT_PREFIX=https://externalcdn.livepeer.com/mist/" >> .env
echo "CATALYST_API_CDN_REDIRECT_PLAYBACK_IDS=222222222222" >> .env
Note that this mechanism is limited to adding new configuration; existing
configuration cannot be modified this way. If you need to modify existing
configuration you can manually change the file in
more robust configuration management system is under development.
TLDR: Use a command like this and the Makefile will take care of it for you:
The general Livepeer in a Box development cycle works like this:
- Make changes to code on your local filesystem
- Build a Linux binary from that code
- Move that Linux binary into the
catalyst, which is mounted by
- Kill the old version of your binary and allow MistController to bring it back up.
Thankfully, this entire process has been automated. All you need to do is have
the project you’re working on cloned in a directory adjacent to
example, if you’re hacking on
task-runner, you might have
The catalyst Makefile is aware of the common paths for all of the other projects that go into the full stack. All that’s necessary to build a new binary, package it in the container, and trigger a restart is a single command:
Note that the names of all subprojects are prefixed with
livepeer, just like
the resulting binaries within the Catalyst container. This yields the following
|Studio Node.js API Server
Connecting the Frontend
Livepeer in a Box comes with a pkg-bundled version of the Livepeer Studio API server and frontend, but does not include a full development environment for that frontend. If you are making changes to the frontend, you can boot it up as you usually would:
yarn run dev
To connect it to the box; there’s a hidden
localStorage variable you can use
to override the API server URL. Open your browser console and type in the
Reload the page and your frontend should be connecting to the box as an API server.
Additional note: in the interest of build speed,
make livepeer-api does not
package the frontend within the
livepeer-api binary that it builds, so if you
experience your frontend suddenly 404ing after you run
make livepeer-api you
will have to use the above instructions to boot up the frontend on your host.
You can also build the full API server with a bundled frontend using
make livepeer-api-pkg, but be aware this frequently takes 3-4 minutes to
- Your CockroachDB (Postgres) database and your Minio (S3) object store will be
saved in the
datasubdirectory of your Catalyst installation. If you want to start from scratch again with the
firstname.lastname@example.org snapshot, shut down your box and
rm -rf data.
- You can press
Ctrl+Cto trigger a graceful shutdown of the container. If you’re impatient, following it up with a
Ctrl+\can uncleanly shut things down a bit more cleanly.
- Sometimes the rate of logs produced by Catalyst somehow overwhelms Make and
log output simply stops. You’ll know if you get in this state because you’ll
press Ctrl+C and control will return immediately to your terminal instead of
shutting down the Docker image. You can start everything back up with
docker rm -f catalystand
- Changed the hardcoded streams in the database snapshots to have
easy-to-remember stream keys like
- Changed the built-in streams to use the H264ConstrainedHigh profile so there are no B-Frames in the output
- Moved all references from
localhost; this is needed for WebRTC/Coturn to work properly
- Removed outdated references to
KILL=true; these are the defaults now
Was this page helpful?