### Start Axon Server Instance

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/local-installation

This command starts an Axon Server instance using default ports. It's essential for provisioning uninitialized nodes for a cluster. The server exposes HTTP for the Management UI and REST API, and gRPC ports for client connections and internal cluster communication.

```bash
./axonserver.jar
```

--------------------------------

### Axon Server Cluster Template Configuration Example (YAML)

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/clustering/cluster-basics

An example of a basic Axon Server cluster template configuration in YAML format. This defines replication groups for admin and default contexts, specifying primary nodes for each. It also includes placeholders for applications and users.

```yaml
axoniq:
  axonserver:
    cluster-template:
      first: internal-hostname:internal-port
      replicationGroups:
      - name: _admin
        roles:
        - node: axonserver-1
          role: PRIMARY
        - node: axonserver-2
          role: PRIMARY
        - node: axonserver-3
          role: PRIMARY
        contexts:
        - name: _admin
      - name: default
        roles:
        - node: axonserver-2
          role: PRIMARY
        - node: axonserver-3
          role: PRIMARY
        - node: axonserver-1
          role: PRIMARY
        contexts:
        - name: default
          dcbContext: false
      applications: []
      users: []

```

--------------------------------

### Starting Axon Server with Docker Compose

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/docker-k8s

This command initiates the Axon Server cluster defined in the `docker-compose.yml` file. It starts all the defined services and networks.

```bash
$ docker-compose up

```

--------------------------------

### Dockerfile for Axon Server EE

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/docker-k8s

A multi-stage Dockerfile to build a custom Axon Server EE image. It starts from a base Java image, sets up directories, copies the Axon Server JAR and properties, defines volume mounts, exposes ports, and sets the entrypoint command to start Axon Server.

```dockerfile
FROM eclipse-temurin:17-focal
RUN mkdir -p /axonserver/config /axonserver/data /axonserver/events /axonserver/log /axonserver/exts

COPY axonserver.jar axonserver.properties /axonserver/

WORKDIR /axonserver

VOLUME [ "/axonserver/config", "/axonserver/data", "/axonserver/events", "/axonserver/log", "/axonserver/exts", "/axonserver/plugins"  ]
EXPOSE 8024/tcp 8124/tcp 8224/tcp

ENTRYPOINT [ "java", "-jar", "./axonserver.jar" ]
```

--------------------------------

### Install Axon Server OAuth Extension

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/security/access-control-oauth2

This snippet demonstrates how to install the Axon Server OAuth Extension by unpacking the distribution ZIP file into the 'exts' subdirectory of the Axon Server working directory. It shows the creation of the 'exts' directory and the unzipping command, listing the JAR files that are extracted.

```bash
mkdir exts
unzip -j axon-server-extension-oauth-4.5-SNAPSHOT-bin.zip -d exts

```

--------------------------------

### Configure Axon Server Auto-clustering

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/local-installation

Configuration settings in `axonserver.properties` file to enable automatic cluster setup. `axoniq.axonserver.autocluster.first` specifies a known admin node, and `axoniq.axonserver.autocluster.contexts` defines contexts to join or create.

```properties
# Example properties for auto-clustering
axoniq.axonserver.autocluster.first=admin-node-hostname
axoniq.axonserver.autocluster.contexts=_admin,default
```

--------------------------------

### Configure Axon Server Standalone Mode

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/local-installation

This configuration sets up Axon Server to run in a standalone mode with a single context named 'default'. It's a simple setup for a single node. This property should be added to `axonserver.properties` or as an environment property.

```properties
axoniq.axonserver.standalone=true
```

--------------------------------

### Initialize Axon Server Cluster

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/local-installation

Steps to initialize a cluster by designating one node as the admin node using the `axonserver-cli.jar`.

```APIDOC
## Initial Node Initialization

To convert a group of uninitialized Axon Server nodes into a cluster, you need to select any one of them as a starting point and run the `init-cluster` command on it using the command-line utility (`axonserver-cli.jar`).

### Command

```bash
$ ./axonserver-cli.jar init-cluster
```

#### Description

This command designates the current node as the _admin node_ of the Axon Server cluster. It also creates the `_admin` context for cluster configuration and a `default` context for event storage and message routing.

#### Response

After successful execution, the `/v1/public/me` REST API call to the admin node will reflect its new role and cluster status.

##### Example Response for Admin Node
```json
{
  "authentication": false,
  "clustered": true,
  "ssl": false,
  "adminNode": true,
  "developmentMode": false,
  "storageContextNames": [ "default" ],
  "contextNames": [ "_admin", "default" ],
  "name": "axonserver-1",
  "hostName": "axonserver-1",
  "internalHostName": "axonserver-1",
  "grpcInternalPort": 8224,
  "grpcPort": 8124,
  "httpPort": 8024
}
```

The UI console will also display the newly initialized admin node.
```

