AxonOps is a management platform for Apache Cassandra and Apache Kafka, offering monitoring, maintenance, and backup capabilities. This repository provides a simple way to run AxonOps locally using Docker Compose.
Links:
Before you begin, make sure you have:
-
Docker Desktop (recommended for beginners) or Docker Engine installed
- Download Docker Desktop (Windows/Mac/Linux)
- Docker Desktop includes Docker Compose
-
Minimum System Requirements:
- 4 GB RAM available for Docker (8 GB recommended)
- 10 GB free disk space
- macOS, Windows 10/11, or Linux
-
Verify Docker is installed by opening a terminal and running:
docker --version docker compose version
You should see version numbers for both commands.
git clone https://github.com/axonops/axonops-server-compose
cd axonops-server-composeOr download the ZIP file and extract it.
docker compose up -dThis command:
- Downloads the required container images (first time only)
- Starts all services in the background (
-dmeans "detached") - May take 2-5 minutes on first run
Check the status of all services:
docker compose psWait until all services show healthy in the STATUS column. You can also watch the logs:
docker compose logs -fPress Ctrl+C to stop watching logs.
Open your web browser and go to: http://localhost:3000
You're now ready to configure your AxonOps agents to connect to the server on port 1888.
docker compose ps# All services
docker compose logs -f
# Specific service
docker compose logs -f axon-serverdocker compose downdocker compose up -ddocker compose down -vWarning: The
-vflag removes all stored data. Only use this if you want to start fresh.
By default, the services use conservative memory settings suitable for development:
- OpenSearch: 2 GB heap
- Cassandra: 1 GB heap
For production or larger workloads, increase the memory by setting environment variables before starting:
# Set custom memory (before running docker compose up)
export OPENSEARCH_HEAP_SIZE=4g
export CASSANDRA_HEAP_SIZE=4096M
# Then start services
docker compose up -dOr set them inline:
OPENSEARCH_HEAP_SIZE=4g CASSANDRA_HEAP_SIZE=4096M docker compose up -dThe services use default credentials. For production deployments, change these by setting environment variables:
export AXONOPS_SEARCH_USER=admin
export AXONOPS_SEARCH_PASSWORD=your-secure-password
export AXONOPS_DB_USERNAME=your-secure-passwordAxonOps is free to use. Enterprise customers with a license key can add it to axon-server.yml:
license_key: "your-license-key"
org: "your-organization-name"This setup runs four services:
| Service | Description | Port |
|---|---|---|
| axon-server | Backend API server - handles agent connections and data processing | 1888 (agents), 8080 (API) |
| axon-dash | Web dashboard for monitoring and configuration | 3000 |
| axondb-search | OpenSearch database for indexing and search | 9200 (internal) |
| timseriesdb | Cassandra database for time-series data storage | 9042 |
Your data is stored in Docker volumes, which persist across restarts:
| Volume | Purpose |
|---|---|
searchdb_data |
OpenSearch indices and data |
timeseriesdb_data |
Cassandra time-series data |
axonops_logs |
Application logs |
To see your volumes:
docker volume ls-
Check available memory:
docker stats --no-stream
If memory is maxed out, increase Docker's memory limit in Docker Desktop settings, or reduce heap sizes.
-
Check logs for errors:
docker compose logs axondb-search docker compose logs timseriesdb
-
Restart everything fresh:
docker compose down -v docker compose up -d
- Mac/Windows: Make sure Docker Desktop is running
- Linux: Start the Docker service:
sudo systemctl start docker
Another application is using port 3000, 1888, or 9042. Either:
- Stop the other application
- Or edit
docker-compose.ymlto use different ports (e.g., change"3000:3000"to"3001:3000")
Wait a few minutes - the databases need time to initialize. If they stay unhealthy:
# Check what's wrong
docker compose logs axondb-search
docker compose logs timseriesdb
# Try restarting
docker compose restartThe axon-server may still be starting. Wait for it to become healthy:
docker compose psIf you prefer Podman:
podman compose up -d
podman compose ps
podman compose downThe check_health.sh script verifies all services are running correctly:
./check_health.shIf everything is healthy, you'll see no output. If there are problems, you'll see error messages like:
ERROR: Service timseriesdb is not running
ERROR: Service axondb-search is not healthy. Current status: starting
For Podman users:
./check_health.sh podman| Task | Command |
|---|---|
| Start services | docker compose up -d |
| Stop services | docker compose down |
| View status | docker compose ps |
| View logs | docker compose logs -f |
| Restart a service | docker compose restart axon-server |
| Delete everything | docker compose down -v |
| Update images | docker compose pull && docker compose up -d |
- Documentation: https://axonops.com/docs
- Issues: https://github.com/axonops/axonops-server-compose/issues
- Support: https://axonops.com/contact
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 Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation. Docker is a trademark of Docker, Inc. OpenSearch is a trademark of Amazon Web Services.