Getting Started

This page provides a quick introduction to using Axoniq Insights. It covers installation options, licensing, and connecting to Axon Server.

Prerequisites

  • Java 21 or later (for stand-alone installation)

  • Docker and Docker Compose (for Docker installation)

  • An Axon Server cluster (version 2024.1 or later) to connect to

  • An Axoniq Platform account or a local license file

Installation

Axoniq Insights can be deployed either as a Docker container or as a stand-alone Java application.

Docker

The recommended way to run Axoniq Insights is using Docker Compose. This approach bundles Insights with an Axon Server instance and handles networking between the services.

Running with Docker Compose

Create a docker-compose.yml file:

services:
  axonserver:
    image: docker.axoniq.io/axoniq/axonserver:latest
    hostname: axonserver-1
    environment:
      - AXONIQ_AXONSERVER_NAME=axonserver-1
      - AXONIQ_AXONSERVER_INTERNAL_HOSTNAME=axonserver-1
      - AXONIQ_AXONSERVER_HOSTNAME=localhost
      - AXONIQ_AXONSERVER_STANDALONE=true
    volumes:
      - axonserver-data:/axonserver/data
      - axonserver-events:/axonserver/events
    ports:
      - '8024:8024'
      - '8124:8124'

  insights:
    image: docker.axoniq.io/axoniq/axoniq-insights:latest
    hostname: insights-1
    environment:
      - insights.axonserver.routing-servers=axonserver-1:8124
    volumes:
      - insights-data:/insights/data
      - ./application.properties:/insights/config/application.properties
    ports:
      - '8080:8080'

volumes:
  axonserver-data:
  axonserver-events:
  insights-data:

Start the services:

docker compose up -d

The Axoniq Insights UI is available at http://localhost:8080 and Axon Server Dashboard at http://localhost:8024.

Running standalone Axoniq Insights

If you already have an Axon Server cluster running, you can run Insights on its own:

docker run -d \
  --name insights \
  -p 8080:8080 \
  -v insights-data:/insights/data \
  -v ./application.properties:/insights/config/application.properties \
  -e insights.axonserver.routing-servers=<axonserver-host>:8124 \
  docker.axoniq.io/axoniq/axoniq-insights:latest

Docker volumes

The Insights container uses two volumes:

Volume

Purpose

/insights/data

Persistent storage for DuckDB databases, event lake data, and the SQLite configuration database.

/insights/config

Configuration directory. Place your application.properties file here.

Stand-alone application

You can run Axoniq Insights directly as a Java application without Docker.

Download

Download the latest Insights executable JAR from the Axoniq download page or your Axoniq Platform account.

Running the application

java -jar insights.jar

By default, Insights stores its data in a data directory relative to the working directory. You can change this using the insights.dbdir property.

Configuration file

Create an application.properties file in the same directory as the JAR, or in a config subdirectory:

# Axon Server connection
insights.axonserver.routing-servers=localhost:8124

# Data directory
insights.dbdir=./data

# Default admin password (change this!)
insights.authorization.default-password=admin

Alternatively, you can pass properties as command-line arguments:

java -jar insights.jar \
  --insights.axonserver.routing-servers=myserver:8124 \
  --insights.dbdir=/var/insights/data

Or use environment variables (replace dots with underscores and use uppercase):

export INSIGHTS_AXONSERVER_ROUTING_SERVERS=myserver:8124
java -jar insights.jar

Licensing

Axoniq Insights requires a valid license to operate. There are two ways to configure your license.

Option 1: Axoniq Platform (recommended)

Connect Insights to Axoniq Platform to manage your license automatically. Axoniq Platform handles license provisioning, renewal, and monitoring of your Insights installation.

Add the following to your application.properties:

insights.platform.url=https://platform.axoniq.io
insights.platform.authentication=<your-platform-authentication-token>

You can obtain the authentication token from your Axoniq Platform account under the Insights section.

When connected to Axoniq Platform, Insights periodically validates its license and reports usage metrics. This is the recommended approach as it simplifies license management and provides access to platform features such as centralized monitoring.

Option 2: Local license file

For environments without internet access or when you prefer offline license management, you can install a license file directly.

Place the license file in the Insights data directory and configure the path:

insights.license.path=/insights/data/insights.license

When using Docker, mount the license file into the container:

docker run -d \
  --name insights \
  -p 8080:8080 \
  -v ./insights.license:/insights/data/insights.license \
  -v insights-data:/insights/data \
  docker.axoniq.io/axoniq/axoniq-insights:latest

Or in Docker Compose:

services:
  insights:
    image: docker.axoniq.io/axoniq/axoniq-insights:latest
    volumes:
      - ./insights.license:/insights/data/insights.license
      - insights-data:/insights/data

Contact Axoniq at sales@axoniq.io to obtain a license file.

Connecting to Axon Server

Axoniq Insights connects to one or more Axon Server nodes to stream events into its analytics engine. Configure the connection in your application.properties.

Single node

For a single Axon Server instance:

insights.axonserver.routing-servers=axonserver-host:8124

Port 8124 is the default Axon Server gRPC port used for client communication.

Cluster

To connect to an Axon Server cluster, provide a comma-separated list of routing servers. Insights uses these as initial contact points and discovers the full cluster topology automatically.

insights.axonserver.routing-servers=axonserver-1:8124,axonserver-2:8124,axonserver-3:8124

Listing multiple nodes ensures Insights can connect even if one node is temporarily unavailable.

Authentication

If your Axon Server requires an access control token, configure it using:

insights.axonserver.token=<your-axonserver-token>

Auto-subscribing to contexts

By default, Insights requires you to manually register which Axon Server contexts to monitor. To automatically subscribe to all available contexts:

insights.axonserver.auto-subscribe=true

When auto-subscribe is enabled, Insights discovers all contexts on the connected Axon Server cluster and begins streaming events from each one. New contexts are picked up automatically.

When auto-subscribe is disabled (the default), use the Insights UI or REST API to add contexts individually. This gives you fine-grained control over which contexts are monitored.

Verifying the connection

After starting Insights, open the UI at http://localhost:8080. Navigate to the Contexts page to verify that your Axon Server contexts are visible and events are being streamed.

You can also check the application logs for connection status:

Connected to Axon Server at axonserver-1:8124

Next steps