Installation

This page describes how to install and prepare Axon Server Proxy for use.

System requirements

Java runtime

When using the JAR distribution:

  • Java 21 or higher

  • Sufficient memory for your expected connection load (typically 256 MB - 1 GB)

Native binary

When using the native binary:

  • No Java runtime required

  • Compatible operating system (Linux, macOS, or Windows)

  • Sufficient memory for your expected connection load

Network requirements

  • Network connectivity to Axon Server admin nodes (default port 8124)

  • Inbound network access from your applications

  • Open port for the proxy to listen on (configurable)

Obtaining the proxy

Download the jar

Download the latest axon-server-proxy-<version>.jar from the releases page or your artifact repository.

# Example: Download from a repository
curl -O https://repo.axoniq.io/releases/io/axoniq/axon-server-proxy/<version>/axon-server-proxy-<version>.jar

Download native binary

Alternatively, download the native executable for your platform:

# Linux example
curl -O https://repo.axoniq.io/releases/io/axoniq/axon-server-proxy/<version>/axon-server-proxy-<version>-linux

# Make it executable
chmod +x axon-server-proxy-<version>-linux

Building from source

If you have access to the source code:

# Build JAR
mvn clean package

# Build native binary (requires GraalVM)
mvn -Pnative clean package

The JAR will be in target/axon-server-proxy-<version>.jar and the native binary in target/axon-server-proxy.

Prepare configuration

Before running the proxy, you need to prepare a configuration file. See Configuration for details.

Create a configuration file named proxy.properties in the working directory:

# Minimal configuration
proxy.servers=axonserver1:8124,axonserver2:8124
proxy.port=8124

Directory structure

A typical installation directory structure:

/opt/axon-server-proxy/
├── axon-server-proxy.jar (or native binary)
├── proxy.properties
└── logs/

Next steps