UNOMI-919: Refactor the UNOMI startFeatures configuration to use a Karaf feature

[jayblanc]

Summary

This PR refactors how Apache Unomi selects and installs its startup feature set (formerly driven by the startFeatures OSGi configuration and the semantic overloading of UNOMI_AUTO_START). It introduces proper Karaf features to represent Unomi “distributions” (search backend variant + ancillary feature set) and restores UNOMI_AUTO_START to its original purpose (auto–start true/false). A new environment variable and/or setup mechanism is added to select the desired search backend distribution cleanly and persistently.

It also removes the HealthCheck delegator introduced earlier and reverts to the standard pattern of provider activation via configuration, now split per backend through dedicated healthcheck features.

---

Motivation

The previous approach:

• Overloaded UNOMI_AUTO_START to include backend selection (e.g. elasticsearch | opensearch) which was confusing to new users.
• Introduced a custom OSGi configuration (startFeatures) holding a comma–separated list of features, duplicating what Karaf feature descriptors already provide (dependency management, versioning, externalization).
• Added a HealthCheck delegator layer to route to the correct search provider, while Unomi already supports selective provider activation via config.

This PR adopts standard Karaf feature mechanisms for clarity, maintainability, and easier custom packaging, while simplifying health checks.

---

Key Changes

1. Distribution Feature Introduction

   • Added two Karaf features :
     • unomi-distribution-elasticsearch
     • unomi-distribution-opensearch
   • These features aggregate the previously listed startup features and include the appropriate healthcheck feature.
   • New Maven module distribution housing the built-in feature XML descriptors (included in the package).
   • Enables external (custom) distributions by publishing feature XMLs to Maven repos.

2. Environment Variable / Setup Refactor

   • Restored UNOMI_AUTO_START to a boolean/legacy behavior (e.g. auto-start service on container launch).
   • Introduced UNOMI_DISTRIBUTION to specify which distribution feature to use (defaults to Elasticsearch if unset).
   • Docker image and startup scripts updated to translate UNOMI_DISTRIBUTION into an internal unomi:setup persisted value.
   • UnomiManagementService set the distribution to unomi-distribution-elasticsearch if not set in environment
   • Added unomi:setup <distributionFeatureName> command:
     • Persists chosen distribution (unless overridden with a force/overwrite flag).
     • Guards against accidental production backend switching.

3. Removal of Custom startFeatures OSGi Config

   • Deleted the startFeatures OSGi config key and associated management logic from UnomiManagementService.
   • Simplified startup path: now just resolves the selected distribution feature and installs it by iterating on feature dependencies (as previously done with the startFeatures list).

4. HealthCheck Simplification

   • Removed the Delegator pattern.
   • Reintroduced separate providers with activation governed by configuration.
   • Added two healthcheck feature descriptors (e.g. unomi-healthcheck-elasticsearch, unomi-healthcheck-opensearch).
   • Each healthcheck feature carries a config file enabling only the relevant providers.
   • Search backend providers now defensively check activation in init() to avoid unnecessary client construction when not active.

5. Docker & Packaging Adaptations

   • Updated entrypoint / scripts to:
     • Respect UNOMI_DISTRIBUTION.
     • No longer misuse UNOMI_AUTO_START for backend selection.
   • Documentation/examples updated to show:
     • UNOMI_AUTO_START=true
     • UNOMI_DISTRIBUTION=unomi-distribution-opensearch (or elasticsearch).

---

Upgrade / Migration Notes

If you previously used Unomi Docker images with:

UNOMI_AUTO_START=elasticsearch

(or opensearch)

You must now use:

UNOMI_AUTO_START=true
UNOMI_DISTRIBUTION=unomi-distribution-elasticsearch

(or unomi-distribution-opensearch).

If you previously started Unomi in Karaf shell with:

unomi:start elasticsearch

(or opensearch)

You must now use:

unomi:setup unomi-distribution-elasticsearch
unomi:start

(or unomi-distribution-opensearch).

Custom startup feature lists should be converted into a Karaf feature XML and published as a Maven artifact; then set UNOMI_DISTRIBUTION to that feature name.

---

Testing Performed

• Unit tests updated for ManagementService (distribution resolution logic).
• Integration tests for both distributions ensure feature installation completes and backend connects.
• Healthcheck endpoints validated for each backend returning expected checks.
• Docker image smoke-tested with both UNOMI_DISTRIBUTION values.
• Negative test: unspecified UNOMI_DISTRIBUTION defaults to elasticsearch.
• Re-run after switching distribution (if setup command supports overwrite).

---

Related JIRA / PR Links

• JIRA: UNOMI-919
• Prior PR (context – OpenSearch integration): #715

[sergehuber]

Hi @jayblanc this closed automatically when I deleted the branch. Sorry about that, do you want to rebase it ?