UNOMI-969: Brand PlantUML diagrams with Unomi theme colors

manual/pom.xml

@@ -33,8 +33,9 @@
         <doc.output.html>target/generated-docs/html/latest</doc.output.html>
         <doc.output.pdf>target/generated-docs/pdf/latest</doc.output.pdf>
         <doc.version>${project.version}</doc.version>
-        <!-- Default path to GraphViz dot executable, can be overridden via -Dgraphviz.dot.path=/path/to/dot -->
-        <graphviz.dot.path>${env.GRAPHVIZ_DOT}</graphviz.dot.path>
+        <!-- Prefer PATH (`dot`). Do not default to ${env.GRAPHVIZ_DOT}: when unset it
+             becomes "", and PlantUML treats that as the process cwd (a directory). -->
+        <graphviz.dot.path>dot</graphviz.dot.path>
     </properties>
 
     <build>
@@ -72,9 +73,6 @@
                             <requires>
                                 <require>asciidoctor-diagram</require>
                             </requires>
-                            <attributes>
-                                <graphvizdot>${graphviz.dot.path}</graphvizdot>
-                            </attributes>
                             <sourceDocumentName>index.adoc</sourceDocumentName>
                             <sourceDirectory>${doc.source}</sourceDirectory>
                             <outputDirectory>${doc.output.html}</outputDirectory>
@@ -89,6 +87,8 @@
                                 <source-highlighter>highlightjs</source-highlighter>
                                 <revnumber>${project.version}</revnumber>
                                 <project-version>${project.version}</project-version>
+                                <graphvizdot>${graphviz.dot.path}</graphvizdot>
+                                <plantuml-config>${project.basedir}/src/main/asciidoc/plantuml/unomi-theme.puml</plantuml-config>
                             </attributes>
                         </configuration>
                     </execution>
@@ -122,6 +122,8 @@
                                 <idprefix />
                                 <idseparator>_</idseparator>
                                 <sectnums>true</sectnums>
+                                <graphvizdot>${graphviz.dot.path}</graphvizdot>
+                                <plantuml-config>${project.basedir}/src/main/asciidoc/plantuml/unomi-theme.puml</plantuml-config>
                             </attributes>
                         </configuration>
                     </execution>
@@ -207,6 +209,18 @@
     </build>
 
     <profiles>
+        <!-- Honor GRAPHVIZ_DOT when set (see building-and-deploying.adoc); leave default `dot` otherwise. -->
+        <profile>
+            <id>graphviz-from-env</id>
+            <activation>
+                <property>
+                    <name>env.GRAPHVIZ_DOT</name>
+                </property>
+            </activation>
+            <properties>
+                <graphviz.dot.path>${env.GRAPHVIZ_DOT}</graphviz.dot.path>
+            </properties>
+        </profile>
         <profile>
             <id>generate-documentation-bundle</id>
             <activation>

manual/src/main/asciidoc/5-min-quickstart.adoc

@@ -15,9 +15,9 @@
 [#_five_minutes_quickstart]
 === Quick start with Docker
 
-Begin by creating a `docker-compose.yml` file. You can choose between ElasticSearch or OpenSearch:
+Begin by creating a `docker-compose.yml` file. You can choose between Elasticsearch or OpenSearch:
 
-==== Option 1: Using ElasticSearch
+==== Option 1: Using Elasticsearch
 
 [source,yaml]
 ----
@@ -52,14 +52,14 @@ services:
 version: '3.8'
 services:
     opensearch-node1:
-        image: opensearchproject/opensearch:3
+        image: opensearchproject/opensearch:3.7.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}
+            - OPENSEARCH_INITIAL_ADMIN_PASSWORD=${OPENSEARCH_INITIAL_ADMIN_PASSWORD:-MyStrongPassw0rd!}
         ulimits:
             memlock:
                 soft: -1
@@ -79,7 +79,10 @@ services:
             - UNOMI_DISTRIBUTION=unomi-distribution-opensearch
             - UNOMI_OPENSEARCH_ADDRESSES=opensearch-node1:9200
             - UNOMI_OPENSEARCH_USERNAME=admin