--------------------------------

### Configure Axon Server Standalone DCB Mode

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/local-installation

This configuration starts Axon Server in standalone mode with a Disaster Recovery Context (DCB). It's an alternative to the standard standalone mode for specific recovery scenarios. This property should be added to `axonserver.properties` or as an environment property.

```properties
axoniq.axonserver.standalone-dcb=true
```

--------------------------------

### Automatic Cluster Initialization Configuration

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/clustering/cluster-basics

Configure Axon Server to automatically initialize cluster settings by specifying the first node and contexts. This bypasses manual member registration. Properties are applied on a clean start only.

```properties
axoniq.axonserver.autocluster.first=internal-hostname:internal-port
axoniq.axonserver.autocluster.contexts=context1,context2
```

--------------------------------

### Start and Apply Event Transformation in Java

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/administration/event-transformation

This code snippet demonstrates how to initiate a new event transformation with a description, apply a transformer to it, and then start applying the transformation. It relies on Axon Server's Java API, specifically the `EventTransformationChannel` and `ActiveTransformation` classes. The methods return `CompletableFuture`s, allowing for asynchronous composition.

```java
connection.eventTransformationChannel()
          .newTransformation("My transformation description")
          .thenCompose(activeTransformation -> activeTransformation.transform(transformer))
          .thenCompose(ActiveTransformation::startApplying);
```

--------------------------------

### GET /actuator/info

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/administration/monitoring/actuator-endpoints

The `/actuator/info` endpoint provides basic information about Axon Server, such as its name, description, and version. This is useful for liveness and readiness probes.

```APIDOC
## GET /actuator/info

### Description

Retrieves basic information about the Axon Server instance.

### Method

GET

### Endpoint

`/actuator/info`

### Parameters

None.

### Request Example

```bash
curl http://<axonserver-ip>:8024/actuator/info
```

### Response

#### Success Response (200)

Returns a JSON object with basic server attributes.

- **name** (string) - The name of the Axon Server instance.
- **description** (string) - A description of the Axon Server instance.
- **version** (string) - The version of Axon Server.

#### Response Example

```json
{
  "name": "AxonServer",
  "description": "Axon Server EE",
  "version": "4.7.1"
}
```
```

--------------------------------

### Get Cluster Configuration

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/local-installation

Retrieves the complete details of the Axon Server cluster configuration. This API should be called against the admin node.

```APIDOC
## Get Cluster Configuration

### Description
This REST API operation retrieves the complete details of the Axon Server cluster configuration. It provides information about the leader, available contexts, nodes within the cluster, and the roles each node plays in specific contexts.

### Method
GET

### Endpoint
`/v1/public/context`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET http://<admin_node_hostname>:8024/v1/public/context
```

### Response
#### Success Response (200)
Returns an array of context configurations. Each context object includes:
- **metaData** (object) - Additional metadata for the context.
- **nodes** (array<string>) - A list of hostnames of nodes participating in this context.
- **leader** (string) - The hostname of the leader node for this context.
- **pendingSince** (integer) - Timestamp indicating when a change was pending.
- **changePending** (boolean) - Indicates if a cluster configuration change is pending.
- **roles** (array<object>) - An array detailing the roles of each node within the context. Each role object has:
    - **role** (string) - The role of the node (e.g., "PRIMARY").
    - **node** (string) - The hostname of the node.
- **context** (string) - The name of the context.

#### Response Example
```json
[
  {
    "metaData": {},
    "nodes": ["axonserver-1", "axonserver-2"],
    "leader": "axonserver-1",
    "pendingSince": 0,
    "changePending": false,
    "roles": [
      { "role": "PRIMARY", "node": "axonserver-1" },
      { "role": "PRIMARY", "node": "axonserver-2" }
    ],
    "context": "_admin"
  },
  {
    "metaData": {},
    "nodes": ["axonserver-1", "axonserver-2"],
    "leader": "axonserver-1",
    "pendingSince": 0,
    "changePending": false,
    "roles": [
      { "role": "PRIMARY", "node": "axonserver-1" },
      { "role": "PRIMARY", "node": "axonserver-2" }
    ],
    "context": "default"
  }
]
```
```

--------------------------------

### GET /v2/aggregates/{aggregateId}/snapshots

Source: https://docs.axoniq.io/axon-server-reference/development/_attachments/integration-openapi

Retrieves snapshots for a specific aggregate from Axon Server. Snapshots are used to optimize event sourcing by providing a starting point for aggregate state.

```APIDOC
## GET /v2/aggregates/{aggregateId}/snapshots

### Description
Retrieves snapshots for a specific aggregate from Axon Server. Snapshots are used to optimize event sourcing by providing a starting point for aggregate state.

