Apache Unomi

Prerequisites

Before you deploy this image, make sure you have:

• An active Azure subscription.
• An SSH key pair.
• A VNet and subnet in the target region.
• A VM size of Standard_B4ms (4 vCPU / 16 GiB RAM), which is a sensible starting point. Both the Unomi (Karaf) JVM and the Elasticsearch JVM are memory-hungry, so size up for larger datasets or busier ingest.
• NSG inbound rules that 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 SecureAnyCloud, 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 choose Review + create and Create.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:apache-unomi-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name unomi \
  --image sac1647283583153:apache-unomi-ubuntu-24-04:default:latest \
  --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. Print it with:

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. Check it with:

curl -s http://localhost/health

It returns ok. This endpoint never requires authentication, so it is safe to use 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 that 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 it rejects a wrong password with 401 Unauthorized.

The command embeds your unique password, so 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, 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 with the karaf credentials from Step 5. For example, use GET /cxs/profiles/count for the current profile count, or GET /cxs/segments to list segments. 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 you can resize the disk independently. Confirm the mount with:

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. To rotate the Karaf password, edit 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 run 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 and 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 (for example, certbot) and your own domain before you run it in production.
• Security patches: unattended-upgrades remains enabled, so the OS continues to receive security updates automatically.

Support

SecureAnyCloud provides 24/7 expert support for this image. Contact sales@secureanycloud.com.

Deploy on Azure

Launch Apache Unomi on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Prerequisites

Before you deploy this image, make sure you have:

• An Amazon Web Services account where you can launch EC2 instances.
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products.
• An EC2 key pair in the target Region for SSH access to the instance.
• A VPC and subnet in the target Region, with a security group that allows inbound port 22 from your management network only.
• An SSH client on your workstation.

You do not need to open port 8181, 9200 or 80 in the security group. You reach the API through the SSH tunnel described later in this guide.

Launching from the AWS Marketplace

• Open the product page in AWS Marketplace and choose Continue to Subscribe.
• Accept the terms, then choose Continue to Configuration.
• Select the software version and the Region you want to deploy into, then choose Continue to Launch.
• Choose Launch through EC2 for full control of networking and storage.
• Pick an instance type. m5.large is the recommended minimum. Scale up as your profile and event volume grow, because both Unomi and Elasticsearch are JVM services that benefit from additional memory.
• Select your VPC, subnet and a security group that opens only inbound TCP 22 from your management network.
• Choose your key pair and launch.

Connecting to your instance

The CDP data volume is attached and mounted automatically. Connect over SSH on port 22 using the default login user for your operating system variant:

OS variant SSH login user

Ubuntu 24.04 LTS ubuntu

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

Retrieve the per-instance administrator password

The first-boot service writes a unique administrator password to a root-only file. Read it with:

sudo cat /root/unomi-credentials.txt

The file shows the REST URL, the administrator user (karaf), the generated UNOMI_ADMIN_PASSWORD, and the third-party event API key. Keep this file safe. It is readable only by root.

Confirm the services are running

systemctl is-active elasticsearch apache-unomi nginx

All three report active. Confirm that the Elasticsearch datastore is the Apache-2.0 OSS build and is answering on the loopback interface:

curl -s http://127.0.0.1:9200 | grep -E '"number"|"build_flavor"'

The build_flavor is oss and the version is 7.10.2.

Confirm the context server and authentication

The nginx health endpoint answers without authentication:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/health

The Unomi cluster endpoint requires the administrator password. Read it into a shell variable from the credentials file. Then confirm that a wrong password is refused and the correct one returns the cluster JSON:

PW=$(sudo grep '^UNOMI_ADMIN_PASSWORD=' /root/unomi-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'wrong password -> %{http_code}\n' -u karaf:definitely-wrong http://127.0.0.1:8181/cxs/cluster
curl -s -u "karaf:$PW" http://127.0.0.1:8181/cxs/cluster

The first call returns 401. The second returns a JSON array describing the context-server node.

Create and query a visitor profile

This is the core CDP round trip. Write a profile that carries a known property, then read it back through the REST API.

PW=$(sudo grep '^UNOMI_ADMIN_PASSWORD=' /root/unomi-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'profile saved -> %{http_code}\n' -u "karaf:$PW" -H 'Content-Type: application/json' -X POST http://127.0.0.1:8181/cxs/profiles -d '{"itemId":"demo-visitor-1","itemType":"profile","properties":{"region":"emea","plan":"trial"}}'

Read the profile back and confirm the stored properties:

PW=$(sudo grep '^UNOMI_ADMIN_PASSWORD=' /root/unomi-credentials.txt | cut -d= -f2-)
curl -s -u "karaf:$PW" http://127.0.0.1:8181/cxs/profiles/demo-visitor-1

The response contains the region and plan properties exactly as written, which proves that the profile survived the Elasticsearch round trip.

To list the datastore indices that Unomi created, run:

curl -s 'http://127.0.0.1:9200/_cat/indices/context*?h=index'

Reaching the API from your workstation

The REST API is bound to loopback. To use it from an application or an HTTP client on your workstation, open an SSH tunnel:

ssh -i /path/to/your-key.pem -L 8181:127.0.0.1:8181 ubuntu@<public-ip>

With the tunnel open, http://127.0.0.1:8181/cxs/cluster on your workstation reaches the context server on the instance. Authenticate with the karaf user and the password from the credentials file.

To expose the nginx-fronted API on port 80 instead, add an inbound rule for TCP 80 to your security group, restricted to your own network range. Put TLS termination and your own access controls in front of it. Never expose the Unomi API to the public internet without TLS and authentication.

Data, indices and rollover

Profiles, sessions, events and system items are stored as context-* indices in the local Elasticsearch datastore under /var/lib/unomi/elasticsearch.

Because this is a single-instance appliance, monthly index rollover is disabled. Rollover is an Elasticsearch Index Lifecycle Management feature that is not part of the Apache-2.0 OSS distribution, so events and sessions are stored in plain indices. For high-volume production workloads, SecureAnyCloud support can help you plan an external or multi-node search tier and enable rollover.

Managing the services

sudo systemctl restart apache-unomi
sudo systemctl status elasticsearch apache-unomi nginx

After a restart, the context server takes a short while to bootstrap its OSGi bundles. Once the REST stack is ready, the /cxs endpoints return 401 (rather than 404).

Backup and maintenance

• Back up the data volume at /var/lib/unomi with EBS snapshots. This captures the Elasticsearch indices and the Karaf data directory.
• Rotate credentials by editing org.apache.unomi.security.root.password and the karaf line in /opt/unomi/etc/users.properties, then restarting apache-unomi.
• Operating system updates are delivered by the normal Ubuntu unattended-upgrades mechanism.

Support

Every deployment is backed by SecureAnyCloud engineers, available 24/7 by email at sales@secureanycloud.com and by live chat. Support covers deployment and sizing, CDP data modelling (profiles, sessions, events, segments, rules and scoring), REST API integration, the Elasticsearch datastore, securing the API behind TLS and authentication, backup and restore of the data volume, and Apache Unomi and JVM tuning. Critical issues receive a one-hour average response time.

Apache, Apache Unomi and Apache Karaf are trademarks of The Apache Software Foundation. Elasticsearch is a trademark of Elasticsearch B.V. All product and company names are trademarks or registered trademarks of their respective holders.

Deploy on AWS

Launch Apache Unomi Customer Data Platform with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com