Docker Compose

Docker has become a standard method of running software on your computer. Docker is a containerization platform that allows you to run applications in isolated environments. This makes it easy to run Axon Server on any machine that supports Docker.

Step 1: Verify installation

Make sure you have Docker and Docker Compose installed on your machine. You can verify this by running the following command:

docker version
docker compose version

You should see an output like:

Docker version 24.0.2, build cb74dfc
Docker Compose version v2.19.1

Older versions of docker uses a separate executable, called docker-compose. If you have an older version, you can use the docker-compose command instead of docker compose. You can check this by running docker-compose version.

If you cannot execute the commands successfully, we recommend following the docker setup guide.

Step 2: AxonIQ Console (optional)

By connecting your Axon Server to AxonIQ Console, you can unlock additional functionality.

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:

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

Step 3: Choose your image (optional)

AxonIQ provides ready-to-use Axon Server images. In this guide, we will use the latest-jdk-17 image. For a guide on all images, and how to make your own, see choosing and building your own Docker image. If you choose to do this, replace the image in the commands below.

Step 4: Create the file

We can now define the docker-compose.yaml that specifies how docker containers should be created.

Create a new folder, and put the following content in the docker-compose.yaml file:

With AxonIQ Console
Without AxonIQ Console

Please replace the YOUR_ACCESS_TOKEN text with the access key acquired in Step 2.

services:
  axonserver-1:
    image: axoniq/axonserver:latest-jdk-17
    pull_policy: always
    environment:
      - axoniq_console_authentication=YOUR_ACCESS_TOKEN
      - axoniq_axonserver_hostname=localhost
      - axoniq_axonserver_internal_hostname=axonserver-1
    ports:
      - '8024:8024'
      - '8124:8124'
      - '8224:8224'

services:
  axonserver-1:
    image: axoniq/axonserver:latest-jdk-17
    pull_policy: always
    environment:
      - axoniq_axonserver_hostname=localhost
      - axoniq_axonserver_internal_hostname=axonserver-1
    ports:
      - '8024:8024'
      - '8124:8124'
      - '8224:8224'

This docker-compose file is for demonstration purposes only. It is not suitable for production use. For example, the volumes are not persistent. You will lose data after running docker compose down. For more information, see the persistent Docker Compose data guide.

We set the hostname to localhost and the internal_hostname to axonserver-1. The hostname is communicated to clients to connect. Setting this to localhost ensures your applications running on your computer can easily connect. The internal_hostname is used to communicate between Axon Servers and to name itself.

For more information, see the hosts and connections guide.

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 add -e AXONIQ_AXONSERVER_STANDALONE=true to the Docker command.

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