### Method
GET

### Endpoint
/v2/aggregates/{aggregateId}/snapshots

### Parameters
#### Path Parameters
- **aggregateId** (string) - Required - The unique identifier of the aggregate.

#### Query Parameters
- **context** (string) - Required - The name of the context.
- **minSequence** (integer) - Optional - The minimum sequence number (inclusive) for snapshots. Defaults to 0.
- **maxResults** (integer) - Optional - The maximum number of snapshots to return. Defaults to 1.

### Response
#### Success Response (200)
- **(array of Snapshot)** - An array of snapshot objects.

#### Error Responses
- **403** (string) - Forbidden
- **400** (string) - Bad Request
```

--------------------------------

### Get Node Status

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/local-installation

Retrieves the status and configuration details of the current Axon Server node. This can be used to verify if a node has joined the cluster and its current settings.

```APIDOC
## Get Node Status

### Description
This REST API operation retrieves the status and configuration details of the current Axon Server node. It returns information such as authentication status, clustering status, SSL configuration, and node-specific details like name, hostnames, and ports.

### Method
GET

### Endpoint
`/v1/public/me`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET http://<node_hostname>:8024/v1/public/me
```

### Response
#### Success Response (200)
- **authentication** (boolean) - Indicates if authentication is enabled.
- **clustered** (boolean) - Indicates if the node is part of a cluster.
- **ssl** (boolean) - Indicates if SSL is enabled.
- **adminNode** (boolean) - Indicates if the node is an admin node.
- **developmentMode** (boolean) - Indicates if the node is in development mode.
- **storageContextNames** (array<string>) - A list of storage context names.
- **contextNames** (array<string>) - A list of available context names.
- **name** (string) - The name of the Axon Server node.
- **hostName** (string) - The hostname of the Axon Server node.
- **internalHostName** (string) - The internal hostname used for cluster communication.
- **grpcInternalPort** (integer) - The internal gRPC port for cluster communication.
- **grpcPort** (integer) - The external gRPC port.
- **httpPort** (integer) - The HTTP port.

#### Response Example
```json
{
  "authentication": false,
  "clustered": true,
  "ssl": false,
  "adminNode": true,
  "developmentMode": false,
  "storageContextNames": [ "default" ],
  "contextNames": [ "_admin", "default" ],
  "name": "axonserver-2",
  "hostName": "axonserver-2",
  "internalHostName": "axonserver-2",
  "grpcInternalPort": 8224,
  "grpcPort": 8124,
  "httpPort": 8024
}
```
```

--------------------------------

### Provision Axon Server Nodes

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/local-installation

Instructions on how to provision uninitialized Axon Server nodes to form a cluster. This involves extracting the Axon Server zip file on each node and running the Axon Server JAR.

```APIDOC
## Provision Axon Server Nodes

To get started with setting up a cluster, you need to provision a set of _*uninitialized*_ nodes. Extract the Zip on all the nodes that you want to be part of the cluster. The nodes will need to run on separate ports if run on the same machine.

From the location where the files have been extracted, please run the following command:

```bash
$ ./axonserver.jar
     _                     ____
    / \   __  _____  _ __ / ___|  ___ _ ____   _____ _ __
   / _ \  \ \/ / _ \| '_ \\___ \ / _ \ '__\ \ / / _ \ '__|
  / ___ \  >  < (_) | | | |___) |  __/ |   \ V /  __/ |
 /_/   \_\/_/\_\___/|_| |_|____/ \___|_|    \_/ \___|_|
                                               Powered by AxonIQ
```

This will start Axon Server using the default ports - 8024 for HTTP / 8124 and 8224 for gRPC. The HTTP port is used to serve the Management UI and the REST API provided by Axon Server. The gRPC 8124 port is used by Axon Framework client applications to connect to Axon Server, while the gRPC 8224 port is used for internal communication between the nodes of an Axon Server cluster.

The management UI can be opened at `http://localhost:8024` while the REST API is accessible at `http://localhost:8024/v1`.

### GET /v1/public/me

This REST API operation provides configuration details for a running instance of Axon Server.

#### Method
GET

#### Endpoint
`/v1/public/me`

#### Response
##### Success Response (200)
- **authentication** (boolean) - Indicates if authentication is enabled.
- **clustered** (boolean) - Indicates if the node is part of a cluster.
- **ssl** (boolean) - Indicates if SSL is enabled.
- **adminNode** (boolean) - Indicates if this node is the admin node.
- **developmentMode** (boolean) - Indicates if the server is running in development mode.
- **storageContextNames** (array) - List of storage context names.
- **contextNames** (array) - List of context names.
- **internalHostName** (string) - The internal hostname of the node.
- **grpcInternalPort** (integer) - The internal gRPC port.
- **grpcPort** (integer) - The gRPC port for client connections.
- **httpPort** (integer) - The HTTP port for management UI and REST API.
- **name** (string) - The name of the node.
- **hostName** (string) - The hostname of the node.