-            - UNOMI_OPENSEARCH_PASSWORD=${OPENSEARCH_INITIAL_ADMIN_PASSWORD:-admin}
+            - UNOMI_OPENSEARCH_PASSWORD=${OPENSEARCH_INITIAL_ADMIN_PASSWORD:-MyStrongPassw0rd!}
+            # Package default sslEnable is true; trust-all matches typical local OpenSearch Docker TLS
+            - UNOMI_OPENSEARCH_SSL_ENABLE=true
+            - UNOMI_OPENSEARCH_SSL_TRUST_ALL_CERTIFICATES=true
             - UNOMI_HEALTHCHECK_PROVIDERS=cluster,opensearch,unomi,persistence
         ports:
             - 8181:8181
@@ -94,9 +97,9 @@ volumes:
 
 From the same folder, start the environment using `docker-compose up` and wait for the startup to complete.
 
-==== After startup (ElasticSearch Docker path)
+==== After startup (Elasticsearch Docker path)
 
-Once Unomi is running, create a tenant and save the API keys from the response:
+Once Unomi is running, create a tenant, then **regenerate** API keys and save the `plainTextKey` values from those responses (tenant create only returns masked keys):
 
 [source,bash]
 ----
@@ -110,6 +113,9 @@ curl -X POST http://localhost:8181/cxs/tenants \
       "description": "Default tenant for quick start"
     }
   }'
+
+curl -X POST "http://localhost:8181/cxs/tenants/default/apikeys?type=PUBLIC" --user karaf:karaf
+curl -X POST "http://localhost:8181/cxs/tenants/default/apikeys?type=PRIVATE" --user karaf:karaf
 ----
 
 Use the public API key in `X-Unomi-Api-Key` for `/cxs/context.json` requests. See <<_multitenancy,Multi-tenancy>>.
@@ -118,26 +124,26 @@ Try accessing https://localhost:9443/cxs/cluster with username/password: karaf/k
 
 === Quick Start manually
 
-==== Option 1: Using ElasticSearch
+==== Option 1: Using Elasticsearch
 
 1) Install JDK 17 and make sure you set the JAVA_HOME variable (see our <<_jdk_compatibility,Getting Started>> guide for more information on JDK compatibility)
 
-2) Download ElasticSearch here : https://www.elastic.co/downloads/past-releases/elasticsearch-9-4-3 (please *make sure* you use the proper version : 9.4.3)
+2) Download Elasticsearch here : https://www.elastic.co/downloads/past-releases/elasticsearch-9-4-3 (please *make sure* you use the proper version : 9.4.3)
 
 3) Uncompress it and change the `config/elasticsearch.yml` to include the following config :
 
 [source,yaml]
 ----
-cluster.name: contextElasticSearch
+cluster.name: contextElasticsearch
 ----
 
-4) Launch ElasticSearch using : `bin/elasticsearch`
+4) Launch Elasticsearch using : `bin/elasticsearch`
 
 ==== Option 2: Using OpenSearch
 
 1) Install JDK 17 as described above
 
-2) Download OpenSearch here: https://opensearch.org/downloads.html (please *make sure* you use version 3.x)
+2) Download OpenSearch here: https://opensearch.org/downloads.html (please *make sure* you use version **3.7.0**, matching `opensearch.version` in the Unomi root POM)
 
 3) Uncompress it and change the `config/opensearch.yml` to include the following config:
 
@@ -169,7 +175,7 @@ which determines which set of features and bundles are installed and started. A
 
 9) Try accessing https://localhost:9443/cxs/cluster with username/password: `karaf/karaf` . You might get a certificate warning in your browser, just accept it despite the warning it is safe.
 
-10) Create a tenant that will own all your data:
+10) Create a tenant that will own all your data, then regenerate keys and store `plainTextKey`:
 
 [source,bash]
 ----
@@ -183,9 +189,12 @@ curl -X POST http://localhost:8181/cxs/tenants \
       "description": "Default tenant for quick start"
     }
   }'
+
+curl -X POST "http://localhost:8181/cxs/tenants/default/apikeys?type=PUBLIC" --user karaf:karaf
+curl -X POST "http://localhost:8181/cxs/tenants/default/apikeys?type=PRIVATE" --user karaf:karaf
 ----
 
