Apache Ratis packages Raft as a Java library with swappable state machines and transports

A replicated log library, not a consensus product

The framing matters before anything else. Ratis is a Java library implementing the Raft protocol, and the README describes its purpose as making Raft available to any system that needs a replicated log. It is not a database, not a distributed file system and not a key-value store.

That boundary determines who should look at it. If you are choosing a consensus implementation for Hadoop, HBase, Kafka or a storage engine, Ratis is a candidate. If you are choosing a replicated datastore, you are looking at the wrong repository and should be evaluating a system that already made those choices for you.

The protocol itself is Raft, with the extended paper linked from the README at raft.github.io/raft.pdf, and the original Ongaro and Ousterhout USENIX ATC 2014 paper cited as the reference. The README quotes the paper on why Raft exists at all, namely that it produces a result equivalent to multi-Paxos with a structure that is easier to understand and a better foundation for practical systems.

One stated design goal deserves attention because it is not standard: high throughput data ingest. The README says an important goal is supporting high throughput data ingest so Ratis can be used for more general data replication cases. Read that as an intent rather than a measured claim, since the README publishes no throughput figures.

Four pluggability points, each a separate module

The README states the pluggability surface in one sentence: state machine implementations to manage replicated state, Raft log implementations, RPC implementations, and metric implementations. Each of those is a place where you supply code, which is the main reason the module structure in this repository looks the way it does.

The top-level entries give the map. `ratis-common/` is the shared core. `ratis-client/` is the client-facing side, and `ratis-server/` with `ratis-server-api/` is the peer side, where the API module separates the contract from the implementation. `ratis-proto/` holds the protocol definitions. `ratis-assembly/` and `ratis-bom/` are packaging concerns, with the BOM existing so downstream projects can align dependency versions across Ratis artifacts.

Transport and observability are the two axes with the most obvious module-per-choice structure. `ratis-grpc/` and `ratis-netty/` are the two RPC implementations named in the layout, so the RPC pluggability point is concrete rather than theoretical. Metrics has three modules: `ratis-metrics-api/` defines the interface, `ratis-metrics-default/` provides an implementation, and `ratis-metrics-dropwizard3/` provides a Dropwizard Metrics backed one. `ratis-trace-otel/` is the OpenTelemetry module.

The testing and tooling modules tell you how the project works. `ratis-test/` holds the test harness, `ratis-experiments/` is where non-production work goes, `ratis-tools/` is administrative tooling, and `ratis-shell/` is a shell for driving a cluster by hand. `ratis-resource-bundle/` centralises configuration and messages, and `ratis-docs/` holds documentation. `dev-support/` holds contributor support files.

Building it: Maven wrapper, BUILDING.md, and a build env script

The README keeps the build instructions short and points elsewhere, which is normal for an Apache project. It says to see BUILDING.md to build the artifacts, and `ratis-examples/README.md` to run the examples. Both files are in the repository root area.

That matters for reproducible CI builds, where pinning the wrapper is often a requirement.

There is also a `start-build-env.sh` script at the root, which suggests a Docker-based or scripted development environment for getting a working toolchain before you build. Its contents are not shown in the repository listing, so read it before assuming what it provides.

`DEPLOY.md` sits alongside `BUILDING.md`, covering release mechanics. Worth noting: the repository has no GitHub releases, and `pom.xml` sits at the root as the aggregator for the reactor.

A `.asf.yaml` file at the root is the ASF metadata declaration, and `.idea/` is checked in, which is unusual and suggests the project ships IntelliJ configuration for contributors.

What you still have to write yourself

The pluggability that makes Ratis flexible is the same thing that makes it work. Nothing in the repository description indicates that a state machine, a durable log or an RPC layer ships ready to use, so the honest accounting of an adoption is what you must supply.

At minimum, a real deployment needs a durable log. Raft's safety argument depends on log entries surviving a crash, and mapping Raft log entries onto your storage is exactly the kind of code where a subtle mistake is invisible until data loss. The library abstracts this behind a pluggable Raft log, which means the abstraction is available but the implementation is yours.

Second, the state machine. Raft only guarantees that every replica applies the same commands in the same order; it does not decide what applying means. That application logic, including idempotence in the face of a re-applied entry, is your code.

Third, membership. Changing the set of peers in a Raft cluster is where most integration bugs live, and nothing in the module list suggests a turnkey membership workflow. Verify against your operational expectations rather than assuming the library handles joint consensus cases the way you need.

Fourth, the client story. `ratis-client/` exists, but a client library that needs routing, retry and reconnection semantics layered on top is still your design work.

How it compares with other Java Raft implementations

There is no single consensus implementation for Java, and the meaningful differences are in scope.

Against a database that already ships Raft, such as a distributed SQL engine or a Kafka-like log, the comparison is not feature by feature. Those systems make storage, membership and recovery decisions for you and expose a data API. Ratis exposes a replicated log and makes you implement the state machine. Choose Ratis when the existing system's storage model or deployment shape is wrong for your workload.

Against lower-level building blocks, the difference is in what is already solved. Because Ratis is a library rather than a service, it has no process to supervise, no ports to expose and no data format to migrate. `ratis-grpc/` and `ratis-netty/` mean the transport is a module decision, and `ratis-metrics-api/` with `ratis-trace-otel/` mean observability plugs into systems you already run rather than requiring you to adopt the library's own.

Against other Apache Raft-adjacent work, the ASF governance is the practical difference.

One caution on this comparison: The README publishes no throughput figures. Any throughput or latency claim you encounter elsewhere came from somewhere other than this README, so verify it against your own workload, particularly since the README names high throughput ingest as a goal without a number attached.

Licence, governance and what the last push tells you

The project is Apache-2.0, with both a `LICENSE` and a `NOTICE` file at the root, which is the standard Apache distribution pair and the one to keep intact when you redistribute. The README header also carries the licence text, so the obligation to retain the notice is stated in the file most people read first.

Governance is worth noting for a component in your write path. `.asf.yaml` marks the repository as an ASF project, and `dev-support/` holds the contributor infrastructure.

On activity, the repository is not archived and the last push was on 2026-10-15. That is a current signal, and the fact that `pom.xml` and the module set are actively changing means you should expect module and API movement between versions even though the repository shows no GitHub releases to track.

The default branch is `master`, not `main`, which is an older Apache convention and occasionally surprises tooling that assumes `main`.

`ratis-examples/README.md` is the pointer for running examples. Start there: an example that boots a small cluster tells you more about what a first integration looks like than the module list does.

Editorial conclusion

Apache Ratis fits a Java team that needs a replicated log inside an existing system and wants Raft without writing leader election, log shipping and membership change itself. Do not expect a storage engine, a replication product or a turnkey cluster from it, since the repository ships no server product and no release tags, and do not choose it if you need snapshots and membership changes to be a solved problem rather than an integration task. Verify first which module owns your state machine and which owns your transport, because the pluggability the README advertises means you will be writing at least one of those implementations yourself.

Frequently asked questions

Official sources

1. apache/ratis on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README