Skip to content
Klutch.sh Docs

Deploying an Unomi App

Introduction

Apache Unomi is an open-source customer data platform for profiles, events, and segmentation. This guide shows how to containerize Unomi with a Dockerfile, connect it to Elasticsearch, persist data, and deploy it to Klutch.sh over HTTP.

Prerequisites

  • GitHub repository containing your Dockerfile.
  • Elasticsearch/OpenSearch cluster (managed or deployed separately).
  • Klutch.sh project ready in klutch.sh/app.

Project structure

.
└── Dockerfile

Sample Dockerfile

FROM apache/unomi:latest


# Default Unomi port
ENV HTTP_PORT=8181
EXPOSE 8181

Required environment variables

  • ELASTICSEARCH_ADDRESSES – e.g., http://HOST:9200
  • ELASTICSEARCH_USERNAME and ELASTICSEARCH_PASSWORD – if security is enabled
  • HTTP_PORT – internal port (default 8181)
  • UNOMI_CLUSTER_NAME – cluster name for Unomi/Elasticsearch
  • UNOMI_ROOT_PASSWORD – set a strong password for Karaf/Unomi console

Optional environment variables

  • UNOMI_KARAF_DEBUG=false – keep debug off in production
  • UNOMI_ELASTICSEARCH_SSL=false – set true if using HTTPS
  • UNOMI_HOST – public host URL (e.g., https://example-app.klutch.sh)

Persistence

Persist Unomi data and logs:

  • Mount path: /opt/unomi/data
  • Size: based on profile/event volume and retention

Networking

  • Protocol: HTTP
  • Internal port: 8181
  • Users and services reach https://example-app.klutch.sh while Klutch.sh routes to port 8181 in the container.
Terminal window
curl -I http://localhost:8181/cxs/cluster

Deployment on Klutch.sh

  1. Push your Dockerfile to GitHub.
  2. In klutch.sh/app, create a new app and select GitHub as the source.
  3. Klutch.sh automatically detects the Dockerfile in the repository root.
  4. Select HTTP traffic and set the internal port to 8181.
  5. Add environment variables for Elasticsearch (ELASTICSEARCH_ADDRESSES, credentials, SSL toggle), Unomi cluster name, and UNOMI_ROOT_PASSWORD. Mark sensitive values as secrets.
  6. Attach a persistent volume at /opt/unomi/data sized for your expected profiles and events.
  7. Deploy. After startup, access the Unomi endpoints at https://example-app.klutch.sh/cxs and configure your segments and rules.

Verification

  • Cluster check:

    Terminal window
    curl -s https://example-app.klutch.sh/cxs/cluster

  • Basic auth check (if enabled): ensure the endpoint returns status 200 and cluster info.

Next steps

  • Secure Elasticsearch with TLS and role-based access.
  • Set retention policies for events and profiles.
  • Enable backups for both the Elasticsearch cluster and the mounted /opt/unomi/data volume.