Docker Compose

Axon Server can be run using Docker Compose. This guide will show you how to set up an Axon Server cluster using Docker Compose.

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

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:

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

  axonserver-2:
    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-2
      - server_port=8025
      - axoniq_axonserver_port=8125
      - axoniq_axonserver_internal_port=8225
    ports:
      - '8025:8025'
      - '8125:8125'
      - '8225:8225'

  axonserver-3:
    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-3
      - server_port=8026
      - axoniq_axonserver_port=8126
      - axoniq_axonserver_internal_port=8226
    ports:
      - '8026:8026'
      - '8126:8126'
      - '8226:8226'

Both the name and internal-hostname are set to axonserver-1, axonserver-2, and axonserver-3 respectively. However, the hostname is set to localhost, so framework applications can connect to the Axon Server nodes without running in Docker. If you decide to add Axon Framework services to the Docker Compose file, set the hostname to the same value as the internal-hostname. For more information, see the hosts and connections guide.

This docker-compose will create three Axon Server nodes, each with a different port exposed for the dashboard, client, and cluster ports.

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.

Step 5: Run

To run the Axon Server cluster, execute the following command in the directory where the docker-compose.yaml file is located:

docker compose up

As you are starting three Axon Server nodes, this might take a bit of time. Once the nodes are up and running, you can access the Axon Server dashboard by navigating to port 8024, 8025 and 8026 of the machine in your browser for the first, second and third node respectively.

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=localhost:8124,localhost:8125,localhost:8126

If you are running your Axon Framework applications in Docker, you should replace localhost with the internal-hostname of the Axon Server nodes, and configure the hostname of the Axon Server nodes to the same value as the internal-hostname (see step 4, or the hosts and connections guide).