# riak_core: the Erlang distributed systems layer under Riak

> riak_core is the Basho framework that provides the clustering and scaling machinery Riak is built on, usable on its own as a toolkit for distributed Erlang applications. It ships with rebar3 targets for unit tests, QuickCheck property tests, Dialyzer and xref, and its visible release tags are Riak KV tags from 2023.

**basho/riak_core** — Distributed systems infrastructure used by Riak.

- Repository: https://github.com/basho/riak_core
- Stars: 1,276 · Forks: 385
- Language: Erlang
- License: Apache-2.0
- Published: 2026-10-17 · Updated: 2026-10-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/basho-riak-core

## riak_core is the part of Riak you can lift out

Riak is a database. riak_core is the framework underneath it that decides how nodes find each other, how data is distributed, and how the system scales. The README puts it as the distributed systems framework forming the basis of how Riak distributes data and scales, and then widens the frame: more generally it can be thought of as a toolkit for building distributed, scalable, fault-tolerant applications.

That second sentence is the one that matters for an adoption decision. You can take riak_core without taking the Riak key-value store on top of it, which is a meaningful option for teams whose data model does not fit Riak KV but whose operational requirements, clustered nodes that tolerate failure, are the same.

The code is Erlang, licensed Apache-2.0, and the default branch is develop, which is worth noting for anyone who clones with a shallow default and assumes they have a stable tree. The repository also carries a vendored `rebar3` executable alongside `rebar.config`, so the build does not depend on a globally installed Erlang build tool.

## Building and testing through the Makefile

Every build action in this repository goes through rebar3, invoked through a thin Makefile. The compile and test targets look like this:

```bash
compile:
	$(REBAR) compile

test: compile
	$(REBAR) eunit
```

The `REBAR` variable is set to `./rebar3` in the Makefile, so the bundled binary is used rather than whatever happens to be on your path. The `test` target depends on `compile`, which means a test run always rebuilds first, and the unit tests are eunit tests inside the project.

Two other targets deserve attention because they change how you should read a green build. The `cover` target runs eunit with coverage and then generates the report:

```bash
cover: 
	$(REBAR) eunit --cover
	$(REBAR) cover
```

And `clean` runs `$(REBAR) clean`, which is the fastest way to get out of a broken build state after a dependency change.

For a first use, the sequence is short: clone the repository, make sure you have a working Erlang and rebar3 environment, run `make compile`, then `make test`. If you want to see the project under the same conditions its own CI uses, run `make check`.

## Property testing with eqc and the check gate

The `eqc` target is the most distinctive part of the build, and it points at how this project thinks about correctness. It is not a unit test suite, it is property based testing:

```bash
eqc:
	$(REBAR) as test eqc --testing_budget 120
	$(REBAR) as eqc eunit
```

The first line compiles the project in the `test` profile and runs QuickCheck style generated cases with a testing budget of 120, and the second runs the eunit suite again in the `eqc` profile so the two configurations are exercised together. The repository root carries an `eqc/` directory, which is where those properties live.

The gate is `check`, which chains three separate analyses:

```bash
check: test dialyzer xref
```

So a full check runs the unit tests, then Dialyzer for type and spec consistency, then xref for undefined function and unused export analysis. The three are separate targets in the Makefile, and `dialyzer` and `xref` are separate targets in the Makefile, so you can run either on its own while iterating.

For distributed systems code, where a bug may only appear under a particular interleaving of node messages, generated property tests are a better fit than example based tests, and this repository treats them as part of the standard check rather than an optional extra.

## What the repository layout tells you

The top level directory listing is short and tells you how the project is organised. `src/` holds the Erlang source, `include/` holds the public headers, and `priv/` holds runtime assets that ship with the application. `test/` is where the eunit tests live, `eqc/` holds the property tests, and `docs/` contains the documentation. `rebar.config` describes the application and its dependencies, and `rebar3` is the vendored build tool binary.

Two things are absent and worth noticing. There is no `Dockerfile` and no container configuration in the listing, so unlike many modern Erlang projects there is no packaged image to build your way to a running cluster. There is also no configuration directory with example files, so the configuration surface has to be learned from the docs rather than from a sample file you can copy.

