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.