Linux

This guide will walk you through the steps to run Axon Server Enterprise as a cluster of multiple nodes, while using the package manager built into your Linux distribution: APT on Debian and Debian-based distributions (such as Ubuntu), or DNF/YUM on RHEL-based distributions.

The package currently supports Debian 12 (Bookworm) and 13 (Trixie), Ubuntu 22.04 (Jammy) and 24.04 (Noble Numbat), and RHEL 8, 9, and 10 (or compatible distributions, such as Rocky Linux and AlmaLinux). More distributions will be supported in the future.

Step 1: Pick a node

As we are installing a multi-node cluster, you need to pick one of the nodes to be the first node. Please follow the steps completely for this node first, and then repeat step 2 to 7 for the other nodes.

Step 2: Installation

Pick the tab that matches your distribution.

Requirements: Before we can install Axon Server, we need to make sure that your system has the required dependencies to manage the AxonServer package repository. The Debian instructions below apply to Debian and Debian-based distributions, such as Ubuntu, since Ubuntu uses the same APT package manager.

  • Debian

  • RHEL 9 / RHEL 10

  • RHEL 8

sudo apt install ca-certificates lsb-release curl
sudo dnf install -y dnf-utils
sudo yum install -y yum-utils

Signing key: All artifacts are signed with a private key, that the package manager will verify upon installation. It does this for you, so you can be sure the software you install is trusted.

  • Debian

  • RHEL 9 / RHEL 10

  • RHEL 8

The following command imports our public key for this verification.

sudo curl https://pkg.axoniq.io/axoniq.pub -o /etc/apt/trusted.gpg.d/axoniq.asc

The signing key is referenced automatically from the repository configuration file added in the next step, so no separate step is required here.

The signing key is referenced automatically from the repository configuration file added in the next step, so no separate step is required here.

Repository: Next, we have to add the repository that houses our artifacts. The repository provides two release channels for Axon Server and the Axon Server CLI:

  • main: the latest Axon Server and Axon Server CLI releases.

  • LTS: the latest Long-Term Support (LTS) stable releases.

You can pick either channel, and switch between them later on.

  • Debian

  • RHEL 9 / RHEL 10

  • RHEL 8

Choose the channel you want to use.

  • main

  • LTS

echo "deb [arch=all signed-by=/etc/apt/trusted.gpg.d/axoniq.asc] https://pkg.axoniq.io/apt $(. /etc/os-release && echo "$VERSION_CODENAME") main" | sudo tee /etc/apt/sources.list.d/axoniq.list > /dev/null
echo "deb [arch=all signed-by=/etc/apt/trusted.gpg.d/axoniq.asc] https://pkg.axoniq.io/apt $(. /etc/os-release && echo "$VERSION_CODENAME") LTS" | sudo tee /etc/apt/sources.list.d/axoniq.list > /dev/null

You can switch channels at any time by editing /etc/apt/sources.list.d/axoniq.list, replacing main with LTS (or vice versa), and running sudo apt-get update.

sudo yum-config-manager --add-repo https://pkg.axoniq.io/rhel/axonserver.repo

This repository file defines both channels as separate repositories, axonserver (main) and axonserver-lts (LTS), with the LTS channel enabled by default. To switch channels, enable one repository and disable the other:

Use the main channel
sudo dnf config-manager --set-enabled axonserver
sudo dnf config-manager --set-disabled axonserver-lts
Use the LTS channel (default)
sudo dnf config-manager --set-enabled axonserver-lts
sudo dnf config-manager --set-disabled axonserver
sudo yum-config-manager --add-repo https://pkg.axoniq.io/rhel/axonserver.repo

This repository file defines both channels as separate repositories, axonserver (main) and axonserver-lts (LTS), with the LTS channel enabled by default. To switch channels, enable one repository and disable the other:

Use the main channel
sudo yum-config-manager --enable axonserver
sudo yum-config-manager --disable axonserver-lts
Use the LTS channel (default)
sudo yum-config-manager --enable axonserver-lts
sudo yum-config-manager --disable axonserver
Repository file content (RHEL)

The repository configuration file (axonserver.repo) added above contains:

[axonserver]
name=Axonserver for RHEL/CentOS $releasever
baseurl=https://pkg.axoniq.io/rhel/$releasever
enabled=0
gpgcheck=1
gpgkey=https://pkg.axoniq.io/axoniq.pub

[axonserver-lts]
name=Axonserver LTS for RHEL/CentOS $releasever
baseurl=https://pkg.axoniq.io/rhel/$releasever/LTS
enabled=1
gpgcheck=1
gpgkey=https://pkg.axoniq.io/axoniq.pub

Install: We are ready for the installation!

  • Debian

  • RHEL 9 / RHEL 10

  • RHEL 8

sudo apt-get update
sudo apt-get install axonserver
sudo dnf -y install axonserver

To also install the Axon Server CLI:

sudo dnf -y install axonserver-cli
sudo yum -y install axonserver

To also install the Axon Server CLI:

sudo yum -y install axonserver-cli

