Download

Downloading and executing a single instance of Axon Server is a simple process. This guide will walk you through the steps to download and run Axon Server on your local machine.

Prerequisites

Make sure you have the Java Runtime Environment (JRE) installed on your machine. 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.

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.

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 (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 5: 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

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

Step 6: 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