Ubuntu

This guide will walk you through the steps to run Axon Server Enterprise as a cluster of multiple nodes, while using the APT package manager built into Ubuntu.

The package currently only supports Ubuntu 22 (Jammy) and 24 (Focal). 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

Requirements: Before we can install Axon Server, we need to make sure that your system has the required dependencies. The following command will install the required dependencies.

sudo apt install ca-certificates lsb-release curl

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. 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

Repository: Next, we have to add the repository that houses our artifacts.

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

Install: We are ready for the installation!

sudo apt-get update
sudo apt-get install axonserver

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:

Auto-clustering: By defining which node is in charge of forming the cluster, it will automatically form
Axon Server Dashboard: By going into the Axon Server dashboard after Step 6, you can initialize the cluster manually
AxonIQ Console: it’s possible to add your Enterprise license to AxonIQ Console. This will automatically form a cluster of nodes.
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".

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:

Log into AxonIQ Console.
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
Go to the Axon Server page via the left menu
In the sidebar on the right, click "Manage access tokens" to open access token management
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=axon-server-1:8124,axon-server-2:8124,axon-server-3:8124

Please replace the axon-server-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.