Download

This guide will walk you through the steps to run Axon Server Enterprise as a cluster of multiple nodes.

You can also use this guide to run all separate instances on a single machine for testing purposes. In that case, make sure you use different ports for each instance in step 2.

Prerequisites

Make sure you have the Java Runtime Environment (JRE) installed on the machines you want to install Axon Server. Axon Server requires at least Java 17.

If the following command returns a version number, you have Java installed:

java -version

Make sure the version of this command is at least 17.

Step 1: Download

Download Axon Server from our Download Page. After filling in your email address, you will receive the link in your email. If you would like, you can also receive notifications about future trainings.

Step 2: Extract

Extract the downloaded ZIP in the installation directory of your choice.

Step 2: Configure

Axon Server runs with adequate defaults. You can tweak this by editing the properties file that you extracted from the ZIP.

It’s recommended to configure at least the following:

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

axoniq.axonserver.hostname=myhost      # The hostname of the machine, which needs to be reachable from other machines

Step 3: Choose a clustering method

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 that is 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

You can find more information on the Cluster Template page of the reference guide.

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

To run Axon Server, execute the following command in the installation directory of every node:

java -jar axonserver.jar

Once you see the following log line, Axon Server is up and running:

io.axoniq.axonserver.AxonServer: Started AxonServer in 29.056 seconds

You can now access the Axon Server dashboard by navigating to hostname:8024 in your browser. If you customized the port, use the custom port instead.

Step 7: Daemon

Usually, you want to run Axon Server as a service on the host machine, so it starts on boot automatically. How this is done depends on the operating system you are using. Please refer to the documentation of your operating system for more information.

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.