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 20 tests pass. The -LE known_crash flag skips three tests with upstream braft bugs.

Build the counter example​

note

The examples are not yet wired into the Conan build system. They still use standalone CMake and assume the library is already built. This section will be updated once the examples are integrated.

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

cd example/counter
cmake .
make

This produces the server and client binaries in the example/counter directory.

Start the cluster​

bash run_server.sh

This launches three server processes on localhost. Each one writes its Raft log and snapshot data into a subdirectory under example/counter/. 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 example/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​