This is an automated email from the ASF dual-hosted git repository.
sergehuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/unomi.git
The following commit(s) were added to refs/heads/master by this push:
new 16c1724c6 Update manual and README branding from Unomi 3.x to 4.x
(#945)
16c1724c6 is described below
commit 16c1724c654ceeca1059e3a55ac97c68b58ee267
Author: Serge Huber <[email protected]>
AuthorDate: Tue Nov 3 06:26:47 2026 +0100
Update manual and README branding from Unomi 3.x to 4.x (#945)
Co-authored-by: Claude Opus 5.5 <[email protected]>
---
README.md | 4 ++--
manual/src/main/asciidoc/building-and-deploying.adoc | 6 +++---
manual/src/main/asciidoc/configuration.adoc | 8 +++++---
manual/src/main/asciidoc/datamodel.adoc | 1 +
manual/src/main/asciidoc/foreword.adoc | 4 ++--
manual/src/main/asciidoc/index.adoc | 4 ++--
manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc | 3 ++-
manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc | 2 +-
manual/src/main/asciidoc/scheduler.adoc | 1 +
manual/src/main/asciidoc/shell-commands.adoc | 2 +-
10 files changed, 20 insertions(+), 15 deletions(-)
diff --git a/README.md b/README.md
index 8346fa21c..5ad1e538a 100644
--- a/README.md
+++ b/README.md
@@ -40,9 +40,9 @@ compile and be stable. These are recommended for users that
prefer to work from
packaged binaries on the [Apache Unomi website](https://unomi.apache.org).
-Apache Unomi 3.x
+Apache Unomi 4.x
--------------
-Unomi 3.0+ requires **Java 17**, **Karaf 4.4**, and **Elasticsearch 9.x**.
Unomi 4.0 adds **multi-tenancy**, **OpenSearch 3** support, a cluster-aware
**task scheduler**, and persistence-based clustering.
+Unomi 4.x requires **Java 17**, **Karaf 4.4**, and **Elasticsearch 9.x** or
**OpenSearch 3**. It adds **multi-tenancy**, a cluster-aware **task
scheduler**, and persistence-based clustering on top of the 3.x platform.
* Build and run: see `manual/src/main/asciidoc/building-and-deploying.adoc` or
`manual/src/main/asciidoc/5-min-quickstart.adoc`
* Docker: see `docker/README.md`
diff --git a/manual/src/main/asciidoc/building-and-deploying.adoc
b/manual/src/main/asciidoc/building-and-deploying.adoc
index be6d99452..a56ef8e31 100644
--- a/manual/src/main/asciidoc/building-and-deploying.adoc
+++ b/manual/src/main/asciidoc/building-and-deploying.adoc
@@ -15,7 +15,7 @@
[#_building]
=== Building
-Apache Unomi 3.x provides a convenient `build.sh` script that simplifies the
build process with
+Apache Unomi 4.x provides a convenient `build.sh` script that simplifies the
build process with
enhanced error handling, preflight validation, and deployment options. See the
<<_using_the_build_script,Using the build.sh script>> section below for
details. Alternatively, you can build using Maven
directly as described in this section.
@@ -75,7 +75,7 @@ TIP: On a non-English Windows env, the Asciidoctor Maven
Plugin may fail to
[#_using_the_build_script]
==== Using the build.sh script
-Apache Unomi 3.x provides a unified `build.sh` script that simplifies the
build, deployment, and execution process.
+Apache Unomi 4.x provides a unified `build.sh` script that simplifies the
build, deployment, and execution process.
This script replaces multiple legacy build scripts and provides enhanced error
handling, colorized output, and
comprehensive environment validation.
@@ -240,7 +240,7 @@ To merge the branch into master.
==== Installing a Search Engine
-Apache Unomi 3.x does not embed a search engine. Install Elasticsearch 9.x or
OpenSearch 3.x as a standalone service. See <<_migrate_from_2_x_to_3_0,Migrate
from 2.x to 3.0>> for version requirements.
+Apache Unomi 4.x does not embed a search engine. Install Elasticsearch 9.x or
OpenSearch 3.x as a standalone service. See <<_migrate_from_2_x_to_3_0,Migrate
from 2.x to 3.0>> and <<_migrate_from_3_0_to_4_0,Migrate from 3.0 to 4.0>> for
version requirements.
===== Option 1: Using Elasticsearch
diff --git a/manual/src/main/asciidoc/configuration.adoc
b/manual/src/main/asciidoc/configuration.adoc
index b5de02ecf..4aa8c00b8 100644
--- a/manual/src/main/asciidoc/configuration.adoc
+++ b/manual/src/main/asciidoc/configuration.adoc
@@ -43,6 +43,7 @@ Docker Compose you can put the environment variables in the
docker-compose.yml f
If you want to "save" the environment values in a file, you can use the
`bin/setenv(.bat)` to setup the environment
variables you want to use.
+[#_changing_the_default_configuration_using_property_files]
=== Changing the default configuration using property files
If you want to change the default configuration using property files instead
of environment variables, you can perform
@@ -283,6 +284,7 @@ import should start right away.
Otherwise, import should start at the next startup. Import runs in background,
but can take about 15 minutes.
At the end, you should have about 4 million entries in the geonames index.
+[#_rest_api_security]
=== REST API Security
The Apache Unomi Context Server REST API is protected using JAAS
authentication and using Basic or Digest HTTP auth.
@@ -1370,7 +1372,7 @@ If a reverse proxy terminates TLS in front of Unomi, the
request Unomi sees is p
* the proxy's address is listed in `org.apache.unomi.ip.trustedProxies`
(`UNOMI_IP_TRUSTED_PROXIES`). The default list covers every private address
range; narrow it to your proxies, or any host on those networks can claim HTTPS.
* the proxy sends `X-Forwarded-Proto: https`. Configure it to overwrite the
header: if any listed protocol is not `https`, the request is treated as plain
HTTP.
-Changing `org.apache.unomi.ip.trustedProxies` in `custom.system.properties`
needs a restart. The setting does not apply to `X-Unomi-Peer` keys in
<<_single_tenant_compatibility_mode,single-tenant compatibility mode>>, which
keep their Unomi 3.0 behaviour, nor to merges Unomi runs itself outside an HTTP
request.
+Changing `org.apache.unomi.ip.trustedProxies` in `custom.system.properties`
needs a restart. The setting does not apply to `X-Unomi-Peer` keys in
<<_v2_compatibility_mode,single-tenant compatibility mode>>, which keep their
Unomi 3.0 behaviour, nor to merges Unomi runs itself outside an HTTP request.
==== Troubleshooting profile merges
@@ -1594,7 +1596,7 @@ shell commands in the "Shell commands" section of the
documentation.
=== Search engine authentication and security
-Apache Unomi 3.x talks to **Elasticsearch 9** or **OpenSearch 3** using the
settings below. Prefer `etc/custom.system.properties` (or
`unomi.custom.system.properties` / environment variables). The persistence OSGi
configs (`etc/org.apache.unomi.persistence.elasticsearch.cfg` /
`...opensearch.cfg`) expose the same values as short keys (`username`,
`password`, `sslEnable`, `sslTrustAllCertificates`) that resolve from those
system properties.
+Apache Unomi 4.x talks to **Elasticsearch 9** or **OpenSearch 3** using the
settings below. Prefer `etc/custom.system.properties` (or
`unomi.custom.system.properties` / environment variables). The persistence OSGi
configs (`etc/org.apache.unomi.persistence.elasticsearch.cfg` /
`...opensearch.cfg`) expose the same values as short keys (`username`,
`password`, `sslEnable`, `sslTrustAllCertificates`) that resolve from those
system properties.
Elasticsearch security reference:
https://www.elastic.co/guide/en/elasticsearch/reference/current/security-minimal-setup.html[Elasticsearch
security].
OpenSearch security reference:
https://docs.opensearch.org/docs/latest/security/[OpenSearch Security].
@@ -2077,7 +2079,7 @@ public interface HealthCheckProvider {
Calls to provider are supposed to be done at a regular rate (every 15 seconds
for example) and should be fast to execute. Feel free to include any caching
strategy if needed.
-===== Health check for another persistence backend
+==== Health check for another persistence backend
A persistence backend that is not packaged with Unomi (PostgreSQL, for
example) integrates with the health check the same way as Elasticsearch and
OpenSearch:
diff --git a/manual/src/main/asciidoc/datamodel.adoc
b/manual/src/main/asciidoc/datamodel.adoc
index 947f71172..87cb41661 100755
--- a/manual/src/main/asciidoc/datamodel.adoc
+++ b/manual/src/main/asciidoc/datamodel.adoc
@@ -251,6 +251,7 @@ In the following example, the scope uses the unique
identifier of a web site cal
}
----
+[#_item]
=== Item
Unomi structures the information it collects using the concept of `Item` which
provides the base information (an identifier and a type) the context server
needs to process and store the data.
diff --git a/manual/src/main/asciidoc/foreword.adoc
b/manual/src/main/asciidoc/foreword.adoc
index 2e8767a29..b2d7e2bbf 100644
--- a/manual/src/main/asciidoc/foreword.adoc
+++ b/manual/src/main/asciidoc/foreword.adoc
@@ -15,7 +15,7 @@
[#_foreword]
== Foreword
-This documentation provides a comprehensive guide to Apache Unomi 3.x, a
powerful and flexible Customer Data Platform (CDP) that enables organizations
to collect, manage, and leverage customer data for personalization and
marketing automation.
+This documentation provides a comprehensive guide to Apache Unomi 4.x, a
powerful and flexible Customer Data Platform (CDP) that enables organizations
to collect, manage, and leverage customer data for personalization and
marketing automation.
Apache Unomi is built on open standards and provides a robust foundation for
building customer-centric applications. Whether you're implementing
personalization, running marketing campaigns, or building customer profiles,
this documentation will help you understand and effectively use Apache Unomi's
capabilities.
@@ -25,4 +25,4 @@ The Apache Unomi community is committed to providing
comprehensive, accurate, an
Happy reading!
-This edition documents Apache Unomi 3.x, which requires Java 17, Elasticsearch
9.x or OpenSearch 3.x, and (from 4.0) tenant API keys for public endpoints.
+This edition documents Apache Unomi 4.x, which requires Java 17, Elasticsearch
9.x or OpenSearch 3.x, and tenant API keys for public endpoints.
diff --git a/manual/src/main/asciidoc/index.adoc
b/manual/src/main/asciidoc/index.adoc
index 36bf630d0..d31b5ec0e 100644
--- a/manual/src/main/asciidoc/index.adoc
+++ b/manual/src/main/asciidoc/index.adoc
@@ -12,7 +12,7 @@
// limitations under the License.
//
-= Apache Unomi 3.x - Documentation
+= Apache Unomi 4.x - Documentation
Apache Software Foundation
:doctype: book
:toc: left
@@ -60,7 +60,7 @@ ifndef::backend-pdf[]
Apache Unomi™
++++
-<h1 class="display-title">Apache Unomi 3.x<br><span
class="text-hero-accent">Documentation</span></h1>
+<h1 class="display-title">Apache Unomi 4.x<br><span
class="text-hero-accent">Documentation</span></h1>
++++
[.cover-meta.lead]
diff --git a/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc
b/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc
index 4cc2fac83..32267c552 100644
--- a/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc
+++ b/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc
@@ -23,6 +23,7 @@ The key innovation in 4.0 is the introduction of **tenant
isolation** for all da
- **Tenant-specific API keys** for secure access control
- **Backward compatibility** with system administrator access for management
operations
+[#_updating_applications_consuming_unomi]
=== Updating applications consuming Unomi
==== Authentication Model Changes
@@ -325,7 +326,7 @@ the segment and scoring lists itself instead of leaving it
to the search engine.
Paging and sorting follow the 3.0 rules:
* `offset` and `limit` page the merged list. A missing `limit` returns
`defaultQueryLimit` items, 10 unless
- configured (see
<<changing_the_default_configuration_using_property_files,the search engine
configuration>>), and `-1` returns every item.
+ configured (see
<<_changing_the_default_configuration_using_property_files,the search engine
configuration>>), and `-1` returns every item.
The response echoes the requested `offset` and `limit`.
* `sortby` takes the same syntax: comma-separated `field` or `field:desc`
criteria. Any criterion other than an
exact `:desc` suffix sorts ascending.
diff --git a/manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc
b/manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc
index 38f4eff9d..8da500ef1 100644
--- a/manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc
+++ b/manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc
@@ -15,7 +15,7 @@
[#_v2_compatibility_mode]
=== single-tenant compatibility mode
-[[_single_tenant_compatibility_mode]]This document explains how to use
single-tenant compatibility mode in Apache Unomi 4.0. The mode lets client
applications
+This document explains how to use single-tenant compatibility mode in Apache
Unomi 4.0. The mode lets client applications
written for Unomi 2.x or Unomi 3.x keep working without tenant API keys while
you move them to the 4.0 authentication model.
==== Overview
diff --git a/manual/src/main/asciidoc/scheduler.adoc
b/manual/src/main/asciidoc/scheduler.adoc
index d42806766..4e4881ad3 100644
--- a/manual/src/main/asciidoc/scheduler.adoc
+++ b/manual/src/main/asciidoc/scheduler.adoc
@@ -357,6 +357,7 @@ moment shutdown begins and held locks age out normally for
peers to recover. And
`COMPLETED` / `FAILED` write, the heartbeat is stopped (waiting out any
in-flight tick) so a late renewal
cannot invalidate the terminal compare-and-set.
+[#_renewal_timing_limits_with_the_default_1_s_refresh_interval]
===== Renewal timing limits with the default 1 s refresh interval
Renewal is safe with the ES/OS default index refresh batching
(`refresh_interval` = 1 s) because none of
diff --git a/manual/src/main/asciidoc/shell-commands.adoc
b/manual/src/main/asciidoc/shell-commands.adoc
index bd25cef41..6a4a216df 100644
--- a/manual/src/main/asciidoc/shell-commands.adoc
+++ b/manual/src/main/asciidoc/shell-commands.adoc
@@ -26,7 +26,7 @@ You can connect to the Apache Karaf SSH Shell using the
following command:
ssh -p 8102 karaf@localhost
-Authenticate with the `karaf` user and the password from `UNOMI_ROOT_PASSWORD`
(Unomi does not ship a known default password). Set the password before start;
see <<_getting_started,Getting started>> and
<<_client_facing_hardening_4_0,client-facing hardening>>.
+Authenticate with the `karaf` user and the password from `UNOMI_ROOT_PASSWORD`
(Unomi does not ship a known default password). Set the password before start;
see <<_getting_started_with_unomi,Getting started>> and
<<_client_facing_hardening_4_0,client-facing hardening>>.
Once connected you can simply type in :
