This is an automated email from the ASF dual-hosted git repository.
shuber pushed a commit to branch opensearch-persistence
in repository https://gitbox.apache.org/repos/asf/unomi.git
commit 1f7e585af66e807099c040ad8f8fd01a81be020f
Author: Serge Huber <shu...@jahia.com>
AuthorDate: Mon Jan 6 09:13:33 2025 +0100
- Add support for OpenSearch in docker images
- Add docker compose support for OpenSearch
- Fix startup issues with updates to UnomiManagementService
- Documentation updates to add OpenSearch information (still to be
completed)
---
manual/src/main/asciidoc/5-min-quickstart.adoc | 119 +++++++++++++++++----
.../src/main/asciidoc/building-and-deploying.adoc | 88 ++++++++++++---
.../src/main/asciidoc/builtin-condition-types.adoc | 71 ++++++------
manual/src/main/asciidoc/configuration.adoc | 23 ++--
manual/src/main/asciidoc/getting-started.adoc | 27 +++--
.../jsonSchema/extend-an-existing-schema.adoc | 2 +-
.../main/asciidoc/queries-and-aggregations.adoc | 12 ++-
manual/src/main/asciidoc/shell-commands.adoc | 2 +-
manual/src/main/asciidoc/whats-new.adoc | 35 ++++++
manual/src/main/asciidoc/writing-plugins.adoc | 4 +-
10 files changed, 291 insertions(+), 92 deletions(-)
diff --git a/manual/src/main/asciidoc/5-min-quickstart.adoc
b/manual/src/main/asciidoc/5-min-quickstart.adoc
index a25a45dd4..c694dc503 100644
--- a/manual/src/main/asciidoc/5-min-quickstart.adoc
+++ b/manual/src/main/asciidoc/5-min-quickstart.adoc
@@ -14,32 +14,80 @@
=== Quick start with Docker
-Begin by creating a `docker-compose.yml` file with the following content:
+Begin by creating a `docker-compose.yml` file. You can choose between
ElasticSearch or OpenSearch:
-[source]
+==== Option 1: Using ElasticSearch
+
+[source,yaml]
----
version: '3.8'
services:
elasticsearch:
- image: docker.elastic.co/elasticsearch/elasticsearch:7.17.5
- environment:
- - discovery.type=single-node
- ports:
- - 9200:9200
+ image: docker.elastic.co/elasticsearch/elasticsearch:7.17.5
+ environment:
+ - discovery.type=single-node
+ ports:
+ - 9200:9200
+ unomi:
+ # Unomi version can be updated based on your needs
+ image: apache/unomi:2.0.0
+ environment:
+ - UNOMI_ELASTICSEARCH_ADDRESSES=elasticsearch:9200
+ - UNOMI_THIRDPARTY_PROVIDER1_IPADDRESSES=0.0.0.0/0,::1,127.0.0.1
+ ports:
+ - 8181:8181
+ - 9443:9443
+ - 8102:8102
+ links:
+ - elasticsearch
+ depends_on:
+ - elasticsearch
+----
+
+==== Option 2: Using OpenSearch
+
+[source,yaml]
+----
+version: '3.8'
+services:
+ opensearch-node1:
+ image: opensearchproject/opensearch:2.18.0
+ environment:
+ - cluster.name=opensearch-cluster
+ - node.name=opensearch-node1
+ - discovery.type=single-node
+ - bootstrap.memory_lock=true
+ - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m"
+ -
OPENSEARCH_INITIAL_ADMIN_PASSWORD=${OPENSEARCH_INITIAL_ADMIN_PASSWORD:-admin}
+ ulimits:
+ memlock:
+ soft: -1
+ hard: -1
+ nofile:
+ soft: 65536
+ hard: 65536
+ volumes:
+ - opensearch-data1:/usr/share/opensearch/data
+ ports:
+ - 9200:9200
+ - 9600:9600
+
unomi:
- # Unomi version can be updated based on your needs
- image: apache/unomi:2.0.0
- environment:
- - UNOMI_ELASTICSEARCH_ADDRESSES=elasticsearch:9200
- - UNOMI_THIRDPARTY_PROVIDER1_IPADDRESSES=0.0.0.0/0,::1,127.0.0.1
- ports:
- - 8181:8181
- - 9443:9443
- - 8102:8102
- links:
- - elasticsearch
- depends_on:
- - elasticsearch
+ image: apache/unomi:2.0.0
+ environment:
+ - UNOMI_AUTO_START=opensearch
+ - UNOMI_OPENSEARCH_ADDRESSES=opensearch-node1:9200
+ - UNOMI_OPENSEARCH_USERNAME=admin
+ -
UNOMI_OPENSEARCH_PASSWORD=${OPENSEARCH_INITIAL_ADMIN_PASSWORD:-admin}
+ ports:
+ - 8181:8181
+ - 9443:9443
+ - 8102:8102
+ depends_on:
+ - opensearch-node1
+
+volumes:
+ opensearch-data1:
----
From the same folder, start the environment using `docker-compose up` and wait
for the startup to complete.
@@ -48,6 +96,8 @@ Try accessing https://localhost:9443/cxs/cluster with
username/password: karaf/k
=== Quick Start manually
+==== Option 1: Using ElasticSearch
+
1) Install JDK 11
(https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
and make sure you set the
JAVA_HOME variable
https://docs.oracle.com/cd/E19182-01/820-7851/inst_cli_jdk_javahome_t/ (see our
<<JDK compatibility,Getting Started>> guide for more information on JDK
compatibility)
@@ -62,11 +112,31 @@ cluster.name: contextElasticSearch
4) Launch ElasticSearch using : `bin/elasticsearch`
+==== Option 2: Using OpenSearch
+
+1) Install JDK 11 as described above
+
+2) Download OpenSearch here: https://opensearch.org/downloads.html (please
*make sure* you use version 2.18.0)
+
+3) Uncompress it and change the `config/opensearch.yml` to include the
following config:
+
+[source,yaml]
+----
+cluster.name: opensearch-cluster
+discovery.type: single-node
+----
+
+4) Launch OpenSearch using: `bin/opensearch`
+
+==== Complete the Setup
+
5) Download Apache Unomi here : https://unomi.apache.org/download.html
6) Start it using : `./bin/karaf`
-7) Start the Apache Unomi packages using `unomi:start` in the Apache Karaf
Shell
+7) Start the Apache Unomi packages using:
+- For ElasticSearch: `unomi:start elasticsearch`
+- For OpenSearch: `unomi:start opensearch`
8) Wait for startup to complete
@@ -74,9 +144,14 @@ cluster.name: contextElasticSearch
10) Request your first context by simply accessing :
http://localhost:8181/cxs/context.js?sessionId=1234
-11) If something goes wrong, you should check the logs in
`./data/log/karaf.log`. If you get errors on ElasticSearch,
+11) If something goes wrong, you should check the logs in
`./data/log/karaf.log`. If you get errors on the search engine,
make sure you are using the proper version.
Next steps:
- Trying our integration <<Samples,samples page>>
+
+Note: When using OpenSearch, make sure to:
+- Set up proper SSL certificates or disable SSL verification for development
+- Configure the admin password via OPENSEARCH_INITIAL_ADMIN_PASSWORD
+- Enable SSL in Unomi configuration if using secure connections
diff --git a/manual/src/main/asciidoc/building-and-deploying.adoc
b/manual/src/main/asciidoc/building-and-deploying.adoc
index 840639e6e..5fb96f562 100644
--- a/manual/src/main/asciidoc/building-and-deploying.adoc
+++ b/manual/src/main/asciidoc/building-and-deploying.adoc
@@ -64,28 +64,24 @@ TIP: On a non-English Windows env, the Asciidoctor Maven
Plugin may fail to
+
. The distributions will be available under "package/target" directory.
-==== Installing an ElasticSearch server
+==== Installing a Search Engine
-Starting with version 1.2, Apache Unomi no longer embeds an ElasticSearch
server as this is no longer supported by
-the developers of ElasticSearch. Therefore you will need to install a
standalone ElasticSearch using the following steps:
+Starting with version 1.2, Apache Unomi no longer embeds a search engine
server. You will need to install either ElasticSearch or OpenSearch as a
standalone service.
-Download an ElasticSearch version. Here's the version you will need depending
-on your version of Apache Unomi.
+===== Option 1: Using ElasticSearch
-Apache Unomi <= 1.2 :
https://www.elastic.co/downloads/past-releases/elasticsearch-5-1-2[https://www.elastic.co/downloads/past-releases/elasticsearch-5-1-2]
-Apache Unomi >= 1.3 :
https://www.elastic.co/downloads/past-releases/elasticsearch-5-6-3[https://www.elastic.co/downloads/past-releases/elasticsearch-5-6-3]
-Apache Unomi >= 1.5 :
https://www.elastic.co/downloads/past-releases/elasticsearch-7-4-2[https://www.elastic.co/downloads/past-releases/elasticsearch-7-4-2]
+1. Download ElasticSearch 7.17.5 from:
https://www.elastic.co/downloads/past-releases/elasticsearch-7-17-5[https://www.elastic.co/downloads/past-releases/elasticsearch-7-17-5]
-Uncompress the downloaded package into a directory
+2. Uncompress the downloaded package into a directory
-In the config/elasticsearch.yml file, uncomment and modify the following line :
+3. In the config/elasticsearch.yml file, uncomment and modify the following
line:
-[source]
+[source,yaml]
----
cluster.name: contextElasticSearch
----
-Launch the server using
+4. Launch the server using:
[source]
----
@@ -93,10 +89,76 @@ bin/elasticsearch (Mac, Linux)
bin\elasticsearch.bat (Windows)
----
-Check that the ElasticSearch is up and running by accessing the following URL :
+===== Option 2: Using OpenSearch
+
+The recommended way to run OpenSearch is using Docker Compose:
+
+1. Create a `docker-compose.yml` file with the following content:
+
+[source,yaml]
+----
+version: '3.8'
+services:
+ opensearch-node1:
+ image: opensearchproject/opensearch:2.18.0
+ environment:
+ - cluster.name=opensearch-cluster
+ - node.name=opensearch-node1
+ - discovery.type=single-node
+ - bootstrap.memory_lock=true
+ - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m"
+ -
OPENSEARCH_INITIAL_ADMIN_PASSWORD=${OPENSEARCH_INITIAL_ADMIN_PASSWORD:-admin}
+ ulimits:
+ memlock:
+ soft: -1
+ hard: -1
+ nofile:
+ soft: 65536
+ hard: 65536
+ volumes:
+ - opensearch-data1:/usr/share/opensearch/data
+ ports:
+ - 9200:9200
+ - 9600:9600
+
+volumes:
+ opensearch-data1:
+----
+
+2. Set up your Docker host environment:
+ * **macOS & Windows**: In Docker _Preferences_ > _Resources_, set RAM to at
least 4 GB
+ * **Linux**: Ensure `vm.max_map_count` is set to at least 262144
+
+3. Start OpenSearch using:
+[source]
+----
+docker-compose up
+----
+
+===== Verify Installation
+Check that your search engine is up and running by accessing:
http://localhost:9200[http://localhost:9200]
+For OpenSearch with security enabled, you may need to use https and provide
the default credentials:
+- Username: admin
+- Password: admin (or the value of OPENSEARCH_INITIAL_ADMIN_PASSWORD if set)
+
+==== Starting Unomi
+
+After your search engine is running, you can start Unomi using the appropriate
command:
+
+[source]
+----
+# For ElasticSearch
+unomi:start elasticsearch
+
+# For OpenSearch
+unomi:start opensearch
+----
+
+NOTE: Make sure to specify which search engine you're using with the
`unomi:start` command. Using just `unomi:start` without specifying the engine
is deprecated.
+
==== Deploying the generated binary package
The "package" sub-project generates a pre-configured Apache Karaf installation
that is the simplest way to get started.
diff --git a/manual/src/main/asciidoc/builtin-condition-types.adoc
b/manual/src/main/asciidoc/builtin-condition-types.adoc
index 39e18f873..4e1acf05c 100644
--- a/manual/src/main/asciidoc/builtin-condition-types.adoc
+++ b/manual/src/main/asciidoc/builtin-condition-types.adoc
@@ -53,51 +53,58 @@ find here an overview of what a JSON condition descriptor
looks like:
}
----
-Note that condition types have two important identifiers:
+Note that condition types have three important identifiers:
-- conditionEvaluator
-- queryBuilder
+- conditionEvaluator: For real-time condition evaluation
+- queryBuilder: For building search engine queries (either ElasticSearch or
OpenSearch)
-This is because condition types can either be used to build queries or to
evaluate a condition in real time. When implementing
-a new condition type, both implementations much be provided. Here's an example
an OSGi Blueprint registration for the
-above condition type descriptor:
+This is because condition types can be used in three ways:
+1. To evaluate a condition in real time
+2. To build ElasticSearch queries
+3. To build OpenSearch queries
-From
https://github.com/apache/unomi/blob/master/plugins/baseplugin/src/main/resources/OSGI-INF/blueprint/blueprint.xml
+When implementing a new condition type, you need to provide implementations
for each use case. Here's an example of OSGi Blueprint registrations for the
above condition type descriptor:
[source,xml]
----
-...
- <service
-
interface="org.apache.unomi.persistence.elasticsearch.ConditionESQueryBuilder">
- <service-properties>
- <entry key="queryBuilderId"
value="booleanConditionESQueryBuilder"/>
- </service-properties>
- <bean
class="conditions.org.apache.unomi.persistence.elasticsearch.BooleanConditionESQueryBuilder"/>
- </service>
-...
- <!-- Condition evaluators -->
- <service
interface="org.apache.unomi.persistence.spi.conditions.ConditionEvaluator">
- <service-properties>
- <entry key="conditionEvaluatorId"
value="booleanConditionEvaluator"/>
- </service-properties>
- <bean
class="org.apache.unomi.plugins.baseplugin.conditions.BooleanConditionEvaluator"/>
- </service>
-...
+<!-- ElasticSearch Query Builder -->
+<service
interface="org.apache.unomi.persistence.elasticsearch.ConditionESQueryBuilder">
+ <service-properties>
+ <entry key="queryBuilderId" value="booleanConditionESQueryBuilder"/>
+ </service-properties>
+ <bean
class="org.apache.unomi.persistence.elasticsearch.BooleanConditionESQueryBuilder"/>
+</service>
+
+<!-- OpenSearch Query Builder -->
+<service
interface="org.apache.unomi.persistence.opensearch.ConditionOSQueryBuilder">
+ <service-properties>
+ <entry key="queryBuilderId" value="booleanConditionOSQueryBuilder"/>
+ </service-properties>
+ <bean
class="org.apache.unomi.persistence.opensearch.BooleanConditionOSQueryBuilder"/>
+</service>
+
+<!-- Condition Evaluator (shared between both engines) -->
+<service
interface="org.apache.unomi.persistence.spi.conditions.ConditionEvaluator">
+ <service-properties>
+ <entry key="conditionEvaluatorId" value="booleanConditionEvaluator"/>
+ </service-properties>
+ <bean
class="org.apache.unomi.plugins.baseplugin.conditions.BooleanConditionEvaluator"/>
+</service>
----
-As you can see two Java classes are used to build a single condition type. You
don't need to understand all these details in
-order to use condition types, but this might be interesting to know if you're
interested in building your own condition
-type implementations. For more details on building your own custom
plugins/extensions, please refer to the corresponding
-sections.
+As you can see, three Java classes are used to build a single condition type:
+1. A condition evaluator (shared)
+2. An ElasticSearch query builder
+3. An OpenSearch query builder
+
+You don't need to understand all these details to use condition types, but
this might be interesting if you're building your own condition type
implementations. For more details on building custom plugins/extensions with
search engine specific implementations, please refer to the corresponding
sections.
==== Existing condition type descriptors
-Here is a non-exhaustive list of condition types built into Apache Unomi. Feel
free to browse the source code if you want to
-discover more. But the list below should get you started with the most useful
conditions:
+Here is a non-exhaustive list of condition types built into Apache Unomi. Feel
free to browse the source code if you want to discover more. The list below
should get you started with the most useful conditions:
-
https://github.com/apache/unomi/tree/master/plugins/baseplugin/src/main/resources/META-INF/cxs/conditions
Of course it is also possible to build your own custom condition types by
developing custom Unomi plugins/extensions.
-You will also note that some condition types can re-use a `parentCondition`.
This is a way to inherit from another condition
-type to make them more specific.
+You will also note that some condition types can re-use a `parentCondition`.
This is a way to inherit from another condition type to make them more specific.
diff --git a/manual/src/main/asciidoc/configuration.adoc
b/manual/src/main/asciidoc/configuration.adoc
index 0eca5c6e3..37db0e8b0 100644
--- a/manual/src/main/asciidoc/configuration.adoc
+++ b/manual/src/main/asciidoc/configuration.adoc
@@ -93,20 +93,27 @@ org.apache.unomi.opensearch.cluster.name=opensearch-cluster
# Note: the port number must be repeated for each host.
org.apache.unomi.opensearch.addresses=localhost:9200
-# OpenSearch security settings (if needed)
-org.apache.unomi.opensearch.ssl.enable=false
-org.apache.unomi.opensearch.username=
-org.apache.unomi.opensearch.password=
+# OpenSearch security settings (required by default since OpenSearch 2.0)
+org.apache.unomi.opensearch.ssl.enable=true
+org.apache.unomi.opensearch.username=admin
+org.apache.unomi.opensearch.password=${env:OPENSEARCH_INITIAL_ADMIN_PASSWORD:-admin}
+org.apache.unomi.opensearch.sslTrustAllCertificates=true
----
To select which search engine to use, you can:
1. Use the appropriate configuration properties above
2. When building from source, use the appropriate Maven profile:
* For ElasticSearch (default): no special profile needed
- * For OpenSearch: add `-P opensearch` to your Maven command
-
-Note: When using OpenSearch 2.18, you might see log messages about "QueryGroup
_id can't be null". This is a known issue
-that doesn't affect functionality and is being tracked at:
https://github.com/opensearch-project/OpenSearch/issues/16874
+ * For OpenSearch: add `-Duse.opensearch=true` to your Maven command
+3. When using Docker:
+ * For ElasticSearch: use `UNOMI_AUTO_START=elasticsearch`
+ * For OpenSearch: use `UNOMI_AUTO_START=opensearch`
+
+Note: When using OpenSearch 2.18:
+- Security is enabled by default and requires SSL/TLS
+- The default admin username is 'admin'
+- The initial admin password can be set via OPENSEARCH_INITIAL_ADMIN_PASSWORD
environment variable
+- You might see log messages about "QueryGroup _id can't be null". This is a
known issue that doesn't affect functionality and is being tracked at:
https://github.com/opensearch-project/OpenSearch/issues/16874
=== Secured events configuration
diff --git a/manual/src/main/asciidoc/getting-started.adoc
b/manual/src/main/asciidoc/getting-started.adoc
index 8e16ab092..f27c1209b 100644
--- a/manual/src/main/asciidoc/getting-started.adoc
+++ b/manual/src/main/asciidoc/getting-started.adoc
@@ -31,19 +31,27 @@ Also, as there are new licensing restrictions on JDKs
provided by Oracle for pro
added support for OpenJDK builds. Other JDK distributions might also work but
are not regularly tested so you should use
them at your own risks.
-===== ElasticSearch compatibility
+===== Search Engine Compatibility
-Starting with version 2.0.0 Apache Unomi adds compatibility with ElasticSearch
7.17.5 . It is highly recommended to use the
-ElasticSearch version specified in the documentation whenever possible. If in
doubt, don't hesitate to check with the Apache Unomi community
-to get the latest information about ElasticSearch version compatibility.
+Apache Unomi supports two search engine backends:
+
+* *ElasticSearch*: Version 7.17.5 is supported starting with Unomi 2.0.0
+* *OpenSearch*: Version 2.18.0 is supported
+
+It is highly recommended to use the versions specified in the documentation.
When in doubt, consult the Apache Unomi community
+for the latest compatibility information.
+
+Note for OpenSearch users:
+- Security is enabled by default and requires SSL/TLS
+- Default admin credentials are required (username: admin)
+- The initial admin password can be configured via environment variable
==== Running Unomi
===== Start Unomi
Start Unomi according to the <<Five Minutes QuickStart,quick start with
docker>> or by compiling using the
-<<Building,building instructions>>. Once you have Karaf running,
- you should wait until you see the following messages on the Karaf console:
+<<Building,building instructions>>. Once you have Karaf running, you should
wait until you see the following messages on the Karaf console:
[source]
----
@@ -57,10 +65,11 @@ Initializing profile service endpoint...
Initializing cluster service endpoint...
----
-This indicates that all the Unomi services are started and ready to react to
requests. You can then open a browser and go to `http://localhost:8181/cxs` to
see the list of
-available RESTful services or retrieve an initial context at
`http://localhost:8181/cxs/context.json` (which isn't very useful at this
point).
+This indicates that all the Unomi services are started and ready to react to
requests. You can then:
-You can now find an introduction page at the following location:
http://localhost:8181
+1. Access the RESTful services list: `http://localhost:8181/cxs`
+2. Retrieve an initial context: `http://localhost:8181/cxs/context.json`
+3. View the introduction page: `http://localhost:8181`
Also now that your service is up and running you can go look at the
<<Request examples,request examples>> to learn basic
diff --git a/manual/src/main/asciidoc/jsonSchema/extend-an-existing-schema.adoc
b/manual/src/main/asciidoc/jsonSchema/extend-an-existing-schema.adoc
index d82501f97..17fa7916c 100644
--- a/manual/src/main/asciidoc/jsonSchema/extend-an-existing-schema.adoc
+++ b/manual/src/main/asciidoc/jsonSchema/extend-an-existing-schema.adoc
@@ -27,7 +27,7 @@ This means that if your events include additional properties,
you will need exte
An extension schema is a JSON schema whose id will be overridden and be
defined by a keyword named *extends* in the *self* part of the extension.
-When sending an extension through the API, it will be persisted in
Elasticsearch then will be merged to the targeted schema.
+When sending an extension through the API, it will be persisted in the search
engine then will be merged to the targeted schema.
What does “merge a schema” mean?
The merge will simply add in the *allOf* keyword of the targeted schema a
reference to the extensions.
diff --git a/manual/src/main/asciidoc/queries-and-aggregations.adoc
b/manual/src/main/asciidoc/queries-and-aggregations.adoc
index 269ef1d30..c7c25b9d7 100644
--- a/manual/src/main/asciidoc/queries-and-aggregations.adoc
+++ b/manual/src/main/asciidoc/queries-and-aggregations.adoc
@@ -20,7 +20,7 @@ In this section we will show examples of requests that may be
built using this A
Query counts are highly optimized queries that will count the number of
objects that match a certain condition without
retrieving the results. This can be used for example to quickly figure out how
many objects will match a given condition
-before actually retrieving the results. It uses ElasticSearch/Lucene
optimizations to avoid the cost of loading all the
+before actually retrieving the results. It uses search engine optimizations
(ElasticSearch/OpenSearch) to avoid the cost of loading all the
resulting objects.
Here's an example of a query:
@@ -72,6 +72,8 @@ Metric queries make it possible to apply functions to the
resulting property. Th
- min
- max
+These metrics are supported by both ElasticSearch and OpenSearch backends.
+
It is also possible to request more than one metric in a single request by
concatenating them with a "/" in the URL.
Here's an example request that uses the `sum` and `avg` metrics:
@@ -116,7 +118,7 @@ The result will look something like this:
Aggregations are a very powerful way to build queries in Apache Unomi that
will collect and aggregate data by filtering
on certain conditions.
-Aggregations are composed of :
+Aggregations are composed of:
- an object type and a property on which to aggregate
- an aggregation setup (how data will be aggregated, by date, by numeric
range, date range or ip range)
- a condition (used to filter the data set that will be aggregated)
@@ -127,8 +129,10 @@ Aggregations may be of different types. They are listed
here below.
===== Date
-Date aggregations make it possible to automatically generate "buckets" by time
periods. For more information about the
-format, it is directly inherited from ElasticSearch and you may find it here:
https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-aggregations-bucket-datehistogram-aggregation.html
+Date aggregations make it possible to automatically generate "buckets" by time
periods. The format is compatible with both ElasticSearch and OpenSearch.
+For more information about the format, you can refer to:
+- ElasticSearch documentation:
https://www.elastic.co/guide/en/elasticsearch/reference/7.17/search-aggregations-bucket-datehistogram-aggregation.html
+- OpenSearch documentation:
https://opensearch.org/docs/2.11/aggregations/bucket/datehistogram/
Here's an example of a request to retrieve a histogram of by day of all the
session that have been create by newcomers (nbOfVisits=1)
diff --git a/manual/src/main/asciidoc/shell-commands.adoc
b/manual/src/main/asciidoc/shell-commands.adoc
index 2de339d38..29a98baf6 100644
--- a/manual/src/main/asciidoc/shell-commands.adoc
+++ b/manual/src/main/asciidoc/shell-commands.adoc
@@ -67,7 +67,7 @@ The commands control the lifecycle of the Apache Unomi server
and are used to mi
|migrate
|fromVersion
-|This command must be used only when the Apache Unomi application is NOT
STARTED. It will perform migration of the data stored in ElasticSearch using
the argument fromVersion as a starting point.
+|This command must be used only when the Apache Unomi application is NOT
STARTED. It will perform migration of the data stored in search engine using
the argument fromVersion as a starting point.
|stop
|n/a
diff --git a/manual/src/main/asciidoc/whats-new.adoc
b/manual/src/main/asciidoc/whats-new.adoc
index 7efb0e4ff..d9823f2ae 100644
--- a/manual/src/main/asciidoc/whats-new.adoc
+++ b/manual/src/main/asciidoc/whats-new.adoc
@@ -175,3 +175,38 @@ This version increase is releated to Apache Unomi 2.0
makeing use of a new Elast
called
https://www.elastic.co/guide/en/elasticsearch/reference/7.17/flattened.html[Flattened],
and although it was available in prior versions of Elasticsearch, we do not
recommend using those
due to the above-mentioned log4j vulnerabilities.
+
+==== OpenSearch Support
+
+Starting with version 2.7.0, Apache Unomi now officially supports OpenSearch
2.18.0 as an alternative to Elasticsearch. This addition gives users more
flexibility in choosing their search engine backend. Key features include:
+
+- Full support for OpenSearch 2.18.0
+- Seamless integration with existing Unomi features
+- Support for security features enabled by default in OpenSearch
+- Compatible with both standalone and Docker deployments
+
+===== Configuration Options
+
+Users can choose between ElasticSearch and OpenSearch through various
configuration methods:
+
+1. Using configuration properties
+2. Using Maven profiles during build
+3. Using Docker environment variables
+
+For detailed configuration instructions, see the <<Configuration,configuration
section>>.
+
+===== Security Considerations
+
+When using OpenSearch:
+- Security is enabled by default and requires SSL/TLS
+- Default admin credentials are required
+- The initial admin password can be configured via environment variables
+
+===== Migration Notes
+
+For users wanting to migrate from ElasticSearch to OpenSearch:
+- Data migration requires a full cluster shutdown
+- All existing features, including the flattened field type, are supported
+- Existing queries and aggregations work seamlessly with both backends
+
+For detailed migration instructions, refer to the <<Migrations,migration
guide>>.
diff --git a/manual/src/main/asciidoc/writing-plugins.adoc
b/manual/src/main/asciidoc/writing-plugins.adoc
index 664192608..34a9e8b45 100644
--- a/manual/src/main/asciidoc/writing-plugins.adoc
+++ b/manual/src/main/asciidoc/writing-plugins.adoc
@@ -715,7 +715,7 @@ OSGi Service Registration for ElasticSearch (elasticsearch
bundle's blueprint.xm
<blueprint>
<!-- Common services -->
<reference id="persistenceService"
interface="org.apache.unomi.api.services.PersistenceService"/>
-
+
<!-- Register the query builder -->
<service
interface="org.apache.unomi.persistence.elasticsearch.ConditionESQueryBuilder">
<service-properties>
@@ -734,7 +734,7 @@ OSGi Service Registration for OpenSearch (opensearch
bundle's blueprint.xml):
<blueprint>
<!-- Common services -->
<reference id="persistenceService"
interface="org.apache.unomi.api.services.PersistenceService"/>
-
+
<!-- Register the query builder -->
<service
interface="org.apache.unomi.persistence.opensearch.ConditionOSQueryBuilder">
<service-properties>
