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:

  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

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_axonserver_autocluster_first=axon-server-1
      - axoniq_axonserver_autocluster_contexts=_admin,default
      - 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'
    volumes:
      - ./axoniq-server.license:/axonserver/config/axoniq.license

  axonserver-2:
    image: axoniq/axonserver:latest-jdk-17
    pull_policy: always
    environment:
      - axoniq_axonserver_autocluster_first=axon-server-1
      - axoniq_axonserver_autocluster_contexts=_admin,default
      - 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'
    volumes:
      - ./axoniq-server.license:/axonserver/config/axoniq.license

  axonserver-3:
    image: axoniq/axonserver:latest-jdk-17
    pull_policy: always
    environment:
      - axoniq_axonserver_autocluster_first=axon-server-1
      - axoniq_axonserver_autocluster_contexts=_admin,default
      - 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'
    volumes:
      - ./axoniq-server.license:/axonserver/config/axoniq.license

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.

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.

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).