-Save the API keys from the response - you'll need them for API calls.
+Save the `plainTextKey` values from the key-creation responses — you'll need them for API calls.
 
 11) Request your first context:
 
@@ -216,6 +225,7 @@ 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
+- Align SSL with the cluster (`UNOMI_OPENSEARCH_SSL_ENABLE` / `org.apache.unomi.opensearch.sslEnable`; package default is `true`)
+- For local Docker TLS, set `UNOMI_OPENSEARCH_SSL_TRUST_ALL_CERTIFICATES=true` or install a proper trust store
+- Configure a strong admin password via `OPENSEARCH_INITIAL_ADMIN_PASSWORD` (OpenSearch rejects weak passwords such as `admin`)
+- Select the OpenSearch distribution (`UNOMI_DISTRIBUTION=unomi-distribution-opensearch` or `unomi:setup -d=unomi-distribution-opensearch`)

manual/src/main/asciidoc/architecture.adoc

@@ -14,7 +14,7 @@
 
 === High-Level Architecture
 
-NOTE: Unomi 3.1 adds <<_multitenancy,multi-tenancy>>, <<_scheduler,task scheduling>>, and <<_clustering,persistence-based clustering>>. The diagram below focuses on core request processing.
+NOTE: Unomi 3.1 adds <<_multitenancy,multi-tenancy>> and <<_scheduler,task scheduling>> on top of the 3.0 platform (including <<_clustering,persistence-based clustering>>). The diagram below focuses on core request processing.
 
 [plantuml]
 ----
@@ -61,11 +61,6 @@ Rel(karaf, unomi, "Hosts")
 ----
 @startuml
 skinparam componentStyle uml2
