Search the OSCAR Documentation
< All Topics
Print

Docker for OSCAR 19

Updated
ByPeter Hutten-Czapski
Share this

Introduction

Docker is a technology that is used to contain component applications and their processes. Docker is lighter than virtual machines and depends on the underlying operating systems kernel for many functions. For OSCAR the advantage is that you can deploy OSCAR’s dependencies and have all of them configured independent on which Linux platform you have chosen.

This tutorial is about deploying OSCAR 19 in a Docker on Ubuntu 22.04. NOTE that these instructions are still EXPERIMENTAL, Incomplete, and not tested in Production . For production work we still suggest the currently recommended Ubuntu LTS instructions for OSCAR DEBs that the community has extensive experience with.

Document Version History

  • v0.1 – Initial instructions for LTS Ubuntu 22.04 – Nov 14, 2022
  • v0.2 – Simplified for latest WAR and source in revisit-oscar19-support – Dec 30, 2022
  • v0.3 – Updated Docker installation (Adrian Starzynski) – Sep 20, 2023

Prerequisites

Check that:

  • You have at least one hour to spare. YMMV
  • While the OSCAR server may run on recent CPUs with 2GB RAM I consider 3GB a minimum. I suggest aiming to consumer grade machines with 8GB RAM for 1-3 MD’s increasing to server grade machines with 32GB for 7+ MD’s. Server grade machines offer component redundancy and improved reliability that is an advantage in any setting, but all systems need contingency plans for hardware failure. The author runs Intel Xeon server with 72GB RAM and hardware RAID as well as a i7 backup server with 16GB RAM for a database that is 8GB (compressed) in size and has 24 users
  • You have installed the 22.04 64 bit LTS version of Ubuntu Jammy Jellyfish either natively or as a VM. The desktop version is slightly easier to debug for testing and the server version is “lighter” and more suitable for production. Both have been tested with OSCAR and are publicly supported by Ubuntu to April 2027 and with inexpensive subscription to 2032.
  • You have a basic level of Linux knowledge and you can open a Linux terminal You can cut and paste EXACTLY the following instructions (These instructions are sensitive to spelling packages and order. ) There are significant disadvantages of trying ANY other version of the software versions specified herein unless you have extensive OSCAR configuration experience. Better to get it running on spec and only then try something a bit different.

NOTE: Firefox will copy with Control+C while a Linux terminal requires Shift+Control+V for paste

Installing The Infrastructure Packages

You will need to install Docker. Here we are using the docker version found in Ubuntu repos. Don’t mix versions.

sudo apt install docker docker-compose

Now you need to ensure that Docker starts at boot if not already set

sudo systemctl enable docker
sudo systemctl start docker

Add User to Docker Group in Ubuntu

Add your non privileged user to the Docker Group

sudo usermod -aG docker $USER

You have to (logout and) log back in to get your group membership evaluated.

Install Open OSP

Now install the code for Open OSP which configures the needed containers. These instructions deviate slightly from the originals at https://github.com/open-osp/open-osp

While in your user’s home directory (to go home, just run cd ~ ), then run the cutting edge (still twitching) docker script

git clone -b revisit-oscar19-support --single-branch https://github.com/open-osp/open-osp.git

There are a number of scripts in the bin directory that can be called by openosp $1 $2 … where $1 is the command and the $2 etc are the options

  • openosp-build this builds the war and docker image for the component that is passed eg openosp build oscar or expedius faxws
  • openosp-setup this generates passwords and secrets (if no local.env) and copies the location specific property files to docker volumes
  • openosp-bootstrap make a new database sourcing the LOCATION from local.env and cloning the OSCAR_REPO and then calling populate-db (it also runs setup-faxws.sh)
  • openosp-purge don’t use this as it will delete OSCAR related files and drop the database and remove volumes
  • openosp-backup to stop expedius and trigger backups openosp backup -m for manual backup to send to aws
  • openosp-publish to push to dockerhub the version based on the date
  • openosp-update to update the openosp docker image. This only works if you are not using the open-osp repo to build and have set a release tag version
  • openosp-start to start (bring up) containers if needed. It stops any that are running and sequentially starts the database, oscar and then expedius, it doesn’t do anything to faxws

Run the setup to start the process by generating a local.env file.

cd open-osp
./openosp setup ontario

Answer the prompts or just hit enter to go through. In any case you can edit oscar.properties later if you change your mind.

Grab a coffee while the script generates keys and setups docker volumes for OSCAR drugref Expedius and faxws for you over the next 6 or 7 minutes.

Now run the below command. Allow it about 15 minutes for the download of OSCAR’s source, 3 more for dependencies, and just a few minutes for compilation.

./openosp build oscar

After that finishes you can setup and load the default schema with

./openosp bootstrap

To start OSCAR 19 for the first time run

./openosp start

Then log in with the default credentials at http://localhost:8080/oscar

username: oscardoc
password: mac2002
pin: 1117

It’s that simple.

Ontario Properties File

You want eventually to edit oscar.properties away from the defaults.

nano volumes/oscar.properties

Restart OpenOSP to have the new settings take with

./openosp start

Time Zone

The default will set the server time zone to Pacific Standard time. You can adjust the Docker overrides

nano docker-compose.override.yml