Step 3: Configure

Axon Server runs with adequate defaults, where it will assume the hostname of the machine it is running on and run on the default ports. However, you can customize it by editing the /etc/axonserver/axonserver.properties file that was just installed on your machine.

The Axon Server dashboard runs on port 8024 by default, while the gRPC port for Axon Framework clients is 8124. You can tweak this by editing the properties:

server.port=8024                       # Dashboard port
axoniq.axonserver.port=8124            # gRPC port for Axon Framework clients
axoniq.axonserver.internal-port=8224   # gRPC port for cluster communication

A full list of properties can be found in the configuration reference.

If you want your Axon Server to be accessible from other machines, you might need to add additional settings so machines know where to find each other. For more information, see the hosts and connections.

Step 4: Define clustering

There are various ways to set up a cluster of Axon Server nodes:

  1. Auto-clustering: By defining which node is in charge of forming the cluster, it will automatically form

  2. Axon Server Dashboard: By going into the Axon Server dashboard after Step 6, you can initialize the cluster manually

  3. AxonIQ Console: it’s possible to add your Enterprise license to AxonIQ Console. This will automatically form a cluster of nodes.

  4. Cluster Template: By defining a cluster template, you can automatically form a cluster. While beyond the scope of this guide, you can find more information in the reference guide.

  • Auto-clustering

  • Axon Server Dashboard

  • AxonIQ Console

Setting up auto-clustering is straightforward. You define the node allowed to be the first to form the cluster, by defining it in the properties of all nodes. The first node will then create the cluster, and the other nodes will join it automatically.

Add the following properties to the axonserver.properties file of all nodes:

axoniq.axonserver.autocluster.first=axonserver-1:8224   # The hostname and port of the first node
axoniq.axonserver.autocluster.contexts=_admin,default   # The contexts that are automatically created

When accessing the Axon Server dashboard for the first time, you will be prompted to complete installation.

On the first node, choose "Start node and initialize multi-node cluster", and click "Complete".

Complete installation prompt of Axon Server

On the other nodes, choose "Join existing cluster", fill in the host address and port of the first node, and click "Complete".

Complete installation prompt of Axon Server

Repeating this for all nodes will form a cluster.

Please ask your AxonIQ representative to add your Enterprise license to AxonIQ Console. Once you have done that, you can acquire the access token from the console and add it to the properties file of all nodes, as such:

axoniq.console.authentication=YOUR_ACCESS_TOKEN
Obtaining AxonIQ Console access token

You can obtain the console access token by following these steps:

  1. Log into AxonIQ Console.

  2. If this is your first time logging in, you will be prompted to enter your name. After this, your own Workspace will be created automatically

  3. Go to the Axon Server page via the left menu

  4. In the sidebar on the right, click "Manage access tokens" to open access token management

  5. Click the button under "Show Token" to reveal your unique access token

Step 5: Configure ports

Depending on your cloud environment or machine configuration, you might need to open the ports in the firewall. Please refer to the documentation of your cloud provider or operating system for more information.

The following ports need to be accessible:

  • The dashboard port (default: 8024) from where you want to access the Axon Server dashboard.

  • The gRPC port for Axon Framework clients (default: 8124) from where your Axon Framework applications connect to Axon Server.

  • The gRPC port for cluster communication (default: 8224) for communication between Axon Server nodes in a cluster. This port does not need to be accessible from the outside.

During operations of Axon Server, you might want to connect to individual nodes in the cluster. We discourage any form of load-balancing for any port of Axon Server, as it might lead to unexpected behavior.

Step 6: Run Axon Server

You can now start Axon Server! You can use Systemd if your system uses it:

sudo systemctl start axonserver

Or, alternatively, you can run it manually:

sudo -i -u axonserver
cd /var/lib/axonserver/
sh start-axonserver.sh

Step 7: Verify installation

Once the Axon Server instance has booted up, you should be able to access the dashboard by navigating to http://HOSTNAME:8024 in your browser, provided the firewall allows it. You can also verify that Axon Server started up correctly by checking AxonIQ console. You can see an example of a healthy cluster in the image below.

Axon Server cluster healthy in AxonIQ console

If this is only the first node you are connecting, you will only see one node in the cluster.

Step 8: Repeat for remaining nodes

To connect the other nodes to the cluster, repeat steps 2 to 6 for each node until all nodes are correctly up and running.

Next steps

The steps in this guide do not take into account any security, authentication or authorization. If you would like to set this up, please follow the Securing Axon Server guide.

Ready to connect

Now that you have your Axon Servers running, you can start using it with your Axon Framework applications.

Your Axon Framework applications should list all nodes of Axon Server in their properties file, so that if one node goes down, the application can still connect to the other nodes initially.

axon.axonserver.servers=axonserver-1:8124,axon-server-2:8124,axon-server-3:8124

Please replace the axonserver-1, axon-server-2, and axon-server-3 with the hostnames of your Axon Server nodes. And replace 8124 with the gRPC port of your Axon Server nodes if you customized this.