3.4.1.2. Use EHRbase Image

This part of the documentation explains how to run EHRbase as a Docker Container created from the image in previous steps.

3.4.1.2.1. Run EHRbase in Docker

Note

Remember: EHRbase requires a properly configured and running PostgreSQL DB to work. Make sure to set this up first before you try run EHRbase.

To run EHRbase in a Docker Container first pull the official Docker image from Docker Hub:

docker pull ehrbase/ehrbase

OR

build your own image form Dockerfile:

git clone https://github.com/ehrbase/ehrbase.git
cd ehrbase
docker build -t myehrbase/ehrbase .
docker image ls

THEN use the docker run command adjusting parameters to your needs to change Container’s default behaviour.

Note

Remember: Container’s default behaviour is set during Docker image build time.

docker run -e DB_URL=jdbc:postgresql://ehrdb:5432/ehrbase \
           -e DB_USER=foouser \
           -e DB_PASS=foopass \
           -e SERVER_NODENAME=what.ever.org \
           -p 8080:8080 \
           ehrbase/ehrbase
Parameter Usage Example
DB_URL Database URL. Must point to the running database server. jdbc:postgresql://ehrdb:5432/ehrbase
DB_USER Database user configured for the ehr schema. ehrbase
DB_PASS DB user password ehrbase
SERVER_NODENAME Name of the server local.ehrbase.org
SECURITY_AUTHTYPE HTTP security method BASIC / OAUTH
SECURITY_AUTHUSER BASIC Auth username myuser
SECURITY_AUTHPASSWORD BASIC Auth password myPassword432
SECURITY_AUTHADMINUSER BASIC auth admin user myadmin
SECURITY_AUTHADMINPASSWORD BASIC auth admin password mySuperAwesomePassword123
ADMINAPI_ACTIVE Should admin endpoints be enabled true / false
ADMINAPI_ALLOWDELETEALL Allow admin to delete all resources - i.e. all EHRs true / false
MANAGEMENT_ENDPOINT_ENV_ENABLED Enable /management/env endpoint from actuator true / false
MANAGEMENT_ENDPOINT_HEALTH_ENABLED Enable /management/health endpoint from actuator true / false
MANAGEMENT_ENDPOINT_INFO_ENABLED Enable /management/info endpoint from actuator true / false
MANAGEMENT_ENDPOINT_METRICS_ENABLED Enable /management/metrics endpoint from actuator true / false
MANAGEMENT_ENDPOINT_PROMETHEUS_ENABLED Enable /management/prometheus endpoint from actuator true / false
SERVER_DISABLESTRICTVALIDATION Disable strict validation of openEHR input true / false

Note

Do NOT set SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUERURI in combination with SECURITY_AUTHTYPE=BASIC! This will crash EHRbase at start up.

Parameter Usage
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUERURI OAuth2 server isuer uri
example: https://keycloak.example.com/auth/realms/ehrbase

3.4.1.2.2. Run EHRbase + DB with Docker-Compose

Note

Prerequisite: docker-compose is installed on your machine

With Docker-Compose you can start EHRbase and the required DB from a configuration file written in YAML format.

There is an example docker-compose.yml configuration file in our Git repository. Using it allows you to set up and start EHRbase along with the required database with a few simple steps:

# download the docker-compose.yml file to your local
wget https://github.com/ehrbase/ehrbase/raw/develop/docker-compose.yml
wget https://github.com/ehrbase/ehrbase/raw/develop/.env.ehrbase
docker-compose up

# OR: start both containers detached, without blocking the terminal
docker-compose up -d

Note

It is not necessary to have the whole Git repository on your machine, just copy the docker-compose.yml file to a local working directory and run docker-compose up.

Note

DB data is saved in ./.pgdata for easier access.

You can configure all environment variables via the file .env.ehrbase which is located at the same folder as the docker-compose.yml file. This is also required for setting boolean values due to Docker compose files do not allow setting boolean values directly inside docker-compose.yml.

3.4.1.2.3. Docker environment examples

Here you can find some example settings for common use cases for the usage of EHRbase Docker containers. You can also use the environent variables with the normal .jar execution by setting the variables according to your operating system.

3.4.1.2.3.1. Use BASIC auth

Run the docker image with this setting:

docker run --network ehrbase-net --name ehrbase -e SECURITY_AUTHTYPE=BASIC \
-e SECURITY_AUTHUSER=myuser -e SECURITY_AUTHPASSWORD=ThePasswordForUser \
-e SECURITY_AUTHADMINUSER=myadmin -e SECURITY_AUTHADMINPASSWORD=SecretAdminPassword \
-d -p 8080:8080 ehrbase/ehrbase:latest

This will set the used authentication method to BASIC auth and all requests against the EHRbase must be provided with the Authorization header set to Basic %username%:%password% whereas the username and password must be encoded with base64.

Note

Ensure you use an encrypted connection over https otherwise the username and password can be descripted easily

3.4.1.2.3.2. Use OAuth2

Run the docker image with this setting.

docker run --network ehrbase-net --name ehrbase -e SECURITY_AUTHTYPE=OAUTH \
-e SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUERURI=https://keycloak.example.com/auth/realms/ehrbase \
-d -p 8080:8080 ehrbase/ehrbase:latest

You have to prepare the authentication server including a valid client at the target server to get this setup run.

3.4.1.2.3.3. Use OAuth2 and Attribute-based Access Control

Run the docker image with this setting.

docker run --network ehrbase-net --name ehrbase
-e SECURITY_AUTHTYPE=OAUTH \
-e SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUERURI=https://keycloak.example.com/auth/realms/ehrbase \
-e ABAC_ENABLED=true
-e ABAC_SERVER=http://localhost:3001/rest/v1/policy/execute/name/
-d -p 8080:8080 ehrbase/ehrbase:latest

Additionally, add the configuration of the endpoints and policies either here with additional -e parameters or more user-friendly in a separate docker-compose.yml file.