Switch TZ: America/Vancouver for each container to actual, usually TZ: America/Toronto for Ontario

environment:  TZ: America/Toronto

Restart OpenOSP to have the new settings take with:

./openosp start

HTTPS (SSL)

SSL is essential for securing connections on your server. You can adjust the Docker overrides to adjust the exposed ports

nano docker-compose.override.yml

The docker convention is exposed external port : port within the docker container. You will want to block http access to the container by commenting out 8080, and expose https with removing the # on the 8443 line.

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

This will reveal a SSL connection with a self signed certificate.

You will need to run docker-compose for the container to have the new settings take.

docker-compose up -d oscar

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 preferably leave the http connection at 8080 and use webserver like NGINX to serve the SSL connection via reverse proxy.

Updates

Updating Open OSP

Simply run git pull

Updating OSCAR To Current Source

First delete the existing OSCAR

docker rm open-osp_oscar_1 -f

OPTIONAL: If you want to completely start from scratch delete your local source by deleting

sudo rm -rf docker/oscar/oscar

Now simply run the build script

./openosp build oscar

Updating OSCAR to a Specific Build

Simple!

Download the war you want from from the downloads directory for oscaremr at bitbucket. Then use the following adapted to your desired build to install the particular build.

./openosp build oscar ~/open-osp/oscar-19.2784.war

Remember to update your properties (see above) with the build number and to reload the containers with

./openosp start

Update the Schema

To update the database to your new build run all the update sql files in OSCAR 19 source from the date of your prior build (you did put the date in the properties file?) to the current.

They are found in the source at https://bitbucket.org/oscaremr/oscar/src/stable/database/mysql/updates/ and are dated in the file name eg. update-2022-11-11.sql

Troubleshooting

Can’t Log In

Check the properties file to ensure that the db_password is set to the one listed in local.env and that billregion=ON

nano volumes/oscar.properties

The generated MariaDB passwords will be in the environment file

nano ~open-osp/local.env

Drugref2

Drugref requires that you populate the database oscar>admin>integration>update drugref.

If the drugref update is not working check the properties file to ensure the password has been set.

nano volumes/drugref2.properties

The generated MariaDB passwords will be in the environment file above

nano ~open-osp/local.env

Logging

Logging has been directed to Docker workflows. To check the log for a container first determine which one you want with

~/open-osp$ docker-compose ps
    Name                   Command            State         Ports                     
---------------------------------------------------------------------------
open-osp_db_1         docker-entrypoint.sh mysql ...   Up      3306/tcp                                       
open-osp_expedius_1   catalina.sh run                  Up      8080/tcp,                                      
                                                               0.0.0.0:8081->8081/tcp,:::8081->8081/tcp       
open-osp_faxws_1      /entrypoint.sh catalina.sh run   Up      8080/tcp                                       
open-osp_oscar_1      /entrypoint.sh /startup.sh       Up      0.0.0.0:8443->443/tcp,:::8443->443/tcp,        
                                                               8080/tcp

pick your container (lets check MariaDB which is the open-osp_db_1 container) and use its name to get the log

~/open-osp$ docker logs --tail=10 -f open-osp_db_1
2022-12-21 11:34:32 44 [Warning] Aborted connection 44 to db: 'oscar' user: 'root' host: 'open-osp_oscar_1.open-osp_back-tier' (Got timeout reading communication packets)

MariaDB

Configuration other than the default should by done in an eternal my.cnf referenced in the override file docker-compose.override.yml thus

  db:
    environment:
        TZ: America/Toronto
    volumes:
      - ./volumes/my.cnf:/etc/mysql/conf.d/my.cnf

You will need to restart the container with

docker-compose up -d db

The generated MariaDB passwords will be in the environment file local.env above

nano ~open-osp/local.env

This will open up the local environment file which shows the randomly generated MYSQL password under “MYSQL_ROOT_PASSWORD=”

To access the database you need to execute a command in the running “db” container. Use docker-compose to provide a bash shell for the db container.

docker-compose exec db bash

Then with the password from local.env in hand you can run the mysql command (in the container) as you would natively

mysql -u root -p'*******'

and that will open the MariaDB command line to do your work

Console

Note that the container has by design limited resources set by docker-compose and are not to be adjusted internally. Be that said you might want to temporarily tweak or check something. To do that, say open a bash shell for oscar

docker-compose exec oscar bash

Now you can say tail a log (although this can also be done with the docker command described earlier)

tail -f /usr/local/tomcat/logs/catalina.out

Your bash shell will close when the container is shutdown or restarted

Out of Hard Drive Space

If your container runs out of space simply redirect the Documents to a new hard drive. Note that Docker does not play well with symlinks, so changing ./volumes/OscarDocument to a link will fail. Instead change the path to OscarDocument to the actual in docker-compose.override.yml. As per usual the exterior (OS) facing setting comes first and the internal setting (in this case mounting point) is followed by a colon. If you new harddrive is mounted on /media you may need to do something like:

  oscar:
    volumes:
      - /media/peter/doc/OscarDocument:/var/lib/OscarDocument

You will need to run docker-compose for the container to have the new settings take.

docker-compose up -d oscar

Unfinished Business

Neither faxing nor backups have been tested for Docker OSCAR 19.  For inspiration read the notes at Open OSP github repo and instructions for docker Open OSP

Table of Contents