Skip to main content

Build your first cluster

You are going to build QuorumKit from source, start a three-node replicated counter on your local machine, and send it some requests. The whole thing takes a few minutes (plus time for the first Conan build).

Install prerequisites​

You need a C++17 compiler, CMake 3.15+, and Conan 2. See Prerequisites for install commands.

Build the library​

From the repository root, export the local brpc recipe (one-time step):

conan export contrib/brpc/

Install all dependencies and generate CMake presets:

conan install . --output-folder=build --build=missing

Build:

cmake --preset conan-release
cmake --build --preset conan-release

When this finishes you should have libbraft.a and test binaries under build/. If something goes wrong, see Troubleshoot common problems.

Run the tests​

Confirm everything works:

ctest --preset conan-release --output-on-failure -LE known_crash

You should see a clean test run. The -LE known_crash flag skips three tests with upstream braft bugs.

Build the counter example​

The counter example is a small replicated counter service -- three servers that agree on a single integer.

cmake --preset conan-release -DBUILD_EXAMPLES=ON
cmake --build --preset conan-release

This produces the counter example binaries under build/build/Release/examples/counter/.

Start the cluster​

cd examples/counter
bash run_server.sh

This launches three server processes on localhost. Each one writes its Raft log and snapshot data into a subdirectory under examples/counter/. The script resolves counter_server from the CMake build tree, so you do not need to copy binaries around by hand. You will see log output showing leader election: one node wins an election and the other two become followers.

Send requests​

In a second terminal:

cd examples/counter
bash run_client.sh

The client sends increment requests to the cluster. You should see the counter value increasing in the client output. Behind the scenes, each request goes to the leader, gets replicated to a majority, and then gets applied to the counter state machine on all three nodes.

What just happened​

You ran the full Raft cycle: a client wrote to a leader, the leader replicated the write to followers, a majority acknowledged it, and all three nodes applied the same state transition in the same order. The counter example is intentionally minimal -- it exists so you can see that loop without any extra complexity.

Where to go from here​