AxonOps™ Server Docker Compose

AxonOps is a comprehensive management platform designed for Apache Cassandra® and Apache Kafka®, offering unified monitoring, maintenance, and backup functionalities. Built by Cassandra and Kafka experts, it provides the only cloud-native solution to monitor, maintain and backup Apache Cassandra or Apache Kafka clusters through either SaaS or self-hosted deployments.

For detailed documentation, visit:

• Demo https://axonops.com/demo-sandbox/
• Documentation: https://axonops.com/docs
• Product Information: https://axonops.com

For other self-host installation options like Kubernetes, see here: https://axonops.com/docs/installation-starter/axon-server/axonserver_install/

Table of Contents

1. Self-Hosting AxonOps
   • Install License (Optional)
2. Container Runtime Options
3. Accessing AxonOps
4. Compose Structure
   • Overview
   • Key Components
   • Service Details
   • Notes
5. Instructions
   • Using Docker
   • Using Podman
6. Health Check Script
   • How the Script Works
   • Usage
     • Example Output

Self-Hosting AxonOps

When self-hosting AxonOps using this docker-compose.yml file:

1. The axon-server service acts as the backend, communicating with agents and exposing REST APIs.
2. The axon-dash service provides the dashboards and user interface.
3. Data is stored in:
   • Elasticsearch®, which handles indexing and search functionality.
   • Cassandra, which manages time-series data storage.

Install License (Optional)

AxonOps is free to use and includes a range of powerful features at no cost.

For enterprise customers with a license key, you can enhance your installation by adding the key to the axon-server.yml file. Ensure that the organization name matches the one used when obtaining your license.

Container Runtime Options

This project can be run using either Docker or Podman.

It has been tested on Debian 12 with Docker, although it should work in other environments. Please raise an issue on the project if you encounter any problems specific to your setup.

Accessing AxonOps

Once the services are running, access the AxonOps dashboard at: http://localhost:3000 and you can configure your AxonOps agents to point at the AxonOps Server to start managing your cluster.

For production deployments, ensure proper security configurations are in place and refer to the official documentation for advanced setup options.

The platform provides dynamic dashboards for collecting logs and metrics, offering insights into cluster performance and health status. You can set up alerts for various metrics to ensure optimal performance.

Compose Structure

The docker-compose.yml file in this repository defines the services, networks, and volumes required to self-host AxonOps in this fashion. Below is an explanation of its structure and key components.

Overview

The docker-compose.yml file orchestrates the following services:

1. axon-server: The core backend component of AxonOps. This service handles communication with agents and exposes REST APIs for configuration.
2. axon-dash: The frontend component providing dashboards and a user interface for interacting with AxonOps.
3. Elasticsearch®: A search engine used by AxonOps to store and index data.
4. Apache Cassandra®: A distributed NoSQL database used by AxonOps to store time-series data.
5. busybox (initialization container): Ensures proper file permissions for mounted volumes before starting Elasticsearch and Cassandra.

Key Components

Volumes

The docker-compose.yml file mounts persistent volumes for Elasticsearch and Cassandra to ensure data durability across container restarts. These volumes are critical for storing logs and other data generated by AxonOps.

• Elasticsearch Volumes:

  • Mounted to persist Elasticsearch indices and logs.
  • Ensures that all data stored in Elasticsearch remains intact even if the container is restarted.

• Cassandra Volumes:

  • Mounted to persist time-series data and other information stored in Cassandra.
  • Guarantees data reliability and availability.

Initialization with BusyBox

On initialization, a lightweight busybox container is used to set the correct file permissions for the mounted volumes. This step ensures that Elasticsearch and Cassandra have the necessary permissions to read from and write to their respective volumes.

The busybox container runs a simple script that adjusts file ownership and permissions, then exits once the task is complete. This ensures a smooth startup process for the dependent services.

Service Details

axon-server

• Acts as the central hub for AxonOps agents.
• Exposes REST APIs that allow users to configure AxonOps programmatically.
• Handles incoming data from agents, processes it, and stores it in Elasticsearch and Cassandra.

axon-dash

• Provides the primary user interface for AxonOps.
• Allows users to visualize data, monitor systems, and interact with dashboards.
• Communicates with axon-server to fetch data for display.

elasticsearch

• Stores indexed data required by AxonOps for searching, analytics, and monitoring.
• Configured with mounted volumes to persist indices and logs across restarts.

cassandra

• Stores time-series data used by AxonOps for long-term storage and analysis.
• Configured with mounted volumes to ensure durability of stored data.

Notes

• Ensure that the mounted volumes have appropriate permissions before starting the services. The busybox initialization container takes care of this automatically during startup.
• Both Elasticsearch and Cassandra are resource-intensive services; ensure your hosting environment has sufficient resources (CPU, memory, disk space) to handle their requirements effectively.

This structure ensures a robust deployment of AxonOps with all necessary components running seamlessly together in a single Docker Compose setup.

Instructions

Using Docker

# Clone repository
git clone https://github.com/axonops/axonops-server-compose
cd axonops-server-compose

# Start services
docker compose up -d

Using Podman

# Clone repository
git clone https://github.com/axonops/axonops-server-compose
cd axonops-server-compose

# Start services
podman compose up -d

Health Check Script

This repository includes a health-check script (health-check.sh) designed to monitor and verify the status of services running in a Docker or Podman Compose environment. It ensures that all expected services in the Compose environment are running and healthy. It helps system administrators or developers quickly identify issues with containerized services by logging errors for any missing or unhealthy services.

How the Script Works

1. Logging Errors:

   • The script uses a log_error function to log error messages to the system's syslog with the tag container-health-check.

2. Container Runtime Selection:

   • By default, the script assumes the container runtime is docker.
   • If podman is passed as an argument, it switches to using Podman.
   • If an invalid argument is passed, the script exits with an error message.

3. Runtime Validation:

   • The script checks if the selected container runtime (docker or podman) is installed and available in the system's PATH.
   • It also verifies that the Compose plugin for the selected runtime is installed.

4. Service Status Check:

   • The script uses docker compose ps (or podman compose ps) to list all services in the Compose environment.
   • It compares these services against a predefined list of expected services: elasticsearch, cassandra, axon-server, and axon-dash.
   • If any expected service is not running, it logs an error.

5. Health Status Check:

   • For each running service, the script retrieves its health status using the inspect command.
   • If a service's health status is not healthy, or if its health check fails, an error is logged.

6. Exit Code:

   • The script exits with a code of 0 if all services are running and healthy.
   • If any issues are detected (e.g., missing or unhealthy services), it exits with a non-zero code.

Usage

To run the script:

./health-check.sh [runtime]

• [runtime]: Optional argument to specify the container runtime (docker or podman). Defaults to docker.

Example Output

• If all services are running and healthy:

  # No output; exit code 0

• If a service is missing or unhealthy:

  ERROR: Service cassandra is not running
  ERROR: Service elasticsearch is not healthy. Current status: starting

The errors are also logged to syslog for further debugging.

---

This project may contain trademarks or logos for projects, products, or services. Any use of third-party trademarks or logos are subject to those third-party's policies. AxonOps is a registered trademark of AxonOps Limited. Apache, Apache Cassandra, Cassandra, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Elasticsearch is a trademark of Elasticsearch B.V., registered in the U.S. and in other countries. Docker is a trademark or registered trademark of Docker, Inc. in the United States and/or other countries.