-skinparam component {
-  BackgroundColor<<core>> LightBlue
-  BackgroundColor<<persistence>> LightGreen
-  BackgroundColor<<security>> LightYellow
-}
 
 package "Core Services" {
   [Profile Service] <<core>>
@@ -141,11 +136,6 @@ end note
 ----
 @startuml
 skinparam componentStyle uml2
-skinparam component {
-  BackgroundColor<<evaluation>> LightBlue
-  BackgroundColor<<query>> LightGreen
-  BackgroundColor<<persistence>> LightYellow
-}
 
 package "Condition Evaluation" {
   [ConditionDispatcher] <<evaluation>>
@@ -213,9 +203,6 @@ end note
 [plantuml]
 ----
 @startuml
-skinparam activityBackgroundColor LightBlue
-skinparam activityBorderColor DarkBlue
-skinparam arrowColor DarkBlue
 
 |Client|
 start

manual/src/main/asciidoc/building-and-deploying.adoc

@@ -242,7 +242,7 @@ To merge the branch into master.
 
 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.
 
-===== Option 1: Using ElasticSearch
+===== Option 1: Using Elasticsearch
 
 1. Download Elasticsearch 9.4.3 from: https://www.elastic.co/downloads/past-releases/elasticsearch-9-4-3[https://www.elastic.co/downloads/past-releases/elasticsearch-9-4-3]
 
@@ -252,7 +252,7 @@ Apache Unomi 3.x does not embed a search engine. Install Elasticsearch 9.x or Op
 
 [source,yaml]
 ----
-cluster.name: contextElasticSearch
+cluster.name: contextElasticsearch
 ----
 +
 4. Launch the server using:
@@ -274,14 +274,14 @@ The recommended way to run OpenSearch is using Docker Compose:
 version: '3.8'
 services:
   opensearch-node1:
-    image: opensearchproject/opensearch:3
+    image: opensearchproject/opensearch:3.7.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}
+      - OPENSEARCH_INITIAL_ADMIN_PASSWORD=${OPENSEARCH_INITIAL_ADMIN_PASSWORD:-MyStrongPassw0rd!}
     ulimits:
       memlock:
         soft: -1
@@ -324,7 +324,7 @@ After your search engine is running, you can start Unomi using the appropriate c
 
 [source]
 ----
-# For ElasticSearch
+# For Elasticsearch
 unomi:start elasticsearch
 
 # For OpenSearch
@@ -470,7 +470,7 @@ which will output something like this :
 [source]
 ----
 Matching Java Virtual Machines (3):
-    11.0.5, x86_64:	"OpenJDK 11.0.5"	/Library/Java/JavaVirtualMachines/openjdk-11.jdk/Contents/Home
+    17.0.x, x86_64:	"OpenJDK 17"	/Library/Java/JavaVirtualMachines/openjdk-17.jdk/Contents/Home
     1.8.0_181, x86_64:	"Java SE 8"	/Library/Java/JavaVirtualMachines/jdk1.8.0_181.jdk/Contents/Home
     1.7.0_80, x86_64:	"Java SE 7"	/Library/Java/JavaVirtualMachines/jdk1.7.0_80.jdk/Contents/Home
 
@@ -507,7 +507,7 @@ integration tests at least once before using the server to make sure that everyt
 to use these tests is to run them from a continuous integration server such as Jenkins, Apache Gump, Atlassian Bamboo or
  others.
 
-Note : the integration tests require a JDK 11 or more recent !
+Note : the integration tests require a JDK **17** or more recent !
 
 To run the tests simply activate the following profile:
 
@@ -518,7 +518,7 @@ mvn -P integration-tests clean install
 
 ===== Selecting the Search Engine for Integration Tests
 
-By default, integration tests target ElasticSearch. To run them against OpenSearch, you can use either:
+By default, integration tests target Elasticsearch. To run them against OpenSearch, you can use either:
 
 * **Using the build script** (recommended):
 +
@@ -557,6 +557,7 @@ A default test page is provided at the following URL:
    http://localhost:8181/index.html
 ----
 
-This test page will trigger the loading of the /cxs/context.js script, which will try to retrieving the user context
-or create a new one if it doesn't exist yet. It also contains an experimental integration with Facebook Login, but it
-doesn't yet save the context back to the context server.
+This test page loads `/cxs/context.js`, which retrieves or creates a user context.
+On Unomi 3.1, public context endpoints require a tenant public API key (`X-Unomi-Api-Key`) unless <<_v2_compatibility_mode,V2 compatibility mode>> is enabled.
+Create a tenant and regenerate keys first (see <<_five_minutes_quickstart,5-minute quickstart>> or <<_multitenancy,Multi-tenancy>>).
+The page also contains an experimental Facebook Login integration that does not yet save the context back to the server.

manual/src/main/asciidoc/condition-evaluation.adoc

@@ -26,11 +26,6 @@ The condition evaluation system in Apache Unomi provides flexible and efficient
 ----
 @startuml
 skinparam componentStyle uml2
-skinparam component {
-  BackgroundColor<<evaluation>> LightBlue
-  BackgroundColor<<query>> LightGreen
-  BackgroundColor<<persistence>> LightYellow
-}
 
 package "Condition Evaluation" {
   [ConditionDispatcher] <<evaluation>>
@@ -41,12 +36,12 @@ package "Condition Evaluation" {
 
 package "Query Building" {
   interface "QueryBuilder" as QB
-  [ElasticSearchQueryBuilder] <<query>>
+  [ElasticsearchQueryBuilder] <<query>>
   [OpenSearchQueryBuilder] <<query>>
 }
 
 package "Storage" {
-  [ElasticSearch] <<persistence>>
+  [Elasticsearch] <<persistence>>
   [OpenSearch] <<persistence>>
 }
 
@@ -56,10 +51,10 @@ package "Storage" {
 QB <|.. [ConditionQueryBuilder]
 QB <|.. [ConditionQueryBuilder]
 
-[ConditionQueryBuilder] --> [ElasticSearchQueryBuilder]
+[ConditionQueryBuilder] --> [ElasticsearchQueryBuilder]
 [ConditionQueryBuilder] --> [OpenSearchQueryBuilder]
 
-[ElasticSearchQueryBuilder] --> [ElasticSearch]
+[ElasticsearchQueryBuilder] --> [Elasticsearch]
 [OpenSearchQueryBuilder] --> [OpenSearch]
 
 note right of [ConditionDispatcher]
@@ -111,7 +106,7 @@ end note
 
 Query builders provide storage-specific implementations:
 
-1. *ElasticSearch Implementation*
+1. *Elasticsearch Implementation*
 - Optimized for ES query syntax
 - Handles ES-specific mappings
 - Supports ES versioning