Search the OSCAR Documentation
< All Topics
Print

Dockerized Open OSP’s EMR on Ubuntu 22.04

UpdatedDecember 31, 2022
By Peter Hutten-CzapskiAdrian Starzynski

Documentation Copyright [c] [y] by Adrian Starzynski with a few liner notes from Peter Hutten-Czapski for Docker OSCAR 19 under the Creative Commons Attribution-Share Alike 3.0 Unported License

Preface

Open OSP’s EMR was forked off the main OSCAR trunk circa 2018.

Since Open OSP’s EMR is for the Docker platform, you could theoretically run it on any computer that can run Docker containerized application environment. Containerized applications have some benefits such as ease of maintenance, deployment on demand, ease of scaling and life cycle management, improved security by isolating applications from the host system and from each other, and faster app startup. Read more about containerization here: The Benefits of Containerization and What It Means for You – IBM Cloud Blog

With containerized OSCAR, you don’t have to manage OSCAR’s infrastructure packages like java, tomcat, mariadb, wkhtmltopdf, etc. since the containerized deployment does that for you.

Open OSP is also open source, and the code is available here on Bitbucket. The OpenOSP docker deployment repo is here on Github.

Open OSP Service Cooperative is owned and operated by community members. It works well for BC use at this article’s time of publishing. If you are in Ontario, OSCAR v19 is currently a better choice for you as it includes more features geared towards Ontario physicians, related to billing and patient enrolment/enrolment physicians. If you are in British Columba, OpenOSP is a great choice for you as it is stable and supports BC billing.

Document Version History

v0.1 – Initial instructions for LTS Ubuntu 22.04 – Nov 18, 2022

Prerequisites

Check that:

  • You have at least 2 hours to spare.
  • You are using suitable hardware.
    • If you intend to run Open OSP on AWS, either use at least an AWS EC2 t2.medium instance for max. 2 MD’s (2vCPU, 4GiB memory), or a larger instance types for more MD’s. The benefits of AWS are that you can scale easily (increase processing power/RAM when necessary, no physical server maintenance, high reliability, etc.) If running on AWS, don’t forget to assign a static IP to your instance via “Elastic IPs” in the EC2 console.
    • For servers, aim for minimum 8GB RAM for max 2 MD’s, and 32GB for 7+ MD’s, with something like an Intel Xeon CPU. While server-grade machines offer higher reliability and redundancy, you still need to have contingency plans in place for hardware failure.
  • You have installed Ubuntu 22.04 Jammy 64-bit LTS either natively or as a VM. This version is publicly supported by Ubuntu until April 2027 and with an inexpensive subscription to 2032.
  • You have a basic level of Linux and terminal knowledge
  • You copy and paste EXACTLY the following instructions (instructions are sensitive to spelling and order)

Install Docker-Compose

What is Docker vs. Docker-Compose? Docker Compose is a tool for defining and running multi-container Docker applications. You use a .yml (YAML) file to configure your application’s services. Docker is the underlying application engine and is used to create images, and Docker Compose configures how Docker should run the containers of the application.

You *could* use the versions in the Ubuntu Repo, however its usually recommended that you get the latest versions of the docker software from docker themselves. DON’T do both as a version mismatch will cause a problem.

Add Docker’s Public GPG Key

Install the required packages:

sudo apt install apt-transport-https ca-certificates curl gnupg-agent software-properties-common

Add the key:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

Add Docker Repository

This automatically detects the system’s version (its jammy in case lsb_release -cs gives you trouble ) and gets the correct repo URL for the latest Docker release, and the GPG key that was configured in the previous step.

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Update APT Package Index Cache

Run the system update command which will rebuild the APT package index cache in order to recognize the latest Docker repository that was just added.

sudo apt update && sudo apt upgrade

Install Docker Compose

First check that you are using the Docker repo to source docker packages

$ apt-cache policy docker-ce
docker-ce:
  Installed: (none)
  Candidate: 5:20.10.21~3-0~ubuntu-jammy
  Version table:
     5:20.10.21~3-0~ubuntu-jammy 500
        500 https://download.docker.com/linux/ubuntu jammy/stable amd64 Packages
     5:20.10.20~3-0~ubuntu-jammy 500
        500 https://download.docker.com/linux/ubuntu jammy/stable

The correct output (above) is that it is not installed but available from download.docker.com. The version number will that that shown or incremented.

We need the latest version of the Docker engine, docker-compose plugin, and Docker CLI to be able to run the OpenOSCAR containerized application.

sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo apt-get install docker-compose

To check the version (expect Docker Compose version v2.12.2 or later) :

docker compose version

Enable and Start the Docker Service

For Docker to start on system boot, you need to enable it for systemctl (most of the time it will already be enabled):

sudo systemctl enable docker
sudo systemctl start docker

Add User to Docker Group in Ubuntu

Since you are running as non-root, and Docker needs root privileges to run, you need to add your current user to the docker user group. The Docker install should also create the docker user group, and you can check it by running grep docker /etc/group (you should see docker:x:999:ubuntu)
If the docker group does not exist, create it by running sudo groupadd docker
And then restart the docker service: sudo systemctl restart docker

Add the current user to Docker group:

sudo usermod -aG docker $USER

Now you need to log out and log back into Ubuntu so your group membership is re-evaluated. After you will be able to run Docker commands without using sudo or root.

I like to do a sudo reboot at this point to “clean things up.”

Install OpenOSP

While in your user’s home directory (to go home, just run cd ~ ), run the following:

git clone https://github.com/open-osp/open-osp.git
cd open-osp
./openosp setup

Follow the setup instruction prompts.

To create the databases for OSCAR, Expedius, FaxWS, and DrugRef, run:

./openosp bootstrap

Then start the application with:

./openosp start

You also use ./openosp start to restart OSCAR.

Now you can access OSCAR at http://localhost:8080/oscar (obviously replace localhost with your server’s IP/FQDN).

For a production environment, change the release to “release” in docker-compose.override.yml (by default it’s latest):

services:
  oscar:
    image: openosp/open-osp:release

Restart the application for the changes to take effect:

./openosp start

Populate the DrugRef Database

The medications list when prescribing won’t show any drugs until you populate the drugs database.

Login to your OSCAR with the default credentials:

  • Username: oscardoc
  • Password: mac2002
  • PIN: 1117

Go to Administration>Integration>Update Drugref and click on Update Drugref Database

After an hour or so, the drug tables should be updated and you should be able to search for medications in OscarRx.

SSL (HTTPS)

While in the open-osp directory, run:

sudo nano docker-compose.override.yml

Uncomment (remove #) from the line that has ‘8443:443’ so it looks like this:

  oscar:
    ports:
      - '8443:443'

If you want to disable non-HTTPS access to your OSCAR then comment out the line that has ‘8080:8080’ so it looks like this:

  oscar:
    ports:
      - '8443:443'
#      - '8080:8080'

Control+X , Y, and enter, to exit and save the changes.

Restart the container to apply the changes:

./openosp start

If you’re accessing the OSCAR server via public FQDN, you’ll definitely want SSL so the site shows as secure in the web browser. Otherwise if you have it installed locally, you can access your local server at https://yourserverip:8443/oscar but it won’t show as secure (you will need to proceed even though it says insecure, or type “thisisunsafe” while in the “insecure” browser tab to proceed – that’s the hidden passphrase to force open websites with an invalid SSL certificate).

Open OSP will install its own certificate with common name of “faxws” which is invalid, so it won’t show SSL by default.

You can either override the self-signed certificates located at open-osp/volumes/ssl.cert and open-osp/volumes/ssl.key with your own signed certs, OR preferrably use a proxy like NGINX, HaProxy, Cloudflare, etc. for easier certificate management, better security, load balancing, and overall more control over your server’s web requests.

Editing Properties File

While in the open-osp directory, run:

sudo nano volumes/oscar.properties

Customizing Login Screen

While in the open-osp directory:

cd volumes/OscarDocument/login

there is a file called “supportLogo.png” there by default which is the support provider logo that is displayed on the login screen. By default it’s OpenOSP’s logo. You can replace with what ever logo want.

If you don’t want a support provider logo to show then in this directory, run rm supportLogo.png which deletes the file.

To edit the clinic details that display on the login screen, you need to edit the hidden environment file, so run:

sudo nano .env

This file shows all the options for the login screen, such as the support link (link that displays for the support provider), support text (by default it’s OpenOSP’s ad, you can remove/change to what ever you wish and include HTML), support name, clinic details, clinic website link, clinic name, and tab name (name that shows in browser window tabs).

Accessing OSCAR Database CLI

While in the open-osp directory, run:

docker-compose exec db bash
mysql -u root -p

After entering the MYSQL password, now you’re in the mariadb CLI!

The root MYSQL password can be found by running nano local.env from the open-osp directory. This will open up the local environment file which shows the randomly generated MYSQL password under “MYSQL_ROOT_PASSWORD=”

Fax Setup

**AS OF 2022/11/18, FAXWS ON OPENOSP IS NOT WORKING YET DUE TO MISSING TABLES IN OSCARFAX DATABASE.***

There are a few “know-how” steps to enable the fax service. Fax service is known as “FaxWS” which means Fax Web Service.

1). Enable Faxing in properties 

