Bare Metal Server Installation for OpenELIS Global 2.0 on Ubuntu 22.04 LTS

Setup Ubuntu 22.04.2.0 LTS

  1. Boot Ubuntu from a CD. [Note: Use Ubuntu Server 22.04.2.0 LTS, do NOT use desktop] Download.
  2. Chose UI language and keyboard layout
  3. Set the network configuration
  4. Use the default mirror
  5. Set up the hard disk
  6. Name the system: openelis
  7. user openelis
  8. set password and record it
    • I suggest adding the ssh key for each support user to enable passwordless connection.
  9. Select Install OpenSSH server
    • this will allow you to ssh into this computer allowing copy/paste for Windows users through Putty, or connections via terminal on Mac and from the shell in LINUX
  10. Skip the optional server snaps
  11. Finalize the ubuntu install
  12. Reboot

NOTE: I like to connect via ssh if I’m going to be using a lot of resources from my own computer here. This allows me to easily copy and paste commands below. For windows, the best utility I’ve found is Mobaxterm, as it incoperates a SCP client as well available for free download online. .

Install Prerequisites for OpenELIS

  1. Ensure that the system is connected to the internet properly, you can try to ping google DNS at 8.8.8.8

    ping 8.8.8.8

  2. Open a command prompt and enter the following commands- this will install the needed services and install updates to the OS since the image was created. This updates the system from the sources in the sources list. It updates what new packages are available.

    sudo apt update && sudo apt upgrade

  3. Install Net Tools in order to find the IP Address

    sudo apt install net-tools

  4. Install Python

    sudo apt install python3

Create and Load SSL Certificates

OpenELIS uses SSL certificates to securely communicate with other software or consolidated lab data servers. For a test or temporary instance, use a self-signed certificate, and for a production instance create a proper signed certifcate. You must have a cert and key created and in the keystore and truststore for the installer to run

I will include 2 paths, one for generating your own self-signed cert, this is good for just starting out or experimenting, and for using your real certs, which is appropriate for production servers. If you have real certificates skip down to Use a real certificate, best for production uses

Use a self signed certificate.

Generate a .crt and .key file for the domain you want to use.

The command below is for generating and using a self-signed certifcate. Note: for FQDN use *.openelisci.org

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/apache-selfsigned.key -out /etc/ssl/certs/apache-selfsigned.crt
Create keystore from key and cert

Make the directories for the keystore

sudo mkdir /etc/openelis-global/

sudo openssl pkcs12 -inkey /etc/ssl/private/apache-selfsigned.key -in /etc/ssl/certs/apache-selfsigned.crt -export -out /etc/openelis-global/keystore

and then

sudo cp /etc/openelis-global/keystore /etc/openelis-global/client_facing_keystore

Be sure to remember your keystore password, you will need it later

Create truststore with OpenELIS-Global's cert (or a CA that signs OE certs)

Choose ONE of the two methods below to create your truststore

  1. using keytool (more reliable):

    sudo apt install default-jre

sudo keytool -import -alias oeCert -file /etc/ssl/certs/apache-selfsigned.crt -storetype pkcs12 -keystore /etc/openelis-global/truststore
    • set the truststore password

    Be sure to remember your truststore password, you will need it later

    • when prompted if you want to trust the cert type yes

  2. using openssl (less reliable, but doesn't require java):

    openssl pkcs12 -export -nokeys -in /etc/ssl/certs/apache-selfsigned.crt -out /etc/openelis-global/truststore

Use a real certificate, best for production uses

Create keystore from key and cert

Make the directories for the keystore

sudo mkdir /etc/openelis-global/

make sure to record the password somewhere secure as you will need to enter it elsewhere)

sudo openssl pkcs12 -inkey path/toyour/key -in path/to/your/cert -export -out /etc/openelis-global/keystore

enter an export password

Be sure to remember your keystore password, you will need it later

and then

sudo cp /etc/openelis-global/keystore /etc/openelis-global/client_facing_keystore
Create truststore with OpenELIS-Global's cert (or a CA that signs OE certs)

Choose ONE of the two methods below to create your truststore

  1. using keytool (more reliable):

    sudo apt install default-jre

