Docker for OSCAR 19
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
Timezone
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
./openosp start
CAUTION: Remove unused/dangling docker images: docker image prune
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