Apache Unomi CDP on AWS User Guide

Overview

This image runs Apache Unomi 2.7, the reference implementation of the OASIS Customer Data Platform (CDP) specification. Unomi is a Java context server, built on Apache Karaf, that collects, stores and serves visitor profiles, sessions, events, segments, scoring plans and personalization decisions over a clean REST/JSON API.

Unomi runs under a dedicated unprivileged unomi system account, managed by systemd, on OpenJDK 11. Its required search-engine datastore is a co-located single-node Elasticsearch 7.10.2 in the OSS distribution, which is licensed entirely under Apache-2.0 - the last fully open-source Elasticsearch release, chosen deliberately so every component of the appliance is open source. The datastore keeps its indices, and Karaf keeps its data directory, on a dedicated EBS volume mounted at /var/lib/unomi, separate from the operating system disk and independently resizable.

The Unomi REST API on port 8181 (HTTP) and 9443 (HTTPS), the Elasticsearch datastore on port 9200, and the Karaf shell on port 8102 are all bound to the loopback interface only. An nginx reverse proxy listens on port 80, forwards to the Unomi REST surface (passing HTTP basic authentication through), and serves an unauthenticated /health endpoint for liveness probes. The security group opens only SSH (port 22): you reach the API over an SSH tunnel, or open port 80 to your own network range behind your own controls when you are ready. Both are covered below.

Unomi's REST API is protected by HTTP basic authentication. This image does not ship a shared password: a one-shot first-boot service generates a unique administrator password on every instance, writes it into the Unomi configuration and to /root/unomi-credentials.txt with mode 0600, and rotates the third-party event API key to a per-instance value.

Prerequisites

Before you deploy this image you need:

• 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 allowing 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. The API is reached through the SSH tunnel described later in this guide.

Launching from the AWS Marketplace

1. Open the product page in AWS Marketplace and choose Continue to Subscribe
2. Accept the terms, then choose Continue to Configuration
3. Select the software version and the Region you want to deploy into, then choose Continue to Launch
4. Choose Launch through EC2 for full control of networking and storage
5. Pick an instance type. m5.large is the recommended minimum; scale up as your profile and event volume grow, since both Unomi and Elasticsearch are JVM services that benefit from additional memory
6. Select your VPC, subnet and a security group that opens only inbound TCP 22 from your management network
7. 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:

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

You will see 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 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 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 carrying 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, proving the profile survived the Elasticsearch round trip. You can list the datastore indices Unomi created:

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, so open an SSH tunnel to use it from an application or an HTTP client on your workstation:

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.

If you prefer to expose the nginx-fronted API on port 80, add an inbound rule for TCP 80 to your security group restricted to your own network range, and 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 (an Elasticsearch Index Lifecycle Management feature that is not part of the Apache-2.0 OSS distribution) is disabled: events and sessions are stored in plain indices. For high-volume production workloads, cloudimg 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

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

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 cloudimg engineers, available 24/7 by email at support@cloudimg.co.uk 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.