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: 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 2: Configure

Axon Server runs with adequate defaults. 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 need to add additional settings so machines know where to find each other. For more information, see the hosts and connections.

Step 3: AxonIQ Console (optional)

To unlock additional functionality, connect your Axon Server to AxonIQ Console.

Why connect to AxonIQ Console?

By connecting your Axon Server to AxonIQ Console, you will be able to:

  • Automatic initialization and clustering of Axon Server instances

  • Create multiple contexts in Axon Server to organize your applications

  • Inspect the status of your Axon Server through AxonIQ Console

  • Get deep insights into the status and performance of your applications when also connected to AxonIQ Console

  • Create multiple users and Access token in Axon Server

In contrast, without connecting to AxonIQ Console, you can:

  • Only have one context in Axon Server

  • Only have one user and one access key in Axon Server

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

Setting the 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 4: 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 5: Initialize

If you chose not to use AxonIQ Console, you will be prompted to initialize Axon Server when visiting the Axon Server dashboard. If you used AxonIQ Console, you can skip this step and Axon Server is immediately ready for use.

Complete installation prompt of Axon Server

Please choose the Start standalone node edition and click Complete. You are now ready to use Axon Server.

To initialize Axon Server as standalone node without a UI action, you can also set the AXONIQ_AXONSERVER_STANDALONE=true environment variable, or axoniq.axonserver.standalone=true in the axonserver.properties file.

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 Axon Server running, you can start using it with your Axon Framework applications. If you run on the same computer and the default ports, your Axon Framework application should be able to connect to Axon Server without any additional configuration.

If you modified the port or hostname, you need to configure Axon Framework to connect to Axon Server. For Spring Boot, you can do this by adding the following properties to your application.properties file:

axon.axonserver.servers=YOUR_HOST:YOUR_PORT