Apache Unomi: Build Customer Profiles With an Open-Source CDP
Customer data platforms promise one simple thing: a single profile for each customer, built from everything they do on your site, app and in your shop. The commercial ones deliver it, at a price that scales with your audience, and with your customer data living on someone else's servers.
Apache Unomi is the open-source take, under the Apache License 2.0. The project describes itself as the reference implementation of the upcoming OASIS Context Server standard for customer data platforms. Here's what it does, who it's for, and how to set it up without the two security mistakes its quick start makes easy.
What Unomi Does
From the Unomi website, it's a Java server that manages customer, lead and visitor data:
- Profiles. One consolidated profile per person, holding both anonymous behaviour and identified details once someone logs in.
- Events and sessions. Your site or app sends events (page views, clicks, purchases, form submissions), and Unomi attaches them to the right session and profile.
- Segments. Groups defined by rules, such as "visited pricing twice this week" or "bought in the last 30 days", updated in real time.
- Scoring. Points for behaviour, with actions when a profile crosses a threshold, for example pushing a lead into your CRM.
- Privacy built in. The project highlights privacy management, including consents, designed with regulations such as GDPR in mind.
- APIs. A JSON REST API, plus GraphQL, including subscriptions in the 3.1 release.
Typical uses listed by the project: personalising website content, tracking customer journeys across web and mobile, and connecting in-store data to the same profile.
Who It's For
Be clear about this before you start: Unomi is a backend, not a finished marketing tool. There's no drag-and-drop campaign builder. You send it events through its API, and your website, app or marketing tools ask it about the visitor. It fits teams with a developer who wants profiles and segments they control, for example to drive personalisation in their own site or to feed a CRM.
If you mainly want to collect events and land them in a data warehouse, Jitsu is the simpler tool. Unomi is the one to reach for when you need live profiles and segments that your application can query.
Versions: What to Run
The current stable line is 3.1.0, released in October 2026. Unomi 3.0 moved to Elasticsearch 9 and Java 17, and the manual includes a migration path from Elasticsearch 7. Version 4.0 is in release candidate and adds multi-tenancy, with support for OpenSearch 3 as well as Elasticsearch 9.
One warning: the Docker quick start in the 3.1 manual still shows an old Unomi 2.0.0 image with Elasticsearch 7.17.5. Use the versions that match the release you're installing, not the ones in that example.
Two Things to Fix Before Going Live
The manual's own security notes point at two defaults you shouldn't keep:
1. The default credentials. The REST API and SSH console ship with karaf / karaf. Change it by setting org.apache.unomi.security.root.password in etc/unomi.custom.system.properties, or the matching setting in your deployment, before the server is reachable.
2. The third-party key and IP list. Sensitive events such as login and updateProperties are protected. They're only accepted from allowed IP addresses that send a secret key in the X-Unomi-Peer header. The default key is a published value, and the Docker example allows 0.0.0.0/0, which means anywhere. Set your own key with UNOMI_THIRDPARTY_PROVIDER1_KEY, and limit UNOMI_THIRDPARTY_PROVIDER1_IPADDRESSES to your own backend servers.
The manual adds one more rule worth following: don't call the profile endpoints from public clients. Browsers send events, and your server sends logins.
Sending Your First Event
Once Unomi is running, check it's healthy at https://your-server:9443/cxs/cluster. Then send an event to the event collector:
curl -X POST https://unomi.example.com/cxs/eventcollector \
-H 'Content-Type: application/json' \
-d '{
"sessionId": "session-123",
"events": [{
"eventType": "view",
"scope": "my-website",
"source": {"itemType": "site", "scope": "my-website", "itemId": "my-website"},
"target": {"itemType": "page", "scope": "my-website", "itemId": "pricing"}
}]
}'
To read what Unomi knows about the visitor, POST to /cxs/context.json with the same session. That's the endpoint your site uses for personalisation, while /cxs/profiles/ is meant for admin use.
Running It on Elestio
Apache Unomi is in the Elestio catalog, with backups, updates and monitoring handled for you. It runs alongside a search engine, so size the server for that, not only for Unomi. After deploying, change the default password and set your own third-party key and IP list before connecting any site. The Clone button is a good way to test a new version first.
Troubleshooting
login or updateProperties events are ignored. They're protected. Send them from an allowed IP address with the right X-Unomi-Peer key.
Unomi won't connect to Elasticsearch. Check the version. Unomi 3.x expects Elasticsearch 9, and older guides show 7.x.
Regex conditions in segments stopped matching after upgrading to 3.1. 3.1 added limits to matchesRegex. When a limit is hit, the condition returns false and logs a warning. Simplify the pattern.
Custom scripts broke after upgrading to 3.1. The default scripting allow list no longer includes org.mvel2.. Remove it from any custom value.
Profiles aren't merging after login. Send the login event from your server, not the browser, with the protected-event key.
Thanks for reading ❤️ See you in the next one 👋