Apache Unomi on Ubuntu 24.04 on Azure User Guide

Overview

Apache Unomi is the reference implementation of the OASIS Customer Data Platform (CDP) specification. It is a Java/OSGi context server that collects, stores and serves visitor profiles, sessions, events, segments, scoring plans, rules and personalization decisions over a JSON REST API. The cloudimg image installs Apache Unomi 2.7.0 on Apache Karaf with a co-located single-node Elasticsearch 7.17 datastore, giving a fully functional CDP for development, test, single-tenant profiling and proof-of-concept workloads without standing up a multi-node search cluster. Unomi runs as a dedicated unomi service account bound to the loopback interface behind an nginx reverse proxy on port 80, keeps the Elasticsearch index data and the Karaf data directory on a dedicated Azure data disk, and generates a unique admin password and third-party API key on the first boot of every VM. Backed by 24/7 cloudimg support.

What is included:

• Apache Unomi 2.7.0 (Apache Karaf 4.2 distribution) on OpenJDK 11
• A co-located single-node Elasticsearch 7.17 datastore on 127.0.0.1:9200, the datastore Apache Unomi 2.x targets
• The Unomi context-server REST API (/cxs) protected by Karaf basic authentication
• nginx on :80 as a reverse proxy to the loopback Unomi connector on 127.0.0.1:8181
• A per-VM Karaf admin password and third-party API key generated on first boot and recorded in a root-only file
• A dedicated Azure data disk at /var/lib/unomi for the Elasticsearch index data and the Karaf data directory
• elasticsearch.service and apache-unomi.service (running as the unprivileged unomi user) + nginx.service as systemd units, enabled and active
• An unauthenticated /health endpoint for Azure Load Balancer health probes
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Both the Unomi (Karaf) JVM and the Elasticsearch JVM are memory hungry, so Standard_B4ms (4 vCPU / 16 GiB RAM) is a sensible starting point; size up for larger datasets or busier ingest. NSG inbound: allow 22/tcp from your management network and 80/tcp. Unomi serves plain HTTP on port 80; for production, terminate TLS in front of it with your own domain.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Apache Unomi by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Review the dedicated data disk on the Disks tab, then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name unomi \
  --image <marketplace-image-urn> \
  --size Standard_B4ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name unomi --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

systemctl is-active elasticsearch.service apache-unomi.service nginx.service

All three report active. Elasticsearch and the Unomi context server both run as the dedicated unomi user, bound to the loopback interface (127.0.0.1:9200 for Elasticsearch, 127.0.0.1:8181 for the Unomi REST API); nginx fronts Unomi on port 80. The Elasticsearch index data and the Karaf data directory live on the dedicated Azure data disk mounted at /var/lib/unomi.

Step 5 - Retrieve your admin credentials

The Karaf admin password and the third-party API key are generated uniquely on the first boot of your VM and written to a root-only file:

sudo cat /root/unomi-credentials.txt

This file contains UNOMI_ADMIN_USER (karaf), UNOMI_ADMIN_PASSWORD, the UNOMI_THIRDPARTY_KEY used for secured event submission, and the public REST URL. Store the password somewhere safe.

Step 6 - Confirm the health endpoint

nginx serves an unauthenticated health endpoint for load balancers and probes:

curl -s http://localhost/health

It returns ok. This endpoint never requires authentication, so it is safe for an Azure Load Balancer health probe.

Step 7 - Check the Elasticsearch datastore and Unomi indices

Unomi creates its context-* indices in the co-located Elasticsearch datastore on first start. Confirm the datastore is healthy and the indices exist:

curl -s http://127.0.0.1:9200/_cluster/health?pretty
curl -s "http://127.0.0.1:9200/_cat/indices/context-*?v&h=health,status,index,docs.count"

The cluster health reports "status" : "green", and the index list shows the Unomi context-* indices (context-profile, context-session, context-event, context-systemitems and others).

Step 8 - Call the Unomi REST API with your credentials

The Unomi context-server REST API (/cxs) is protected by Karaf basic authentication. The /cxs/cluster endpoint returns the cluster node information as JSON for the per-VM karaf password and rejects a wrong password with 401 Unauthorized. Because the command embeds your unique password, run it interactively rather than from a script - substitute the value of UNOMI_ADMIN_PASSWORD from Step 5 for <UNOMI_ADMIN_PASSWORD>:

curl -s -u karaf:<UNOMI_ADMIN_PASSWORD> http://127.0.0.1:8181/cxs/cluster

The response is a JSON array beginning [{"cpuLoad":...,"publicHostAddress":"http://localhost:8181",...}]. A wrong password returns HTTP 401 with no body.

Step 9 - Ingest an event and create a profile

Unomi's public /cxs/context.json endpoint is how a web client obtains a visitor context and submits events. From your own application you POST a context request that references a session and profile; Unomi resolves (or creates) the profile in the datastore and applies your rules and segments. To administer profiles, sessions, segments, scoring plans and rules, use the authenticated /cxs endpoints (for example GET /cxs/profiles/count for the current profile count, or GET /cxs/segments to list segments) with the karaf credentials from Step 5. The full REST reference is in the Apache Unomi documentation.

Step 10 - Confirm the datastore lives on the dedicated disk

The Elasticsearch index data (/var/lib/unomi/elasticsearch) and the Karaf data directory (/var/lib/unomi/karaf) are stored on the dedicated Azure data disk so they survive OS changes and can be resized independently:

findmnt /var/lib/unomi

The mount is backed by a separate Azure data disk captured into the image and re-provisioned on every VM.

Maintenance

• Credentials: the per-VM Karaf admin password and third-party API key are in /root/unomi-credentials.txt. Rotate the Karaf password by editing org.apache.unomi.security.root.password in /opt/unomi/etc/unomi.custom.system.properties and the karaf line in /opt/unomi/etc/users.properties, then sudo systemctl restart apache-unomi.
• Datastore: the Unomi context-* indices, the Elasticsearch data path and the Karaf data directory live under /var/lib/unomi on the data disk; back up that volume to protect your CDP data.
• Logs: Karaf/Unomi logs are under /var/lib/unomi/karaf/log; Elasticsearch logs are under /var/log/elasticsearch.
• Tuning: edit the Elasticsearch heap in /opt/elasticsearch/config/jvm.options.d/heap.options and the Unomi heap (EXTRA_JAVA_OPTS) in /opt/unomi/bin/setenv, then restart the corresponding service.
• TLS: Unomi serves plain HTTP on port 80; front it with TLS (e.g. certbot) and your own domain before production use.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.