sudo keytool -import -alias oeCert -file path/to/your/cert -storetype pkcs12 -keystore /etc/openelis-global/truststore
    • set the truststore password

    Be sure to remember your truststore password, you will need it later

    • when prompted if you want to trust the cert type yes

  2. using openssl (less reliable, but doesn't require java):

    openssl pkcs12 -export -nokeys -in path/to/your/cert -out /etc/openelis-global/truststore

Ensure keystore/truststore permissions are all correct

Ensure all keystores have global read permission

sudo chmod 644 /etc/openelis-global/keystore /etc/openelis-global/truststore /etc/openelis-global/client_facing_keystore

Download OpenELIS Global

  1. Install OpenELIS Global

    a. Download latest installer package Here: 

    curl -L -O https://url_for_the _file.tar.gz

    b. EG: for OE 2.3 : 

    curl -L -O https://www.dropbox.com/s/zrk5127xrg8cn6g/OpenELIS-Global_2.3.2.2_Installer.tar.gz

  2. Unpack and enter the installer by running the following commands in Terminal, Mobaxterm, or Putty, replacing all in the { } with the appropriate values

    tar xzf OpenELIS-Global_{installer_version}_Installer.tar.gz

cd OpenELIS-Global_{installer_version}_Installer

    a. EG: tar -xvf OpenELIS-Global_2.3.2.2_Installer.tar.gz b. cd OpenELIS-Global_2.3.2.2_Installer/

  3. Optionally configure your install by editing setup.ini

    Find the section [DOCKER_VALUES] and set provide_database=True if you would like to use a Docker database

  4. Run the install script in Terminal or Putty

    sudo python3 setup_OpenELIS.py

Install OpenELIS Global

OpenELIS Global uses the following file to set things like the consolidated server address, it is not overwritten by the installer. /var/lib/openelisglobal/secrets/extra.properties

  1. Set the site identification number for this instance a. The site number is used to set the default test order prefix, and to identify the system to the consolidated server and other data systems.

  2. Set the time zone for OpenELIS Application a. Select the region that your country is in a. Select the country a. Verify the time zone

  3. Enter in the keystore password we set earlier
  4. Same with the truststore
  5. Enter an encryption key, this will help secure your data by encrypting your database

OpenELIS uses FHIR for much of its internal and external communication, if you don't know what the options mean, leave them at the default.

  1. Local FHIR store is the link to the local FHIR API
  2. The remote FHIR store is used in the use case where OpenELIS is polling for lab orders and returning results. EG: the FHIR2 Module for OpenMRS
  3. The Consolidated Sevrer is a central server which collects lab data for reporting, serves as a master facility list, etc.

Wait while install procedure completes

Please note: OpenELIS Global 2.x is designed for and is testing on Chrome only. Please be sure to use Chrome for OpenELIS.

  1. Check if OpenELIS is running at https://{server_ip_address}:8443/OpenELIS-Global/

Default user: admin Default password: adminADMIN!

Configure the backup:

Follow the SOP at: Backup Configuration

To set the identifier for this particular instance, use the /var/lib/openelisglobal/secrets/extra.properties file, and set the organization value to the same identifier as is set in the consolidated server FHIR location object. EG: org.openelisglobal.remote.source.identifier=Organization/8136bd30-901c-4d47-b133-72de813404ee

Run OpenELIS Global 2 With Docker Compose

  1. Install Docker and Docker Compose

  2. Clone the OpenELIS Global repository.
    For Open Elis Global 2.7.x 

    git clone https://github.com/I-TECH-UW/OpenELIS-Global-2.git

    For the Open Elis Global 2.8.x 

    git clone https://github.com/I-TECH-UW/OpenELIS-Global-2.git -b 2.8

  3. Move to the Project directory 

     cd  OpenELIS-Global-2

  4. Start the containers

    docker-compose up -d

For OpenELIS Global 2.7.x ,you should acces the Instance at https://localhost:8443/OpenELIS-Global/

For OpenELIS Global 2.8.x , you should acces the instances at https://localhost/ for the new UI and https://localhost/api/OpenELIS-Global/ for the Old UI