The `Makefile` itself is worth reading as documentation. It is the only build entry point the project ships, and it lists exactly which analyses the maintainers considered worth having in CI.

## Contributing patches and where to ask questions

The contribution path is a plain GitHub flow, and the README is unusually explicit about the steps. Fork the repository, clone your fork or add the remote, create a topic branch for the change, make the change and commit with a clear and descriptive commit message spanning multiple lines if a detailed explanation is needed, push to your fork, and open a pull request. A Riak committer then reviews the patch and either merges it or sends feedback.

The commit message guidance is stricter than most projects, and it fits the project: this is distributed systems code where the reasoning behind a change matters as much as the diff.

Questions have their own channels, separated by scope. The Riak Users List is described as the main place for all discussion around Riak, and there is a separate Riak Core-specific mailing list for issues that pertain to Core but not Riak. The README also points at the #riak channel on Freenode for real-time help, and asks for bugs to be filed as clear, concise, explanatory issues against the repository. The distinction between the two mailing lists is the one to use when deciding where a question goes.

## Release tags from Riak KV and a 2026 push

The maintenance picture needs reading carefully, because the two signals point in different directions. The repository is not archived, and the last push was on 2026-08-14, so commits are still landing on the develop branch. The visible release tags, on the other hand, are not riak_core versions at all: they are Riak KV releases, 3.0.13 on 2023-02-02, 3.0.14 on 2023-02-10, and 3.0.16 on 2023-06-22.

That tells you riak_core is versioned and tagged as part of the Riak KV release train, which is how downstream consumers get a consistent set of components. It also means there is no separate riak_core release you can pin on its own from the tag list.

Because the last push is more recent than the newest visible tag, work has continued on the branch since that train. If you need a pinned, reproducible dependency, pin to a Riak KV tag and read the changes since. If you want the current state of the framework, track the develop branch and expect the raw Erlang dependencies to move.

The Apache-2.0 licence is the permissive one, so vendoring riak_core into a larger Erlang release carries no copyleft obligation beyond keeping the licence and notice files in place.

## Conclusion

riak_core is worth adopting if you build distributed Erlang systems and want a proven clustering and scalability layer rather than writing gossip and membership management yourself, and if you are prepared to maintain Erlang tooling in your build. It is the wrong choice for a new project without Erlang experience, or for anyone who needs a current release trail, since the visible tags are Riak KV 3.0.x releases from 2023 and the last push was on 2026-08-14. Before building on it, run `make check` in a clone to see the unit, Dialyzer and xref gates pass on your Erlang version, and read the docs/ directory to confirm the membership and handoff behaviour matches what your cluster needs.

## FAQ

### What is riak_core used for?

It is the distributed systems framework that forms the basis of how Riak distributes data and scales, and it can also be used on its own as a toolkit for building distributed, scalable, fault-tolerant applications. It is written in Erlang and licensed Apache-2.0.

### How do you build and test riak_core?

The repository ships a Makefile that drives rebar3, with the bundled `./rebar3` binary. `make compile` builds, `make test` compiles and then runs the eunit tests, and `make check` chains test, dialyzer and xref.

### What does the eqc target do in riak_core?

It runs property based tests: `rebar3 as test eqc --testing_budget 120` compiles in the test profile and runs generated cases with a budget of 120, then `rebar3 as eqc eunit` runs the eunit suite in the eqc profile. The properties live in the eqc directory.

### Is riak_core still maintained?

The repository is not archived and the last push was on 2026-08-14 on the develop branch. The visible release tags are Riak KV releases from 2023, so riak_core is tagged as part of the Riak KV release train rather than on its own schedule.

### Where should I ask a riak_core question?

The README points to the Riak Users List for general Riak discussion and a separate Riak Core-specific mailing list for issues about Core but not Riak, plus the #riak channel on Freenode for real-time help. Bugs should be filed as issues against the repository.

## Sources

- [basho/riak_core on GitHub](https://github.com/basho/riak_core)
- [Issues](https://github.com/basho/riak_core/issues)
- [License: Apache-2.0](https://github.com/basho/riak_core/blob/develop/LICENSE)
- [README](https://github.com/basho/riak_core/blob/develop/README.md)
- [Releases](https://github.com/basho/riak_core/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/basho-riak-core