Installation and setup

WORK IN PROGRESS - DO NOT REFER TO THIS PAGE - DOCUMENTATION BOUND FOR ES 1.8

This page describes the installation and setup of Elexis-Server (ES). Where the setup is completed, on the state that ES is connected to an Elexis database.

• Requirements
• Installation
  • Installation via Download
  • Installation via Docker
    • Plain docker
    • Docker-compose
      • Sharing the Elexis home-directory with the host
    • Usage on Synology devices - Prepare the required volume directory - Setup docker and an elexis-server container
• Setup
  • Configuring the database connection
    • Configuration web-interface
    • Providing the elexis-connection.xml file
    • Elexis Rest API
• Security
  • HTTPS
• Remarks
  • Demo mode login
  • Connecting to ES (port 7234)
• Commercial services (Medelexis Bridge)
  • Connecting to your ES from the Internet
  • Differences in Synology setup

Requirements

Elexis-Server (ES) requires an Elexis-Database connection to provide its functionality as currently is not able to set-up an Elexis-Database itself.

To provide such a database an Elexis installation with the following additional plugins is required:

• Artikelstamm
• Omnivore
• Base CH
• LaborTarif
• Physioleistung

ES1.8 requires Elexis 3.8 for correct functionality.

Installation

ES is available both as download and as docker image. In development we use several development streams. master is always the bleeding edge, which might not be appropriate for you. We recommend you to stick to the highest 1.x version available mentioned.

Installation via Download

You may download the ES products from http://download.elexis.info/elexis-server/, where you have to select your required development stream and the product directory contained.

Installation via Docker

Docker is a software that allows for the distribution of software in form of containers. This is very much like the containers you know in shipping. Docker is available for all major platforms, we however recommend and document the usage on a Linux system. If setting up a linux system with docker is too complicated for you, you might find a viable solution using a synology device.

Plain docker

1. Start the docker image in foreground docker run -e TZ=Europe/Zurich -p 8380:8380 -p 8480:8480 -p 7234:7234 medevit/elexis-server (add -e DEMO_MODE='true' to enable demo mode and -h "hostname" to set a hostname, which is required for proper OpenId behavior)
2. Set the database connection using a POST call

Sharing the Elexis home-directory with the host

Each container you instantiate using Docker is initializing itself from scratch. In order to keep configurations, and provide them to subsequent creations of containers, the elexis home-directory can be provided by the host system to the container.

To use this, first create a directory, which has the necessary rights to be accessed from within the container, and then include it in docker run using -v /full/path/to/local/directory:/elexis.

Usage on Synology devices

Synology features a number of network appliances. This documentation is based on a Synology DS916+ with operating system DSM6.1.5.

Prepare the required volume directory

We have to provide a separate volume to the ES container image, to host the ES home directory. If we don't do this, the ES home directory will be bound to the created container image, and not be available for subsequent updates of the container image.

1. Using File Station generate a directory elexis in your users home directory under homes
2. Adjust the permissions on this directory, such that the following parts will work

Setup docker and an elexis-server container

1. Install the Docker package via the package center

2. Start the docker package by clicking on it in the main-screen

3. Download the newest medevit/elexis-server docker image and select the latest tag. The resulting download will take some time.

4. The tab Image will now contain an image called medevit/elexis-server:latest

5. Select this image, and use the Launch button to create a new container out of the image

6. Name the new image elexis-server and subsequently edit Advanced Settings

7. Switch to Volume and add the required volume directory

8. Switch to Port Settings and add set the local port to static values. ⚠️ Binding port 7234 effectively opens the ES OSGI console for access, you might consider not to include this port.

9. If you want to start this system as a demo system go to Environment and add the variable DEMO_MODE with value true. This will effectively override the current settings and activate the demo system. If you remove this variable later on the system will switch back to its original mode.

Setup

Configuring the database connection

If ES was started in demo-mode, the database configuration is already set to the database that was downloaded into the ES home directory during startup.

If you started ES in non-demo-mode, you have to manually configure the database connection. This can be done by

• using the web-interface,
• providing the elexis-connection.xml file,
• or posting it to the Elexis REST API.

Configuration web-interface

Just use your browser and point to the following location https://localhost:8480/web/elexis-connector/connection.

Providing the elexis-connection.xml file

The following code snippet shows a sample elexis-connection.xml file.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<dbConnection hostName="mysqlHostName" port="3306"
	databaseName="elexisDatabase" connectionString="jdbc:mysql://mysqlHostName:3306/elexisDatabase"
	username="elexis" password="elexis">
		<rdbmsType>MYSQL</rdbmsType>
</dbConnection>

⚠️ localhost as accessible for the host, is not accessible to a docker container. In order to connect to the database system you have to provide a "real" ip address or hostname

In order to make ES use it, you have to leave this file in the ES home-directory.

Elexis Rest API

The elexis-connection.xml file can be posted to the ES REST api using e.g. curl with

curl -X POST --header "Content-Type:application/xml;charset=UTF-8" -d @elexis-connection.xml http://localhost:8380/services/elexis/connector/connection

this call might take a while to return (due to the required services startups). If the connection to the database was successful, the call will answer db pool initialization success.

⚠️ The first call to this endpoint is allowed without authentication. Subsequent calls, which would effectively re-configure the connection, required administration rights.

Security

HTTPS

ES expects elexis-server.keystore at /elexis/elexis-server/elexis-server.keystore with password elexis-server

Remarks

Demo mode login

The demo database provides two users. The user Administrator with password admin having administrator rights, and the user test with password test.

Connecting to ES (port 7234)

If port 7234 is forwarded the ES OSGI console is connectable using unencrypted telnet.

Commercial services (Medelexis Bridge)

Please contact MEDELEXIS for further information on these services.

Connecting to your ES from the Internet

docker run -e DEMO_MODE='true' -e TZ=Europe/Zurich -p 8380:8380 -p 8480:8480 -p 7234:7234 --cap-add=NET_ADMIN \
-e DISABLE_WEB_SECURITY='true' -v /Users/marco/elexis-server/es-docker-home/:/elexis

Differences in Synology setup

• Place the OpenVPN configuration files you received into the "required volume directory". (If you receive a zipped file, place all the extracted files into this directory)
• In step 6 of the docker setup
  • Set the container name to the official hostname you configured for your service to be reachable under.
  • Additionally select "Execute container using high privilege"

⚠️ It might be necessary to initialize the /dev/net/tun device on the synology, see Reddit

TODO: --cap-add=NET_ADMIN should be representable without setting "Execute container using high privilege"