Ubuntu

You can install Axon Server through the APT package manager integrated into Ubuntu. Using this method will make it simple to update using commands as well.

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: AxonIQ Console

The AxonIQ Professional edition of Axon Server will retrieve its license from AxonIQ Console using an access token. In addition, it will register its connection information so that other nodes can automatically find the cluster.

Obtaining the 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

Setting the access token

Now you have the access token, you can set it in the /etc/axonserver/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 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.