a). $ pico volumes/oscar.properties

b). ModuleNames=Fax

c). Check all other Fax related settings. Ie: consultation_fax_enabled=yes

2). Add the “Fax Server Credentials”

Retrieve the server credentials: 

a). $ docker-compose exec db bash

b). $ mysql -u root -p[db password] OscarFax

c). $ select * from OscarFax.users

d). Note the “user_name” and “user_pass” values for the next steps

Set up Fax Server in the EMR:

a) log into the EMR

b). Administration / Faxes / Configure Fax

c). Under “Fax Server Credentials”

– Fax Server URL = https://faxws:443/faxWs

– Fax Server Username = user_name from previous step

– Fax Server Password = user_pass from previous step

d). Click on the Save button;  bottom left

Restart the EMR

$ docker-compose restart Oscar

Restart Fax Service

$ docker-compose restart FaxWs

Add the SRFax Gateway: a). Complete the values under Fax Gateway Accounts (leave the Fax Server Credentials as-is) User: SRFax Account Number
– Password: SRFax Password
– Fax Number: SRFax Fax Number (no punctuation)
– Email: your email address that was used as the SRFax main contact and login Inbox Queue: leave as default for now
– Enable/Disable Gateway: On
b). click Save 

Disclaimers:
These activities to enable Faxing are not pre-set in order to allow the installer a choice in what Fax Server method they wish to use. This set-up is not “bullet proof”, you may be required to apply some troubleshooting skills to get it running.  

OSCAR Update

In the open-osp directory, to update the Docker container’s image, run:

docker pull 2020.11.06

Then set the image version tag in docker-compose.override.yml to the desired version.

Update the environment scripts (while in the open-osp directory):

git pull origin master

Restart the OSCAR environment:

./openosp start

OSCAR Backups

The databases and OscarDocument directory needs to be backed up.

Backup methods will create backups for the OSCAR EMR database and OscarDocuments.

Off-Site Backups

Off Site backups can be configured to use AWS S3 Buckets. First set up a AWS S3 bucket and an IAM user with full S3 permissions to authenticate. Be sure to write down the IAM access key, secret key, and bucket name.

1. Then run the AWS configuration script

aws configure

2. Set the BACKUP_BUCKET variable in the Docker local.env file to the name of the AWS bucket (run sudo nano local.env) you created for your backups. Example:

BACKUP_BUCKET="clinic-backups-bucketname"

3. Also specify your clinic’s name (as a slug) with CLINIC_NAME in the Docker local.env

CLINIC_NAME=your_clinic_name

4. Run the backup process

./openosp backup -m --s3

TIP: Backups for a production environment will be quite large so the S3 storage may get quite expensive if you are storing everything as regular access S3 objects. If you are storing lots of backups on S3, setup a Lifecycle Rule for the bucket to switch old objects into a Glacier storage class, which is significantly cheaper than the standard regular access storage class.

Automated Backups

Setup a cronjob on your host to run ./openosp backup -m — s3

Log Access

First check the container name (this will return a list of the containers including the database, expedius, faxws, and OSCAR):

docker-compose ps

OSCAR Logs

Then tail the logs for the OSCAR container (container name goes in place of open-osp_oscar_1):

docker logs --tail=3000 -f open-osp_oscar_1

MariaDB Logs

To tail the logs for the MariaDB container (container name goes in place of sdf):

docker logs --tail=3000 -f open-osp_db_1

Accessing the OSCAR Container’s Linux CLI

First you need to find the container ID:

docker ps

Then run the following (replace container_id with your openosp/open-osp container ID):

docker exec -it container_id /bin/bash

Advanced Changes

For details on duping log history, changing log verbosity, melody performance profiling, migrating an environment across servers, updating database data, see the Github instructions for open-osp OSCAR: open-osp/open-osp: Modern Deployment and Operations for Oscar EMR (github.com)

Citations

Clark Van Oyen (Countable)

Dennis Warren (OpenOSP)

Table of Contents