Deployment

Docker, Kubernetes, Helm, static product site, and optional MCP for AI agents.

Kubernetes deployment

Choose a deployment path

Kubernetes: install, connect, verify

Commands run from a repository checkout. The example uses release name and namespace eventore, a Kafka backend, one replica, a PVC, and local port forwarding. Resource values are starting examples, not measured sizing recommendations. Confirm the registry images are available in your environment.

  1. Create the namespace and API-token secret.
  2. Review the downloadable Helm values; set your StorageClass or existing claim if the cluster has no default.
  3. Render the manifests, install, and wait for both deployments.
kubectl create namespace eventore
kubectl -n eventore create secret generic eventore-api --from-file=api-token=./api-token.txt
helm template eventore ./deploy/helm/eventore -n eventore -f docs/examples/helm-single-replica.yaml
helm upgrade --install eventore ./deploy/helm/eventore -n eventore -f docs/examples/helm-single-replica.yaml --wait --timeout 5m
kubectl -n eventore rollout status deployment/eventore-backend
kubectl -n eventore rollout status deployment/eventore-frontend

Create api-token.txt beforehand with a strong token on a single line and no trailing newline; keep the file out of Git. Both the Secret and release must be in the same namespace.

# Example for a local port-forward; install from the repository root.
eventore:
  streamProviders: [KAFKA]
  deploymentMode: DEV
  security:
    apiTokenExistingSecret: eventore-api
    apiTokenSecretKey: api-token
    allowedOrigins: "http://localhost:8088"
  connections:
    persistence:
      enabled: true
      volumeType: pvc
      size: 1Gi
backend:
  replicaCount: 1
  resources:
    requests:
      cpu: 250m
      memory: 512Mi
    limits:
      memory: 1Gi
frontend:
  replicaCount: 1
  env:
    apiBaseUrl: /api/v1
    wsUrl: ws://localhost:8088/ws/stream
  resources:
    requests:
      cpu: 50m
      memory: 64Mi
    limits:
      memory: 128Mi
ingress:
  enabled: false

In one terminal, forward the frontend service:

kubectl -n eventore port-forward service/eventore-frontend 8088:80

Open localhost:8088, enter the token through Settings, and create a Kafka profile using a broker address reachable from the backend pod. The frontend proxies API and WebSocket requests to the backend.

In another terminal, forward the backend for a direct health check:

kubectl -n eventore port-forward service/eventore-backend 8080:8080

Then check readiness and effective configuration:

curl http://localhost:8080/actuator/health/readiness
curl http://localhost:8080/api/v1/config -H "Authorization: Bearer YOUR_TOKEN"

Expected: readiness reports UP; config shows the requested mode and Kafka protocol. Validate a broker profile separately.

Move from port forwarding to ingress

Set the host and WebSocket URL together. These are supported chart keys:

ingress:
  enabled: true
  className: nginx
  host: eventore.example.com
frontend:
  env:
    apiBaseUrl: /api/v1
    wsUrl: wss://eventore.example.com/ws/stream
eventore:
  security:
    allowedOrigins: "https://eventore.example.com"

The chart routes /api and /ws to the backend and / to the frontend. The current ingress template does not render a spec.tls block. Configure TLS termination through your ingress platform or an explicitly managed ingress manifest; adding an unsupported ingress.tls value alone will not provision TLS. Verify WebSocket upgrades and idle timeouts with your controller.

Persistence, upgrades, and recovery

The chart-created PVC uses ReadWriteOnce. Keep the example at one backend replica. Increasing replicas is not a complete HA solution: subscriptions and validation history are process-local, and a shared file needs a compatible access mode and coordinated writers. Nginx affinity alone does not solve state sharing. Review your store and routing design before scaling out.

Back up connection data and keep the values file used for each release. Inspect release history before rollback:

helm history eventore -n eventore
helm upgrade eventore ./deploy/helm/eventore -n eventore -f docs/examples/helm-single-replica.yaml --wait --timeout 5m
# Replace REVISION with the known-good revision from helm history:
helm rollback eventore REVISION -n eventore --wait

A Helm rollback changes workloads and configuration; it does not restore external broker data or undo messages published during operation. Pin image tags appropriate to your release policy. For a failed rollout, inspect pod events, logs, registry access, and PVC status using the troubleshooting guide.

Local brokers (development)

docker compose -f docker/docker-compose.brokers.yml up -d
cd backend && mvn -pl eventore-server -am spring-boot:run -Dspring-boot.run.profiles=local
cd frontend && npm install && npm run dev

Versioned images & Helm charts

Stable releases use provider-qualified tags such as 0.2.1-kafka and 0.2.1-all. The chart pins backend, frontend, and MCP images to its application version. Check release availability before installing. Provider-only tags are development aliases, not pinned releases.

Pushes to main validate the product. Version tags run the same quality gates, publish images and OCI charts, and then create the GitHub Release. Manual development builds use Git-SHA image tags and distinct development chart versions.

