Download

This guide will walk you through the steps to run Axon Server Professional 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 3.

Prerequisites

Make sure you have the Java Runtime Environment (JRE) installed on the machines where 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 the ZIP

Extract the downloaded ZIP in the installation directory of your choice on all machines. If you are running all nodes on a single machine, extract the ZIP in different directories.

Step 3: Configure

Axon Server runs with adequate defaults. However, you can customize it by editing the axonserver.properties file in the same directory as the JAR.

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.

Make sure that if you run multiple instances on a single machine, you use different ports for each instance.

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

Step 4: AxonIQ Console

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

Now you have the access token, you can set it in the axonserver.properties file. Add the following line to the file:

axoniq.console.authentication=<your-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:

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

Based on information in AxonIQ Console, the cluster will automatically form.

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

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.