Getting started with a local installation

At its core KHEOPS is an authorization layer placed in front of a DICOMweb capable PACS. KHEOPS is composed of multiple docker containers typically orchestrated using Docker-Compose or Kubernetes.

We are always happy to respond to any questions. Feel free to contact us at contact@kheops.online.

A simple insecure local server

Below are instruction for getting a basic instance of KHEOPS up and running. This configuration does not provide security. In order to be properly secured, KHEOPS and Keycloak must be placed behind TLS (https) connections and the Keycloak configuration must be updated. Nevertheless, this install will provide a starting point that can be modified as needed for the local environment.

  1. Install Docker (latest version)
  2. Install Docker-Compose (latest version)
  3. Make sure that the current user is in the docker group.
  4. Run the following command:
bash <(curl -sL https://raw.githubusercontent.com/OsiriX-Foundation/KheopsOrchestration/insecure-install-v1.1.1/kheopsinstall.sh)

This script will create a new directory named kheops in which it will download docker-compose configuration files, a keycloak realm configuration, and generate the necessary secrets.

Once installed, Keycloak will be available at http://127.0.0.1:8080, Kibana will be available at http://127.0.0.1:8081 and KHEOPS will be available at http://127.0.0.1.

When you first connect to KHEOPS , you will be redirected to the Keycloak login screen. In order to access Kheops, you will need to register a new account. The Register link will be available to create a new KHEOPS account.

Notes

  • On MacOS, the default Docker memory limit of 2GB is not sufficient. 8GB is safer.
  • Also on MacOS, Safari does not trust connections to 127.0.0.1, so when loading a study in the OHIF viewer (which is loaded with https), Safari refuses the mixed security connection. Chrome respects the standards and considers connections to 127.0.0.1 to be secure so this issue does not occur.

Making it secure

In a production environment, Keycloak should be set up on a separate domain. KHEOPS interacts with Keycloak using the Authorization Code flow. Please refer to the Keycloak documentation for instruction on how to properly secure Keycloak. KHEOPS specific Keycloak configuration steps are described here. Keycloak must be configured to work using a secured TLS (https) connection in order to secure user credentials.

Using Let’s Encrypt

A Let’s Encrypt enabled reverse proxy for KHEOPS is available. To use it, replace the -insecure portion of the tag on the kheops-reverse-proxy with -letsencrypt. When using the Let’s Encrypt enabled version of the reverse proxy, the KHEOPS_ROOT_URL environment variable must be a URL accessible from the general internet, and the LETS_ENCRYPT_EMAIL environment variable must be set to the email with which the domain will be registered. Add a volume that will store the Let’s Encrypt certificates in order to avoid having Let’s Encrypt re-issue certificates every time the container is run.

  1. In the docker-compose.env file change the following:
    • Change the KHEOPS_ROOT_URL to your domain.
    • Change the KHEOPS_OIDC_PROVIDER to your secured Keycloak or other OIDC Provider.
    • If needed, change the KHEOPS_UI_CLIENTID.
    • Create and set a new LETS_ENCRYPT_EMAIL environment variable to the email with which the domain will be registered.
  2. In the kheops-authorization section of the docker-compose.yml file change the following:
    • Remove the KHEOPS_OIDC_PROVIDER environment variable.
  3. In the kheops-reverse-proxy section of the docker-compose.yml file change the following:
    • Replace the -insecure portion of the tag with -letsencrypt.

    • Add an extra_hosts section that loopbacks the root.

        extra_hosts:
    - "your.domain.here:127.0.0.1"

    • Modify the ports section as follows.

        ports:
    - "80:80"
    - "443:443"
    • Modify the volumes section of the container as follows. 
        volumes:
    - letsencrypt:/etc/letsencrypt
    • Add the letsencrypt volume to the list of volumes to create at the bottom of the file. 
         volumes:
     letsencrypt:

Using a custom certificate

It is possible to use a custom TLS certificate. To use it, replace the -insecure portion of the tag on the kheops-reverse-proxy with -secure.

  1. Place the certificate private key file in secrets/privkey.pem.
  2. Place the certificate chain file in secrets/fullchain.pem.
  3. In the docker-compose.env file change the following:
    • Change the KHEOPS_ROOT_URL to your domain.
    • Change the KHEOPS_OIDC_PROVIDER to your secured Keycloak or other OIDC Provider.
    • If needed, change the KHEOPS_UI_CLIENTID.
  4. In the kheops-authorization section of the docker-compose.yml file change the following:
    • Remove the KHEOPS_OIDC_PROVIDER environment variable.
  5. In the kheops-reverse-proxy section of the docker-compose.yml file change the following:
    • Replace the -insecure portion of the tag with -secure.

    • Add an extra_hosts section that loopbacks the root.

        extra_hosts:
    - "your.domain.here:127.0.0.1"

    • Modify the ports section as follows.

        ports:
    - "80:80"
    - "443:443"

    • Add a secrets section.

        secrets:
    - privkey.pem
    - fullchain.pem

  6. In secrets section, add the following secrets:

     privkey.pem:
   file: secrets/privkey.pem
 fullchain.pem:
   file: secrets/fullchain.pem

Running without Kibana and logs management

In the docker-compose.yml file :

  • Remove services : kibana, kibana-initialize, elasticsearch, logstash, kheops-authorization-metricbeat and kheops-filebeat-sidecar
  • Remove networks : beats_network, elk_network in all the docker-compose.yml
  • Remove volumes : elastic_data, logs_pep, logs_reverse_proxy, logs_auth in all the docker-compose.yml. Remember to remove all references to these volumes.

Sending logs to an existing ELK Stack

In the docker-compose.yml file :

  • Remove services : kibana, elasticsearch and logstash
  • Remove network : elk_network in all the docker-compose.yml
  • Remove volume : elastic_data in all the docker-compose.yml

*In the *docker-compose.env file : **

  • Edit KHEOPS_LOGSTASH_URL with the logstash url

In the existing ELK Stack

  • Import logstash config here
  • Import index pattern, visualisation and dashboard in your Kibana from here
  • Configure the rollup job rollup_job_kheops_metrics by doing a PUT _rollup/job/rollup_job_kheops_metrics with the following json here
  • Start the rollup job : POST _rollup/job/rollup_job_kheops_metrics/_start

Dependencies on External Services

A KHEOPS instance consists of the KHEOPS Docker containers interacting with the following services.

  • A DICOMweb Capable PACS

    KHEOPS uses strict DICOMweb APIs to communicate with the backing PACS server, making it possible to use any DICOMweb capable PACS. In practice KHEOPS has been tested with DCM4CHEE and Google Cloud Platform Healthcare API.

    DCM4CHEE

    KHEOPS has received the most testing using DCM4CHEE as the backing PACS. Since it is the role of KHEOPS to handle authorization and secure access, DCM4CHEE is run in an unsecured configuration, and is made available only to KHEOPS.

    When using DCM4CHEE, the required minimum version is 19.1.

    Google Cloud Platform

    KHEOPS can also run on Google Cloud Platform using the Cloud Healthcare API using DICOM stores. Unfortunately, DICOM stores within the Cloud Healthcare API only support a subset of DICOMweb. Specific Docker images that work around these limitations are available.

    When running on Google Cloud Healthcare, KHEOPS will access the DICOMweb Store using a Service Account.

  • An OpenID Connect Capable Authorization Server

    For user authentication, KHEOPS behaves as an OpenID Connect (OIDC) Client.

    Keycloak

    KHEOPS has received the most testing using Keycloak as the OIDC Provider. Instructions for configuring Keycloak are available here.

  • PostgreSQL Database

    KHEOPS stores all state to a PostgreSQL database. Versions 9.6, 10, and 12 have been used in the past. Other versions will likely also work.

Architecture Diagram

Architecture
Architecture of a KHEOPS installation

Table of contents