##### Response Example
```json
{
  "authentication": false,
  "clustered": true,
  "ssl": false,
  "adminNode": false,
  "developmentMode": false,
  "storageContextNames": [],
  "contextNames": [],
  "internalHostName": "${hostname}",
  "grpcInternalPort": 8224,
  "grpcPort": 8124,
  "httpPort": 8024,
  "name": "${hostname}",
  "hostName": "${hostname}"
}
```

Repeat this for every node that needs to be a part of the cluster.

**Summary of Provisioning Steps:**
* Extract the Axon Server zip (along with the license file) on each node.
* Start each Axon Server instance.
* Ensure that the gRPC ports are accessible between nodes.
* Use the `/v1/public/me` REST API to verify configuration.
* Customize configuration using `axonserver.properties` if needed.
```

--------------------------------

### Get Event Handler - API Request Example

Source: https://docs.axoniq.io/axon-server-reference/development/openapi/integration-api

Fetches details for a specific event handler on an integration endpoint. Requires endpoint and handler identifiers, and supports an optional context parameter.

```HTTP
GET /v2/endpoints/{endpoint}/eventHandlers/{handler}?context=defaultContext
```

--------------------------------

### Get Command Handler - API Request Example

Source: https://docs.axoniq.io/axon-server-reference/development/openapi/integration-api

Retrieves details of a specific command handler for an integration endpoint. Requires endpoint and handler identifiers. Supports optional context parameter.

```HTTP
GET /v2/endpoints/{endpoint}/commandHandlers/{handler}?context=defaultContext
```

--------------------------------

### View Axon Server Metrics (Axon Server CLI)

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/administration/admin-configuration/command-line-interface

Displays an overview of all Axon-specific metrics available on the Axon Server.

```shell
$ java -jar axonserver-cli.jar metrics
```

--------------------------------

### Get Event Handler - Response Body Example

Source: https://docs.axoniq.io/axon-server-reference/development/openapi/integration-api

Illustrates the structure of a successful response when retrieving an event handler's configuration, including its name, batch size, filter, and event URL.

```JSON
{
  "name": "string",
  "batchSize": 0,
  "filter": "string",
  "sequencingPolicy": "string",
  "sequencingPolicyParameters": "string",
  "segments": 0,
  "startPosition": "string",
  "eventUrl": "string"
}
```

--------------------------------

### List Applications and Roles (Axon Server CLI)

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/administration/admin-configuration/command-line-interface

Lists all registered applications along with their roles per context. Supports JSON output.

```shell
$ java -jar axonserver-cli.jar applications [-o json]
```

--------------------------------

### Activate Plugin via Command Line

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/administration/plugins

This command activates a specific plugin for a given context in Axon Server. It requires the plugin name, version, and context to be provided as parameters.

```bash
java -jar axonserver-cli.jar activate-plugin -p <plugin> -v <version> -c <context>
```

--------------------------------

### Configure Plugin Properties via Command Line Parameters

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/administration/plugins

This command configures plugin properties using command-line parameters. It specifies the plugin, version, context, and then provides key-value pairs for the properties defined in the `ConfigurationListener`. The format is `-prop <listenerName>:<propertyName>=<value>`.

```bash
java -jar axonserver-cli.jar upload-plugin -p <plugin> -v <version> -c <context> -prop myname:mypropid1=myvalue -prop myname:mypropid2=myvalue2
```

--------------------------------

### Axon Server Cluster Template Configuration (YAML)

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/clustering/cluster-basics

Define Axon Server cluster configuration, including replication groups, contexts, metadata, applications, and users, using a YAML file. This template is applied only once on the first clean startup.

```yaml
# Example YAML for Cluster Template
replication_groups:
  - name: "default"
    {-# MINIMUN_NUMBER_OF_INSTANCES = 1 #-}
    {-# MAXIMUN_NUMBER_OF_INSTANCES = 3 #-}
contexts:
  - name: "default"
    replication_group: "default"
users:
  - username: "user"
    password: "password"
    roles:
      - "ADMINISTRATOR"
```

--------------------------------

### Build Docker Image for Axon Server EE

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/docker-k8s

Command to build the Docker image using the created Dockerfile and associated files. This command tags the image with a specified repository and version.

```bash
$ docker build --tag my-repository/axonserver:2024.2.3
```

--------------------------------

### Get Axon Server Cluster Configuration via REST API

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/local-installation

Retrieves the complete cluster configuration using the /v1/public/context REST API endpoint on the admin node. Provides details about nodes, leader, contexts, and roles within the cluster. The response is a JSON array of context configurations.

```json
[
  {
    "metaData": {},
    "nodes": ["axonserver-1", "axonserver-2"],
    "leader": "axonserver-1",
    "pendingSince": 0,
    "changePending": false,
    "roles": [
      { "role": "PRIMARY", "node": "axonserver-1" },
      { "role": "PRIMARY", "node": "axonserver-2" }
    ],
    "context": "_admin"
  },
  {
    "metaData": {},
    "nodes": ["axonserver-1", "axonserver-2"],
    "leader": "axonserver-1",
    "pendingSince": 0,
    "changePending": false,
    "roles": [
      { "role": "PRIMARY", "node": "axonserver-1" },
      { "role": "PRIMARY", "node": "axonserver-2" }
    ],
    "context": "default"
  }
]
```

--------------------------------

### Initialize Axon Server Cluster

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/local-installation

This command initializes a group of uninitialized Axon Server nodes into a cluster by designating one node as the admin node. It uses the `axonserver-cli.jar` utility and creates necessary contexts for cluster configuration and event storage.

```bash
./axonserver-cli.jar init-cluster
```

--------------------------------

### Get Axon Server Node Status via REST API

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/local-installation

Retrieves the status and configuration details of an Axon Server node using the /v1/public/me REST API endpoint. Useful for verifying node information and cluster participation. Returns a JSON object with details like authentication status, clustering status, and network ports.

```json
{
  "authentication": false,
  "clustered": true,
  "ssl": false,
  "adminNode": true,
  "developmentMode": false,
  "storageContextNames": [ "default" ],
  "contextNames": [ "_admin", "default" ],
  "name": "axonserver-2",
  "hostName": "axonserver-2",
  "internalHostName": "axonserver-2",
  "grpcInternalPort": 8224,
  "grpcPort": 8124,
  "httpPort": 8024
}
```

--------------------------------

### Deploy Axon Server StatefulSet Configuration

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/docker-k8s

This YAML defines the StatefulSet for Axon Server, specifying security context, volume mounts, readiness and liveness probes, and volume configurations. It ensures Axon Server instances are deployed with persistent storage for data, events, and logs, along with necessary configuration and license volumes.

```yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: axonserver
  labels:
    app: axonserver
spec:
  serviceName: axonserver
  replicas: 1
  selector:
    matchLabels:
      app: axonserver
  template:
    metadata:
      labels:
        app: axonserver
    spec:
      securityContext:
        runAsUser: 1001
        fsGroup: 1001
      containers:
      - name: axonserver
        image: docker.axoniq.io/axoniq/axonserver:latest-dev-nonroot
        imagePullPolicy: IfNotPresent
        ports:
        - name: grpc
          containerPort: 8124
          protocol: TCP
        - name: gui
          containerPort: 8024
          protocol: TCP
        env:
        - name: AXONIQ_LICENSE
          value: "/axonserver/license/axoniq.license"
        volumeMounts:
        - name: data
          mountPath: /axonserver/data
        - name: events
          mountPath: /axonserver/events
        - name: log
          mountPath: /axonserver/log
        - name: config
          mountPath: /axonserver/config
          readOnly: true
        - name: system-token
          mountPath: /axonserver/security
          readOnly: true
        - name: license
          mountPath: /axonserver/license
          readOnly: true
        readinessProbe:
          httpGet:
            path: /actuator/info
            port: 8024
          initialDelaySeconds: 5
          periodSeconds: 5
          timeoutSeconds: 1
          failureThreshold: 30
        livenessProbe:
          httpGet:
            path: /actuator/info
            port: 8024
          initialDelaySeconds: 5
          periodSeconds: 10
          successThreshold: 1
          failureThreshold: 3
      volumes:
        - name: config
          configMap:
            name: axonserver-properties
        - name: system-token
          secret:
            secretName: axonserver-token
        - name: license
          secret:
            secretName: axonserver-license
  volumeClaimTemplates:
    - metadata:
        name: events
      spec:
        accessModes: [ "ReadWriteOnce" ]
        resources:
          requests:
            storage: 5Gi
    - metadata:
        name: log
      spec:
        accessModes: [ "ReadWriteOnce" ]
        resources:
          requests:
            storage: 1Gi
    - metadata:
        name: data
      spec:
        accessModes: [ "ReadWriteOnce" ]
        resources:
          requests:
            storage: 1Gi

```

--------------------------------

### Axon Server Configuration Details (Uninitialized Node)

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/local-installation

This JSON object represents the configuration details of an uninitialized Axon Server instance, retrieved via the REST API at `/v1/public/me`. It shows default settings for ports, authentication, clustering, and SSL.

```json
{
  "authentication": false,
  "clustered": true,
  "ssl": false,
  "adminNode": false,
  "developmentMode": false,
  "storageContextNames": [],
  "contextNames": [],
  "internalHostName": ${hostname},
  "grpcInternalPort": 8224,
  "grpcPort": 8124,
  "httpPort": 8024,
  "name": ${hostname},
  "hostName": ${hostname}
}
```

--------------------------------

### Upload Plugin via Command-Line (Axon Server CLI)

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/administration/plugins

This command uploads an Axon Server plugin to the server using the command-line interface. Ensure the plugin file is specified with the '-f' flag. Default limits for file and request size can be adjusted in 'axonserver.properties'.

```bash
java -jar axonserver-cli.jar upload-plugin -f [file]
```

--------------------------------

### GET /v2/endpoints

Source: https://docs.axoniq.io/axon-server-reference/development/_attachments/integration-openapi

Retrieves a list of all integration endpoints, including their associated handlers and connection status.

```APIDOC
## GET /v2/endpoints

### Description
Retrieves all integration endpoints with their handlers and connection status.

### Method
GET

### Endpoint
/v2/endpoints

### Parameters
#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **Array of EndpointOverview objects** - A list of integration endpoints.

#### Response Example
[
  {
    "id": "string (uuid)",
    "name": "string",
    "handler": "string",
    "connectionStatus": "string (enum: CONNECTED, DISCONNECTED, UNKNOWN)"
  }
]

#### Error Responses
- **403 Forbidden**: If the user lacks permission.
- **400 Bad Request**: If the request is malformed.
```

--------------------------------

### Start Event Store Backup (DCB Context)

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/administration/backups

Initiates an event store backup for a specified context. This is a 'push' style backup where Axon Server sends data to a designated location. It returns an ID to track the backup progress.

```APIDOC
## POST /v2/backup

### Description
Starts an event store backup for a specified context and location. Returns a backup ID to track progress.

### Method
POST

### Endpoint
/v2/backup

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **context** (string) - Required - The name of the context to back up.
- **location** (string) - Required - The destination path for the backup.

### Request Example
```bash
curl -X 'POST' \
  'http://127.0.0.1:8024/v2/backup' \
  -H 'Content-Type: application/json' \
  -d '{
    "context": "billing",
    "location": "/mnt/backups"
  }'
```

### Response
#### Success Response (200)
- **id** (string) - A unique identifier for the backup operation.

#### Response Example
```json
{
  "id": "1a39b69c-0ca4-42cd-b0ed-22ee3727402a"
}
```
```

--------------------------------

### Run Axon Server EE Standalone Docker Instance

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/docker-k8s

Command to run a standalone instance of the Axon Server EE Docker image. It sets the `axoniq.axonserver.standalone` property via environment variables and maps ports for external access.

```bash
$ docker run -dit -e axoniq.axonserver.standalone=true -p 8024:8024 -p 8124:8124 my-repository/axonserver:2024.2.3
```

--------------------------------

### GET /v2/aggregates/{aggregateId}/eventsPaged

Source: https://docs.axoniq.io/axon-server-reference/development/openapi/integration-api

Retrieves events for a specific aggregate in a paginated manner.

```APIDOC
## GET /v2/aggregates/{aggregateId}/eventsPaged

### Description
Retrieves events for a specific aggregate in a paginated manner.

### Method
GET

### Endpoint
/v2/aggregates/{aggregateId}/eventsPaged

### Parameters
#### Path Parameters
- **aggregateId** (string) - Required

#### Query Parameters
- **context** (string) - Required
- **pageOffset** (integer) - Required
- **pageSize** (integer) - Required

### Response
#### Success Response (200)
OK

#### Error Response (400)
Bad Request

#### Error Response (403)
Forbidden

#### Response Example (200)
```json
{
  "numberOfPage": 0,
  "size": 0,
  "isLast": true,
  "events": [
    {
      "id": "string",
      "aggregateId": "string",
      "aggregateType": "string",
      "sequenceNumber": 0,
      "payloadRevision": "string",
      "payloadType": "string",
      "payload": { },
      "metaData": {
        "property1": "string",
        "property2": "string"
      },
      "dateTime": "2019-08-24T14:15:22Z"
    }
  ]
}
```
```

--------------------------------

### List Axon Server Contexts (CLI)

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/administration/admin-configuration/command-line-interface

Lists all contexts and their assigned nodes, including the master and member nodes. Supports JSON output for easier parsing. No external dependencies beyond the Axon Server CLI JAR.

```bash
java -jar axonserver-cli.jar contexts [-o json]
```

--------------------------------

### GET /v2/endpoints/{endpoint}/queryHandlers/{handler}

Source: https://docs.axoniq.io/axon-server-reference/development/openapi/integration-api

Retrieves a specific query handler for an integration endpoint.

```APIDOC
## GET /v2/endpoints/{endpoint}/queryHandlers/{handler}

### Description
Retrieves a specific query handler for an integration endpoint.

### Method
GET

### Endpoint
/v2/endpoints/{endpoint}/queryHandlers/{handler}

### Parameters
#### Path Parameters
- **endpoint** (string) - Required
- **handler** (string) - Required

#### Query Parameters
- **context** (string) - Required

### Response
#### Success Response (200)
OK

#### Error Response (400)

#### Error Response (403)
Forbidden

#### Error Response (404)
Not Found

#### Error Response (500)
Internal Server Error

#### Response Example (200)
```json
{
  "name": "string",
  "queryUrl": "string"
}
```
```

--------------------------------

### Axon Server Configuration Details (Initialized Admin Node)

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/installation/local-installation

This JSON object represents the configuration details of an initialized Axon Server admin node, retrieved via the REST API at `/v1/public/me`. It indicates that the node is now the admin node and has created the `_admin` and `default` contexts.

```json
{
  "authentication": false,
  "clustered": true,
  "ssl": false,
  "adminNode": true,
  "developmentMode": false,
  "storageContextNames": [ "default" ],
  "contextNames": [ "_admin", "default" ],
  "name": "axonserver-1",
  "hostName": "axonserver-1",
  "internalHostName": "axonserver-1",
  "grpcInternalPort": 8224,
  "grpcPort": 8124,
  "httpPort": 8024
}
```

--------------------------------

### GET /v2/aggregates/{aggregateId}/events

Source: https://docs.axoniq.io/axon-server-reference/development/_attachments/integration-openapi

Retrieves events for a specific aggregate from Axon Server. This allows you to replay the event history of an aggregate.

```APIDOC
## GET /v2/aggregates/{aggregateId}/events

### Description
Retrieves events for a specific aggregate from Axon Server. This allows you to replay the event history of an aggregate.

### Method
GET

### Endpoint
/v2/aggregates/{aggregateId}/events

### Parameters
#### Path Parameters
- **aggregateId** (string) - Required - Aggregate identifier

#### Query Parameters
- **context** (string) - Required - Context name
- **minSequence** (integer) - Optional - Minimum sequence number (inclusive)
```

--------------------------------

### Configure Plugin using YAML File Command

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/administration/plugins

This command configures plugin properties by referencing a YAML file. It uploads the configuration defined in the specified file to Axon Server for a given plugin, version, and context.

```bash
java -jar axonserver-cli.jar configure-plugin -p <plugin> -v <version> -c <context> -f <filename>
```

--------------------------------

### Event Processor Administration API

Source: https://docs.axoniq.io/axon-server-reference/development/axon-server/administration/admin-configuration/grpc-api

Endpoints for managing event processors, including listing, starting, pausing, splitting, merging, and load balancing.

```APIDOC
## GET /event-processors/all

### Description
Provides a list of all event processors defined by the connected applications.

### Method
GET

### Endpoint
/event-processors/all

### Parameters
#### Query Parameters
- None

#### Request Body
- None

### Request Example
None

### Response
#### Success Response (200)
- **stream EventProcessor** (object) - A stream of EventProcessor objects.

#### Response Example
```json
{
  "eventProcessors": [
    {
      "componentName": "example-component",
      "processorName": "example-processor",
      "instanceName": "instance-1"
    }
  ]
}
```

---

## GET /event-processors/component/{componentName}

### Description
Provides a list of all event processors defined by the specified component.

### Method
GET

### Endpoint
/event-processors/component/{componentName}

### Parameters
#### Path Parameters
- **componentName** (string) - Required - The name of the component.

#### Query Parameters
- None

#### Request Body
- None

### Request Example
None

### Response
#### Success Response (200)
- **stream EventProcessor** (object) - A stream of EventProcessor objects.

#### Response Example
```json
{
  "eventProcessors": [
    {
      "componentName": "example-component",
      "processorName": "example-processor",
      "instanceName": "instance-1"
    }
  ]
}
```

---

## POST /event-processors/start

### Description
Starts a distributed event processor, propagating the start request to all EP instances connected to Axon Server.
* Clients need to be already running and connected to Axon Server before the operation is executed.

### Method
POST

### Endpoint
/event-processors/start

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **eventProcessorIdentifier** (object) - Required - Identifies the event processor to start.
  - **componentName** (string) - Required - The name of the component.
  - **processorName** (string) - Required - The name of the event processor.

### Request Example
```json
{
  "eventProcessorIdentifier": {
    "componentName": "my-component",
    "processorName": "my-processor"
  }
}
```

### Response
#### Success Response (200)
- **AdminActionResult** (object) - The result of the administrative action.
  - **success** (boolean) - Indicates if the action was successful.
  - **message** (string) - A message describing the result.

#### Response Example
```json
{
  "success": true,
  "message": "Event processor started successfully."
}
```

---

## POST /event-processors/pause

### Description
Pauses a distributed event processor, propagating the pause request to all EP instances connected to Axon Server.
* Clients need to be already running and connected to Axon Server before the operation is executed.

### Method
POST

### Endpoint
/event-processors/pause

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **eventProcessorIdentifier** (object) - Required - Identifies the event processor to pause.
  - **componentName** (string) - Required - The name of the component.
  - **processorName** (string) - Required - The name of the event processor.

### Request Example
```json
{
  "eventProcessorIdentifier": {
    "componentName": "my-component",
    "processorName": "my-processor"
  }
}
```

### Response
#### Success Response (200)
- **AdminActionResult** (object) - The result of the administrative action.
  - **success** (boolean) - Indicates if the action was successful.
  - **message** (string) - A message describing the result.

#### Response Example
```json
{
  "success": true,
  "message": "Event processor paused successfully."
}
```

---

## POST /event-processors/split-segment

### Description
Splits the largest known segment of the distributed event processor into two segments.

### Method
POST

### Endpoint
/event-processors/split-segment

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **eventProcessorIdentifier** (object) - Required - Identifies the event processor whose segment to split.
  - **componentName** (string) - Required - The name of the component.
  - **processorName** (string) - Required - The name of the event processor.

### Request Example
```json
{
  "eventProcessorIdentifier": {
    "componentName": "my-component",
    "processorName": "my-processor"
  }
}
```

### Response
#### Success Response (200)
- **AdminActionResult** (object) - The result of the administrative action.
  - **success** (boolean) - Indicates if the action was successful.
  - **message** (string) - A message describing the result.

#### Response Example
```json
{
  "success": true,
  "message": "Event processor segment split successfully."
}
```

---

## POST /event-processors/merge-segments

### Description
Merges the smallest known two segments of the distributed event processor into one.
* It may not work if the two smallest segments are not claimed by applications connected to Axon Server.

### Method
POST

### Endpoint
/event-processors/merge-segments

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **eventProcessorIdentifier** (object) - Required - Identifies the event processor whose segments to merge.
  - **componentName** (string) - Required - The name of the component.
  - **processorName** (string) - Required - The name of the event processor.

### Request Example
```json
{
  "eventProcessorIdentifier": {
    "componentName": "my-component",
    "processorName": "my-processor"
  }
}
```

### Response
#### Success Response (200)
- **AdminActionResult** (object) - The result of the administrative action.
  - **success** (boolean) - Indicates if the action was successful.
  - **message** (string) - A message describing the result.

#### Response Example
```json
{
  "success": true,
  "message": "Event processor segments merged successfully."
}
```

---

## GET /load-balancing/strategies

### Description
Provides a list of all load balancing strategies.

### Method
GET

### Endpoint
/load-balancing/strategies

### Parameters
#### Query Parameters
- None

#### Request Body
- None

### Request Example
None

### Response
#### Success Response (200)
- **stream LoadBalancingStrategy** (object) - A stream of LoadBalancingStrategy objects.

#### Response Example
```json
{
  "strategies": [
    "BALANCED",
    "ROUND_ROBIN"
  ]
}
```

---

## POST /load-balancing/balance-processor

### Description
Balances the load across several instances of an event processor, accordingly to the selected strategy.

### Method
POST

### Endpoint
/load-balancing/balance-processor

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **loadBalanceRequest** (object) - Required - The request to balance the load.
  - **eventProcessorIdentifier** (object) - Required - Identifies the event processor to balance.
    - **componentName** (string) - Required - The name of the component.
    - **processorName** (string) - Required - The name of the event processor.
  - **strategy** (string) - Required - The load balancing strategy to use.

### Request Example
```json
{
  "loadBalanceRequest": {
    "eventProcessorIdentifier": {
      "componentName": "my-component",
      "processorName": "my-processor"
    },
    "strategy": "BALANCED"
  }
}
```

### Response
#### Success Response (200)
- **stream google.protobuf.Empty** (object) - An empty response stream indicating the operation has started.

#### Response Example
(Empty stream)

---

## POST /load-balancing/auto-strategy

### Description
Defines the load balancing strategy to use for automatic load balancing.

### Method
POST

### Endpoint
/load-balancing/auto-strategy

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **loadBalanceRequest** (object) - Required - The request to set the auto load balancing strategy.
  - **strategy** (string) - Required - The load balancing strategy to use.

### Request Example
```json
{
  "loadBalanceRequest": {
    "strategy": "ROUND_ROBIN"
  }
}
```

### Response
#### Success Response (200)
- **stream google.protobuf.Empty** (object) - An empty response stream indicating the operation has started.

#### Response Example
(Empty stream)

```