jayblanc opened a new pull request, #742:
URL: https://github.com/apache/unomi/pull/742
### 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](https://github.com/apache/unomi/pull/715)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
