Quick Start
There are three ways to get started running Liftbridge on your machine: downloading a pre-built binary, building from source, or running a Docker container. There are also several options for running a Liftbridge cluster described below.
Binary
A pre-built Liftbridge binary can be downloaded for a specific platform from the releases page. Once you have installed the binary, refer to the steps under Building From Source for running the server.
Building From Source
A Liftbridge binary can be built and installed from source using Go. Follow the below step to install from source.
$ go get github.com/liftbridge-io/liftbridge
Liftbridge uses Go modules, so
ensure this is enabled, e.g. export GO111MODULE=on.
Liftbridge currently relies on an externally running
NATS server. By default, it will connect
to a NATS server running on localhost. The --nats-servers flag allows
configuring the NATS server(s) to connect to.
Also note that Liftbridge is clustered by default and relies on Raft for
coordination. This means a cluster of three or more servers is normally run
for high availability, and Raft manages electing a leader. A single server is
actually a cluster of size 1. For safety purposes, the server cannot elect
itself as leader without using the --raft-bootstrap-seed flag, which will
indicate to the server to elect itself as leader. This will start a single
server that can begin handling requests. Use this flag with caution as it should
only be set on one server when bootstrapping a cluster.
$ liftbridge --raft-bootstrap-seed
INFO[2020-04-27 17:20:21] Liftbridge Version: v1.0.0
INFO[2020-04-27 17:20:21] Server ID: agTv5PkzvgKygm688EMd4C
INFO[2020-04-27 17:20:21] Namespace: liftbridge-default
INFO[2020-04-27 17:20:21] Retention Policy: [Age: 1 week, Compact: false]
INFO[2020-04-27 17:20:21] Starting server on 0.0.0.0:9292...
INFO[2020-04-27 17:20:23] Server became metadata leader, performing leader promotion actions
Once a leader has been elected, other servers will automatically join the cluster.
We set the --data-dir and --port flags to avoid clobbering the first server.
$ liftbridge --data-dir /tmp/liftbridge/server-2 --port=9293
INFO[2020-04-27 17:21:10] Liftbridge Version: v1.0.0
INFO[2020-04-27 17:21:10] Server ID: OtKIIhwxBztcSkgZD0xXQP
INFO[2020-04-27 17:21:10] Namespace: liftbridge-default
INFO[2020-04-27 17:21:10] Retention Policy: [Age: 1 week, Compact: false]
INFO[2020-04-27 17:21:10] Starting server on 0.0.0.0:9293...
We can also bootstrap a cluster by providing the explicit cluster configuration.
To do this, we provide the IDs of the participating peers in the cluster using the
--raft-bootstrap-peers flag. Raft will then handle electing a leader.
$ liftbridge --raft-bootstrap-peers server-2,server-3
Docker Container
Instead of running a binary, you can run Liftbridge using a container. There is a container image available which runs an instance of Liftbridge and NATS inside a single Docker container. This is meant for development and testing purposes. Use the following Docker commands to run this container:
$ docker pull liftbridge/standalone-dev
$ docker run -d --name=liftbridge-main -p 4222:4222 -p 9292:9292 -p 8222:8222 -p 6222:6222 liftbridge/standalone-dev
This will run the container which will start both the NATS and Liftbridge servers. To check the logs to see if the container started properly, run:
$ docker logs liftbridge-main
See the deployment guide for more information.
Running a Liftbridge Cluster Locally
The quickest way to get a multi-node Liftbridge cluster up and running on your machine is with either Docker Compose or Kind (Kubernetes in Docker). Follow the deployment guide for help running a cluster locally for development or testing.