Dockerized Open OSP’s EMR on Ubuntu 22.04
Documentation Copyright © 2023 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
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 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
- v0.2 – Minor tweaks/fixes – Feb 8, 2023
- 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)
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.”
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
Follow the setup instruction prompts.
To create the databases for OSCAR, Expedius, FaxWS, and DrugRef, run:
Then start the application with:
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:
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.
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:
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:
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=”
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 (cd into open-osp directory first)
c). Check all other Fax related settings. Ie: consultation_fax_enabled=yes
2). Add the “Fax Server Credentials”:
Retrieve the fax server credentials (the db password is in local.env):
docker-compose exec db bash
mysql -u root -p[db password] OscarFax
select * from OscarFax.users;
NOTE: the faxws user’s password can also be found in the local.env file (FAXWS_TOMCAT_PASSWORD=)
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
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.
In the open-osp directory, to update the Docker container’s image, run:
docker pull 2020.11.06
docker pull openosp/open-osp:latest
Then set the image version tag in docker-compose.override.yml to the desired version i.e.:
Update the environment scripts (while in the open-osp directory):
git pull origin master
Restart the OSCAR environment:
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 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
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:
3. Also specify your clinic’s name (as a slug) with CLINIC_NAME in the Docker
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.
Setup a cronjob on your host to run ./openosp backup -m — s3
First check the container name (this will return a list of the containers including the database, expedius, faxws, and OSCAR):
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
To tail the logs for the MariaDB container (container name goes in place of sdf):
Accessing the OSCAR Container’s Linux CLI
First you need to find the container ID:
Then run the following (replace container_id with your openosp/open-osp container ID):
docker exec -it container_id /bin/bash
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)
Clark Van Oyen (Countable)
Dennis Warren (OpenOSP)