Aeron Cache is a clustered key-value store built on Aeron, Agrona and SBE with a RAFT-based consensus layer. It exposes REST over HTTP, as well as WebSocket and Server-Sent Events interfaces for real-time updates, and supports multi-cache subscriptions. The project ships with a UI (Next.js) and exposes near-cache capabilities to accelerate reads. To use it, run the MCP server (via Docker, Docker Compose, or Kubernetes) and then interact with the provided HTTP, WS, or SSE endpoints to store and retrieve values, subscribe to cache updates, or explore cluster status. The MCP layer (cache-mcp) provides Swagger-based AutoMCP interfaces for programmatic access to the cache-management features.

Key capabilities include:

• Clustered and single-node operation with RAFT consensus
• Near caching for faster reads and reduced latency
• Embedded clients in multiple languages and a Rust-based CLI
• HTTP, WebSocket, and SSE interfaces for real-time and REST access
• Observability via Prometheus, cAdvisor, Jaeger/OTEL, and tracing
• UI and APIs to manage and monitor caches, subscriptions, and cluster health

To use the tools, connect to the HTTP API endpoints for CRUD operations on cache entries, use the WS endpoint to receive real-time updates for subscribed caches, and leverage the SSE feed for scalable event streams. If you need multi-cache updates, subscribe to multiple cache IDs via the provided endpoints in the documentation or UI.

Prerequisites:

• Docker and Docker Compose installed on your machine
• Git and Java build tool if you want to build from source (optional)
• Access to the project repository

Installation steps:

1. Clone the repository: git clone https://github.com/bhf/aeron-cache cd aeron-cache/

2. Build the project (optional if using prebuilt images): ./gradlew build

   Wait for the build to complete; this produces the cache-cluster and HTTP/WS/SSE components

3. Run with Docker (recommended for MCP): docker compose build docker compose up This starts the UI, HTTP, WS, and SSE interfaces and the cache cluster in a containerized environment.

4. Alternative: Run in Kubernetes (if you have manifests/Helm):

   Follow the repository's k8s/helm instructions (make install-all) to deploy to your cluster.

5. Access the UI and APIs:

   • UI: http://localhost:3000
   • HTTP API: http://localhost:7071/api/...
   • WS: ws://localhost:7071/api/ws/...

Prerequisites recap: ensure Docker is running, network ports 3000, 7071/7072 (for HTTP/WS/SSE) are available, and you have the cluster resources allocated (CPU/memory) for the containerized services.

Tips and common issues:

• If you see port binding errors, ensure no other services occupy 3000, 7071, or 7072 on your host.
• For multi-cache subscriptions, use the provided endpoints to subscribe to multiple cache IDs via WS or SSE; ensure your client handles reconnects gracefully.
• The UI is Next.js-based and may require a build step if you customize the frontend. Use the repository’s Makefile for Kubernetes deployment automation.
• If you iterate on the cache logic, you can leverage the embedded clients (Java, Rust, TypeScript, Python) to test against the running cluster.
• For observability, enable Jaeger/OTEL tracing in your environment to trace requests across services.