Skip to content

Aeron Cluster Quickstart

The cluster quickstart provides a skeleton for testing out and getting started with Aeron Cluster. It includes:

  • A cluster, with sample business logic within a replicated state machine
  • A REPL admin client that interacts with the cluster
  • A Docker Compose file that runs a three-node cluster
  • A Kubernetes deployment for a three-node cluster, delivered via a set of Kubernetes configuration files
  • A Cluster Backup application that maintains a replica of the state from the cluster.

Here is the quickstart showing Aeron Cluster's fully automatic fail-over in action:

Docker Demo

Getting started with Docker


The quickstart has been tested on Ubuntu 22.04 and macOS 13 machines. Both Java JDK 17 and Docker (with Docker Compose 2.x) are expected to be installed and correctly configured.

The steps to get everything up and running are as follows:

  1. Checkout the source code from GitHub
  2. Move to the aeron-io-samples folder, run ./gradlew to build the application components
  3. Start the quickstart by running docker compose up from the docker folder

With the cluster up and running, you can then shell into an admin container, and interact with the cluster and admin.


To do this, within the docker folder, run docker exec -it aeron-admin1-1 java -jar admin-uber.jar. The admin readme has details on the supported operations.


You can interact with either a leader or follower node, though some operations are only valid on the leader. To find the leader, either review the logs within docker and find the node that announced it is 'LEADER', or alternatively you can run the script which is within the docker folder.

Then, you can open a bash terminal using docker exec -it aeron-nodeX-1 java -jar admin-uber.jar where nodeX represents the leader node or follower node as required.

The cluster images have a number of tools within them, including those required to run cluster operations such as taking a snapshot. See the cluster readme for more info.

Cluster Backup

You can test recovering cluster nodes from a backup by creating data in the cluster, removing the cluster volumes, and then restoring them with the data from the Cluster Backup application.

The steps for doing this are described in the backup readme.

Suggested further reading

Once you've had time to see the quickstart cluster in action, you're ready to dig deeper into some key background concepts. These should be well understood before you deliver systems on Aeron Cluster.

  1. Aeron Cluster runs a replicated state machine on top of raft consensus
  2. You will need to define an application level protocol suitable for your application requirements
  3. Ensure that you understand what drives Aeron cluster performance
  4. Finally, consider your requirements and approach to high-availability