Registry: github.com/vijayptiwari — Packages. On a public repo, set package visibility to Public if docker pull or helm install oci://... returns not found.

Stream-provider backend images

Backend images are tagged by which stream providers are in the JAR, not by a single latest “full” build. Helm eventore.streamProviders picks the tag automatically.

Image tagStream providers
kafka, mqtt, jms, pulsar, rabbitmq, kinesis, gcp-pubsub, azure-servicebusOne provider each
kafka-kinesisKAFKA + KINESIS
allAll eight providers

Repository: ghcr.io/vijayptiwari/eventore-backend:<tag>. Matrix: deploy/ci-backend-images.json.

Frontend & MCP

ImageTags
ghcr.io/vijayptiwari/eventore-frontendlatest, git SHA, semver
ghcr.io/vijayptiwari/eventore-mcplatest, git SHA, semver

Helm: eventore.streamProviders

eventore:
  streamProviders:
    - KAFKA
    - KINESIS   # → image tag <version>-kafka-kinesis

Leave image.backend.tag empty to auto-select the tag. Override only for custom builds.

helm install eventore ./deploy/helm/eventore \
  -f deploy/helm/eventore/values-stream-kafka.yaml

helm install eventore ./deploy/helm/eventore \
  -f deploy/helm/eventore/values-kafka-kinesis.yaml

Pull images locally

docker pull ghcr.io/vijayptiwari/eventore-backend:0.2.1-kafka
docker pull ghcr.io/vijayptiwari/eventore-frontend:0.2.1
docker pull ghcr.io/vijayptiwari/eventore-mcp:0.2.1

Helm charts (OCI on GHCR)

ChartOCI referenceWorkloads
eventoreoci://ghcr.io/vijayptiwari/charts/eventoreBackend + frontend pods
eventore-mcpoci://ghcr.io/vijayptiwari/charts/eventore-mcpOptional MCP pod

Chart version matches Chart.yaml (e.g. 0.2.1).

helm install eventore oci://ghcr.io/vijayptiwari/charts/eventore --version 0.2.1 \
  -f deploy/helm/eventore/values-stream-kafka.yaml

helm install eventore-mcp oci://ghcr.io/vijayptiwari/charts/eventore-mcp --version 0.2.1 \
  --set eventore.apiUrl=http://eventore-backend:8080/api/v1

New multi-provider combos: add an entry to deploy/ci-backend-images.json and merge to main so CI publishes that tag.

CI quality gates

Every push to main runs unit tests, five-protocol Testcontainers integration tests, frontend Vitest + production build + Playwright smoke, MCP tests, and Helm lint. Backend images and the Helm chart publish only when all gates pass. See docs/TESTING.md.

Persistence and HA (Helm)

eventore:
  connections:
    persistence:
      enabled: true
      volumeType: pvc    # emptyDir = pod-local only; pvc survives pod delete

backend:
  replicaCount: 2      # requires ingress session affinity for SSE/WS

ingress:
  sessionAffinity:
    enabled: true

Full guidance: docs/HA.md · chart NOTES.txt warnings after install.

Build from source (custom provider sets)

docker build -f docker/Dockerfile.backend \
  --build-arg EVENTORE_STREAM_PROFILES=kafka-kinesis \
  -t eventore-backend:custom .

# Local dev — all providers (not published to GHCR)
docker build -f docker/Dockerfile.backend \
  --build-arg EVENTORE_STREAM_PROFILES=providers-all \
  -t eventore-backend:dev .

Helm from repository (recommended for K8s)

Charts under deploy/helm/ deploy backend + frontend (and optionally MCP from the sibling chart). Same values as OCI installs — use a git checkout when you want to customize templates before install.

Values files:

helm install eventore ./deploy/helm/eventore \
  --set ingress.enabled=true \
  --set ingress.host=eventore.example.com

# Slim stack
helm upgrade --install eventore ./deploy/helm/eventore \
  -f deploy/helm/eventore/values-kafka-kinesis.yaml

See deploy/README.md in the repository for ingress, secrets, and network policies.

Hosting this documentation site

The docs/ folder is the product site (HTML + CSS + SVG). It is intended for GitHub Pages:

# Repository Settings → Pages → Branch: main, Folder: /docs

# Local preview
npx serve docs

See docs/README.md for details. The .nojekyll file ensures GitHub serves static HTML without Jekyll processing.

MCP server (optional)

A separate Node MCP server (mcp/eventore-mcp) exposes control plane and data plane APIs to AI agents (Cursor, HTTP MCP clients). It does not connect to brokers directly.

Full tool, prompt, and resource catalog: MCP for AI agents.

Health and observability

GET /actuator/health
GET /api/v1/config
GET /api/v1/control/plane

Use control plane revision to detect provider registration changes without restarting the UI.

Related: Getting started · Configuration · Architecture