Release Notes and Upgrade Instructions
KHEOPS is composed of a number of Docker Images. All the docker images belonging to a single version and meant to run together are taged with the same version number. As a general rule, upgrading versions is simply a matter up updating the tag on the docker images. Addition steps that need to be performed are detailed below. KHEOPS uses Liquibase to manage the database schema, and the database will be automatically upgraded.
As with any upgrade - make sure to perform a backup of the database used by KHEOPS before performing an upgrade.
v0.9.5
Changes
-
Many UI fixes.
-
Fixed issue where the UI might not load after a long idle time.
Upgrade
- No additional upgrade steps are necessary
v0.9.4
When upgrading, make sure to install and run v0.9.3 prior to installing v0.9.4.
Changes
- Removed dependency on Keycloak.
- UI Improvements.
Upgrade
- Environment variable
KHEOPS_KEYCLOAK_URI
is no longer used. - Environment variable
KHEOPS_KEYCLOAK_REALMS
is no longer used. - Environment variable
KHEOPS_KEYCLOAK_CLIENTID
is no longer used. - Docker secret
kheops_keycloak_clientsecret
is no longer used. - Docker secret
kheops_metric_ressource_password
is no longer used.Note when removing secrets - don’t forget to remove references to secrets in the docker-compose.yml.
- The Keycloak kheopsAuthorization Service Account is no longer used.
v0.9.3
Transition version to v0.9.4
Versions of KHEOPS up to v0.9.2 had a strong dependency on Keycloak. Only the user’s ID (sub) was stored in the KHEOPS database, and KHEOPS would use Keycloak APIs and a service account (kheopsAuthorization) to discover a user’s name and email address.
Starting with v0.9.4, KHEOPS uses exclusively OpenID Connect (OIDC) for user authentication. v0.9.3 is a transition release that is still dependent on Keycloak, and retrieves the user names and emails from Keycloak at startup.
While we still expect Keycloak to be used in the majority of cases. It will now be possible to use other OIDC providers directly, without installing Keycloak.
Changes
- Loads user profile information from Keycloak at startup
- Updates user profile information at each login.
- UI Improvements.
Upgrade
-
Add Environment variable
KHEOPS_OIDC_PROVIDER
which is a URL that points to the OpenIDConnect Provider.The full path to the OIDC provider must be set. Its value will typically be
${KHEOPS_KEYCLOAK_URI}/auth/realms/${KHEOPS_KEYCLOAK_REALMS}
For example: If the
KHEOPS_KEYCLOAK_URI
ishttps://keycloak.kheops.online
, and theKHEOPS_KEYCLOAK_REALMS
isdemo
, the value ofKHEOPS_OIDC_PROVIDER
would behttps://keycloak.kheops.online/auth/realms/demo
. -
Environment variables
KHEOPS_ROOT_SCHEME
,KHEOPS_ROOT_HOST
, andKHEOPS_ROOT_PORT
are replaced byKHEOPS_ROOT_URL
.The value of
KHEOPS_ROOT_URL
will typically be${KHEOPS_ROOT_SCHEME}://${KHEOPS_ROOT_HOST}[:${KHEOPS_ROOT_PORT}]
. If the port is the default port for the scheme (e.g., 443 for https), it can be omitted. For example:https://demo.kheops.online
. -
Environment variable
KHEOPS_UI_KEYCLOAK_CLIENTID
is renamedKHEOPS_UI_CLIENTID
-
Make sure that the KHEOPS UI login client in Keycloak has the
web-origins
,email
, andprofile
Client Scope as an Assigned Default Client Scope. -
KHEOPS_UI_USER_MANAGEMENT_URL
is a new optional environment variable that can be set to provide a page where a user can access user settings.If using Keycloak, this value would probably be set to
${KHEOPS_OIDC_PROVIDER}/account
. For example:https://keycloak.kheops.online/auth/realms/demo/account
Notes for upgrading for nonsecure install
-
Pass the backend docker network hostname of the Keycloak server using the
KHEOPS_OIDC_PROVIDER
environment variable to the kheops-authorization Docker container in the docker-compose.yml file.environment: KHEOPS_OIDC_PROVIDER:http://keycloak:8080/auth/realms/kheops
-
Pass the frontend URL to the keycloak container using the
KEYCLOAK_FRONTEND_URL
environment variable in the docker-compose.yml fileenvironment: KEYCLOAK_FRONTEND_URL: http://127.0.0.1:8080/auth
-
Remove the
KHEOPS_KEYCLOAK_URI
environment variable fromkheops-ui
in the docker-compose.yml file. -
The
-noissuer
tag for the osirixfoundation/kheops-authorization image is no longer needed.
Older versions
To upgrade from versions older than v0.9.2, please contact us directly at support@kheops.online or spalte@naturalimage.ch.