zlg-platform
Context
The ZLG is using the EHRBase an openEHR Clinical Data Repository to store data in an interopable way using the openEHR-Technology Framework.
To make the data accessible by endusers the platform incorporates the NUM-Portal as well as NUM WebApp developed by NUM CODEX project. This allows for data management, data search, user management and more. You may use the official NUM CODEX images or fork/mirror those to build your own image with altered style/texts.
Data Import
With the openEHR_FLAT_Loader there are python-based scripts available to import/export data using CLI and REST. Those scripts can generate an Excel-Mapping-File that allows you to map your source-data (.csv-File) to an existing openEHR-Template´s data items. With this manual user-supplied mapping you may use the scripts to generate Compositions-Files that can also be uploaded to an openEHR-Repository-Server (like EHRBase or Better Server). See the github repository of the openEHR_FLAT_Loader for more informationen.
There are also other solution available (e.g. see HaMSTRETLBuilder).
About openEHR
More in depth explanation of the interoperable technology framework "openEHR" at our Docusaurus-Documentation or at the offical website which also hosts the standards specification.
Usage
You can start the different tools via docker-compose.
Tools
- EHRBase Clinical Data Repository (ehrbase_docker)
- NUM Portal (portal_docker)
- ZLG-Documentation (zlg_docs)
For the data import tool "FLAT_Loader" see FLAT_Loader Github-Repository.
Startup
Create a valid SSL-Cert (once at first start)
Alter Domain-Settings and Environment variables
- Change Domain-Names in
config.deploy.json
- Define passwords in
.env
- If you want to also host the docs alter domain-settings in
./docs/zlg-docs/docusaurus.config.js
Start all containers
Start Container using
docker-compose up -d
Init Databases
Init DB for EHRBase
Set password in ./portal_docker/sql/createdb.sql
according to
docker cp ./portal_docker/sql/createdb.sql ${CONTAINER-NAME}:/docker-entrypoint-initdb.d/createdb.sql
docker exec -u postgres ${CONTAINER-NAME} psql postgres postgres -f docker-entrypoint-initdb.d/createdb.sql
(See EHRBase SQL Init Skript).
Init NUM-Portal Attachment Database
Alter ${CONTAINER-NAME} which would be "postgres" by default.
docker cp ./portal_docker/sql/createdb_attachments-db-setup.sql ${CONTAINER-NAME}:/docker-entrypoint-initdb.d/dump.sql
docker exec -u postgres ${CONTAINER-NAME} psql postgres postgres -f docker-entrypoint-initdb.d/dump.sql
(See NUM-Portal SQL Init Skript)
Setup Keycloak-Auth with NUM-Portal
Generate a client-secret
- Visit Keycloak Endpoint at https://DOMAIN/auth
- Generate new secret via Clients -> num-portal -> Credentials -> Regenerate Secret
- Copy Secret-Value in Keycloak and set ${KEYCLOAK_CLIENT_SECRET} in .env-File
- Recreate num-portal container:
docker-compose up -d --force-recreate num-portal
Setup First User
- Visit Frontend on https://DOMAIN/home
- CLick on Login and register a new user at the keycloak
- Visit keycloak admin interface at https://DOMAIN/auth
- Go to Users -> View all users -> Edit -> Role Mapping -> Assign all roles
- Go to Users -> View all users -> Edit -> Email Verified = ON -> Save
- Re-log in the Frontend
- Enter the database (e.g. using adminer at port :5000)
- e.g. expose port of adminer/pg_admin and login to the DB
- e.g. Login to server=postgres, user=postgres, pw=${POSTGRES_PASSWORD}, database=ehrbase
- See schema "num" and in table "user_details" set the user to approved (identified by same id like in keycloak)
- Re-log in the Frontend
- You should have all rights in the portal now
SSL-Encryption
Setting up SSL Encryption using NGINX and LetsEncrypt is a two step process.
- At first rename
before-cert-creation.conf
tonginx.conf
. - Start the applications using docker-compose to create a valid certificate.
- Set environment variables ${EMAIL} and ${DOMAIN} in
.env
-File - Rename
after-cert-creation.conf
tonginx.conf
. - Rerun the certbot using docker-compose.
The nginx.conf
config-file is picked up by docker-compose when recreating the nginx-container with docker-compose up -d --force-recreate
Hint:
If you choose to copy a new nginx.conf into a running container via
docker cp
you need to reload nginx usingdocker-compose exec nginx nginx -s reload
.
Update Process
For most modules updating can be done by changing the images-version tag. Tags of available images can be found at Docker-Hub. If there are errors after updating you will notice services restarting and/or not working. With the tools we use here it is recommended to use a fixed version-tag instead of :latest-tag to avoid unexpected downtime.
If an update requires additional changes (e.g. NUM-Portal introducing new Environment-Variables or Ehrbase requiring changes on DB-Level) you can use docker-compose logs -f
or docker-compose logs -f
${CONTAINERNAME}to identify the cause of those errors in the log.
See Dockerhub for new versions or Github-pages for changes and changelogs.
Automation of updates
Automate Cert-Renewal:
- Configure a cronjob to run cert-renewal-script
You may consider automating other update processes as well.
Automation of the setup-process is a future-TODO.
(External) Documentation
- openEHR-Specification
- openEHR REST API-Documentation
- EHRBase Documentation
- EHRBase REST API Documentation
- NUM Portal Benutzerhandbuch
License
This documentation is licensed under Creative Commons license CC-BY-SA 4.0 unless otherwise stated.
The tools utlized by the zlg-platform are available at public sources under their respective licenses.