Installation of OSCAR 19 on Ubuntu 22.04

UpdatedNovember 23, 2024

By Peter Hutten-CzapskiPeter Hutten-Czapski

Preface

This basic install is adequate for a local install of OSCAR 19 with scripted encrypted backups and Secure Socket Layer technology.

Document Version History

v0.1 – Initial instructions for LTS Ubuntu 22.04 daily build – March 29, 2022
v0.2 – Instructions for LTS Ubuntu 22.04 beta with some reformatting – April 1, 2022
v0.3 – Instructions for LTS Ubuntu 22.04 release candidate – April 14, 2022
v1.0 – Instructions for LTS Ubuntu 22.04 updated to reflect latest DEB and added Troubleshooting – April 29, 2022
v1.1 – Instructions for LTS Ubuntu 22.04 updated with even more Troubleshooting – Oct 10, 2022
v1.2 – WKHTMLTOPDF hardening, added locale screenshot, and promoted instructions to the default for new production – Jan 10, 2023
v1.3 – Switched from default-jre (openjdk-11) to openjdk-8 to limit struts exposure – Feb 10, 2023
v1.4 – Workaround for Tomcat 9 bug in Ubuntu to support openjdk-8 – Feb 22, 2023
v1.5 – Updated for August 2023 release of Ubuntu 22.04.03 – September 22, 2023
v1.6 – Added link to wkhtmltopdf notes, fixed test parameter – February 20, 2024
v1.7 – Various cleanups, and switching to Java 11 as preferred install to simplify instructions – August 29, 2024
v1.8 – Fixed troubleshooting instructions for context.xml to <Resources cachingAllowed=”true” cacheMaxSize=”1255800″/> – September 16, 2024
v1.9 – NVC references added – September 16, 2024

Prerequisites

Check that:

You have at least two hours to spare. Downloading the Ubuntu ISO will take half an hour at 2 MB/s. Allow a minimum of 30 minutes to install Ubuntu, 15 minutes to install the infrastructure packages, 5 to download the OSCAR DEB and a final 18 minutes to install OSCAR itself. YMMV
We recommend virtualization for enterprise level equipment. A virtualization environment (hypervisor) allows you to install one or more servers as virtual machines (VM) to improve security and ease maintenance. When provisioning the VM consider that the base install of Ubuntu and OSCAR will need about 15 GB and should have 3GB RAM allocated at a minimum for testing.
You are using suitable hardware. 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.
For Production Use, if you are able to manually provide the password after a power outage or reboot, we strongly recommend configuring Ubuntu for *full disk encryption* which will mitigate the privacy breech that occurs with physical theft of the server.
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

TL; DR

Well then lets give the skinny

sudo apt install openjdk-11-jdk tomcat9 unzip curl pgpgpg ufw wkhtmltopdf
sudo apt install mariadb-server mariadb-client libmariadb-java

Now skip to the configuration of MariaDB section for the tricky bits

Installing The Infrastructure Packages

WE REITERATE It’s a newbie error to deviate from these instructions in favour of something newer or “easier.” For production use we recommend these exact instructions as the community can support you if you are having problems. If you are both familiar with OSCAR and are testing or are willing to take chances when you colour outside the lines feel free to deviate from the instructions as you wish (review the version notes), and if its substantive deviation (and it works), please submit back your version.

Java 8, 11, 17, 19, 21

In Ubuntu 22.04 you have the option of Java’s including 8, 11, 17 and 19. All but 19 are LTS releases and have been tested against OSCAR 19. Java 21 is new and has not been fully tested with all of OSCAR systems. We recommend openjdk-11.

sudo apt install openjdk-11-jdk

You can test by the following

java -version openjdk version "11.0.24" 2024-07-16 OpenJDK Runtime Environment (build 11.0.24+8-post-Ubuntu-1ubuntu322.04) OpenJDK 64-Bit Server VM (build 11.0.24+8-post-Ubuntu-1ubuntu322.04, mixed mode, sharing)

If you have multiple Java versions installed the system Java can be changed with

update-alternatives --config java There are 2 choices for the alternative java (providing /usr/bin/java). Selection Path Priority Status ------------------------------------------------------------ * 0 /usr/lib/jvm/java-11-openjdk-amd64/bin/java 1111 auto mode 1 /usr/lib/jvm/java-11-openjdk-amd64/bin/java 1111 manual mode 2 /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java 1081 manual mode

If you have multiple javas installed, Tomcat may not necessarily be picking up the system version if another Java is listed for JAVA_HOME in /etc/default/tomcat9

Tomcat 9

Java uses Apache Tomcat to present OSCAR’s webpages to your internet browser from the Universe repository.

sudo apt install tomcat9

This will trigger the installation of the following additional packages tomcat9-common libtcnative-1 libtomcat9-java

JAVA 8: Tomcat 9 in Ubuntu 22.04 is compiled with Java 11. To use it with Java 8 you need to patch Tomcat with the following (it does no harm if you later upgrade to a newer Java)

sudo apt install libecj-java
sudo ln -s /usr/share/java/ecj.jar /var/lib/tomcat9/lib
sudo systemctl restart tomcat9

Test by pointing your browser at http://localhost:8080

For a headless server you can test by installing a non graphical browser such as lynx. Otherwise test from another machine by replacing localhost with the IP of the server.

If you don’t get a welcome screen then it is likely that Tomcat is not picking up your java, see troubleshooting in the Java section above.

Unzip Curl

Unzip is used to decompress zip files. Curl is an internet file transfer utility. Pgpgpg is optionally used by OSCAR to encrypt charts for export. Uncomplicated Fire Wall (ufw) will secure the server. Unzip and UFW are probably already installed. Apt-get them to be sure

sudo apt install unzip curl pgpgpg ufw

Certbot (optional)

Certbot will register your server with Lets Encrypt so that external browser access to the OSCAR will be with a green padlock for a trusted connection.

To install certbot execute the following

sudo apt install certbot

Certbot sets up a temporary standalone webserver that needs to communicate on port 80 to the lets encrypt server to authenticate that you are the owner of the website. If your server is behind a router/firewalls you will need to open port 80 on your router and forward that port as port 80 on your server. Those instructions vary by router. In the following replace FQDN with your the fully qualified domain name that you own (eg www.example.org)

sudo certbot certonly --standalone -d FQDN

Test by checking if there are files as below

sudo ls /etc/letsencrypt/live/FQDN cert.pem  chain.pem  fullchain.pem  privkey.pem  README

The OSCAR Deb installer will install the certificate for you when it runs, alternately if no certificate is found it will generate a self-signed certificate and install that instead.

To re-certify expired certificates you can use a cronjob similar to the script in /usr/share/letsencrypt.sh

TIP if you edit any of the /usr/share/ *. sh scripts remember to rename it to something else or a Deb upgrade will overwrite it

wkhtmltopdf 0.12.6

OSCAR uses wkhtmltopdf to print some pdf content for eforms and faxing. Recent debs will harden wkhtmltopdf or you can do so manually as described in Version notes – Notes on wkhtmltopdf

sudo apt install wkhtmltopdf

If after you finish installing OSCAR your eForms PDF fine then there is no need for further testing. Otherwise it is advised that you test with the parameters that you have in oscar,properties for the keyword WKHTMLTOPDF_ARGS

Currently the DEB will configure something that could be tested with the following

wkhtmltopdf -s Letter -T 10mm -L 8mm -R 8mm --print-media-type --enable-local-file-access http://oscargalaxy.org test.pdf

If you get an error with the wkhtmltopdf, you can skip it entirely (New) or install the patched version. See the Software Version Notes for more information Version notes – Notes on wkhtmltopdf

MariaDB 10.6

OSCAR uses this database to store your data. You can use the latest version of MariaDB obtained with:

sudo apt install mariadb-server mariadb-client libmariadb-java

OPTIONAL: If you want to install phpmyadmin (not described but basically apt install it choosing lighttpd and the default configuration script) as a MariaDB front end, do it NOW before the next step.

This installation has no initial password and will need to be secured with the following Configuration section (follow the scripts suggested defaults EXCEPT for switching to unix socket authentication where you should answer n)

The plugin prevents non system root users from logging in to MariaDB, but allows for root users to log in to MariaDB directly without a password. By removing the plugin everyone (including OSCAR via the unprivileged tomcat user) can, and has to, sign into MariaDB by providing the MariaDB password.

Configuration MariaDB

Run the mysql_secure_installation scipt. Do NOT switch to unix_socket authentication. The root password (for MariaDB) will not be set (it will be blank). Change it. Feel free to use numbers and letters in your password. If you proceed with the complication of using symbols “#,!, &,*, (, ), / , \, = and $” in this password (e.g. pass&word), be sure to escape them when providing them to scripts below where the instructions supply ****** that require it (e.g. pass\&word).

$ sudo mysql_secure_installation
Switch to unix_socket authentication [Y/n] n
Change the root password? [Y/n] 
New password: 
Re-enter new password: 
Remove anonymous users? [Y/n] 
Disallow root login remotely? [Y/n] 
Remove test database and access to it? [Y/n] 
Reload privilege tables now? [Y/n]

Now there will only be the one root user set for MariaDB with the password you provided.

Installing OSCAR 19

Download the OSCAR deb package from Sourceforge. There are several to choose from. You want the latest DEBs in the feed

RSS Feeds

The naming format is oscar_emr{OSCAR_VERSION}-{DEB_VERSION}~{BUILD}.deb

Install the latest as package support for Ubuntu 22.04 is just being finalized.
Note OSCAR is now running a rolling release and thus stability is not necessarily improved by a higher build number.
Once installed if you are experiencing bugs wait for a new release and try either upgrading to a higher number build (the last 4 digits of the deb’s name) that incorporates the fix, or downgrading to an earlier deb that does not have the problem.

All are at http://sourceforge.net/projects/oscarmcmaster/files

The latest deb will be named slightly different than exampled below for oscar_emr19-94~4489.deb.

wget http://sourceforge.net/projects/oscarmcmaster/files/Oscar\ Debian\+Ubuntu\ deb\ Package/oscar_emr19-94~4489.deb

Now simply run the package and follow the instructions

sudo dpkg -i oscar_emr19-94~4489.deb

The deb will provide feedback as to what it is doing however if you want more verbose details open another terminal window and invoke

sudo tail -f /usr/share/oscar-emr/Oscar19install.log

New installs get the following install screens. (for upgrades see Appendix 1 below)

Start by providing the location. Choose BC only if you need to bill the BC MSP.

Then provide the MySQL/MariaDB password you assigned earlier.

This window will give you the option to populate the database with a demo patient with which to develop familiarity with OSCAR.

You can remove the demo data later with the following (replace ****** with your MariaDB/Mysql password, escaping any symbols (if any) that you used in the password).

mysql -uroot -p******* oscar_15 <  /usr/share/oscar-emr/undemo.sql

While customary production settings will be applied, they can be changed manually through editing /usr/share/tomcat9/oscar.properties in your favorite text editor. Note that OSCAR/Tomcat need to restart whenever the properties file is modified, to have the settings take effect.

BE PATIENT The terminal will provide feedback as OSCAR is assembled and configured. Your output may differ slightly from the below

Selecting previously unselected package oscar-emr.
(Reading database ... 163142 files and directories currently installed.)
Preparing to unpack oscar_emr19-76~2798.deb ...
Unpacking oscar-emr (19-76~2798) ...
Setting up oscar-emr (19-76~2798) ...
NOTE: Picked up JDK_JAVA_OPTIONS:  --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.rmi/sun.rmi.transport=ALL-UNNAMED
Edited tomcat9.service to allow Tomcat 9 read write on /usr/share/oscar-emr and /tmp
Setting initial defaults for areacode  in ON
 [x] Checking the MySQL password  success
 [x] Creating an apparmor profile for wkhtmltopdf success
 [x] Determining locale  success
 [x] Creating the new oscar_15 database  success
 [x] Expanding War files success
 [x] Populating database with ON data  success
 [x] Populating database with OLIS data  success
 [x] Patching database to very latest schema success
 [x] Populating database with Demo data  success
 [x] Configuring Tomcat  success
 [x] Creating Drugref2 Property Files  success
 [x] Updating drugref database  success
 [x] Applying TallMAN rules to drugref  success
 [x] Installing Ontario Specific eForms  success
 [x] Installing HRM xml files  success
 [x] Installing Ontario Rourke eForm under licence  success
 [x] Restarting Tomcat  success
Successful installation of oscar deb revision 76~2798
Login at https://localhost:8443/oscar
Your username is oscardoc
Initial password mac2002
second level password (pin) 1117

Login at https://localhost:8443/oscar
Your username is oscardoc
Initial password mac2002
second level password (pin) 1117

Allow for a good quarter hour for the deb to run. Once Tomcat restarts you will be given back the prompt.

You can read the readme!

less /usr/share/oscar-emr/README.txt

Trying It Out

At this point you have a fairly plain install. To test the connection, click on the link displayed on the output above or open your web browser and type in the address manually. While most new proprietary browsers (Chrome, Safari, Edge etc) will work, for production use we strongly recommend FireFox ESR version, for stability, for tested OSCAR features and a large number of grease monkey addons that you can get on these pages. Did I mention Firefox is open source and doesn’t sell your data?

If you installed oscar_emr19-94~4620.deb or a later version you should install the data (immunization types and lot numbers) from the National Vaccine Catalog through the Administration section with the following instructions https://oscargalaxy.org/knowledge-base/nvc/

Troubleshooting

With luck everything will work as designed. However life sometimes is challenging. These are some simple solutions to potential issues that may come up.

First check the Tomcat log catalina.out that is in /var/log/tomcat9
Note: If catalina.out is not there, try journalctl -u tomcat9.service --since "2024-07-20" to see all tomcat9 related messages since 2024-07-20
Tomcat won’t start. Check sudo service tomcat9 status . If an illegal property is passed in /etc/default/tomcat9 for JAVA_OPTS tomcat will not start
OSCAR runs but you are having issues with uploading any file on the system. This could be that the directories are not allowed
- Edit tomcat9.service override with sudo systemctl edit tomcat9 to ensure the allowed read write directories to include /tmp/ and /usr/share/oscar-emr/
  - [Service]
    ReadWritePaths=/usr/share/oscar-emr/
    ReadWritePaths=/tmp/
- If that does not suffice comment out the #BASE_DOCUMENT_DIR in oscar.properties and manually set the following
  - eform_image = /usr/share/oscar-emr/OscarDocument/oscar/eform/images/
    HOME_DIR = /usr/share/oscar-emr/OscarDocument/oscar/billing/download/
    DOCUMENT_DIR = /usr/share/oscar-emr/OscarDocument/oscar/document/
    OMD_hrm=/usr/share/oscar-emr/OscarDocument/oscar/hrm/
    OMD_directory=/usr/share/oscar-emr/OscarDocument/oscar/hrm/OMD/
    OMD_log_directory=/usr/share/oscar-emr/OscarDocument/oscar/hrm/logs/
    OMD_stored=/usr/share/oscar-emr/OscarDocument/oscar/hrm/stored/
    OMD_downloads=/usr/share/oscar-emr/OscarDocument/oscar/sftp_downloads/

Tomcat log complains about sufficient cache “Unable to add the resource at [/WEB-INF/classes/e2e/datatypes-base.xsd] to the cache for web application [/oscar]”.

To increase cache:

sudo nano /var/lib/tomcat9/conf/context.xml

Add the following line before </Context>:

<Resources cachingAllowed="true" cacheMaxSize="1255800"/>

That should do but be warned that an overriding cache directive may also be referenced in:

/etc/tomcat9/context.xml
/usr/share/tomcat9/etc/context.xml
/usr/share/tomcat9-root/default_root/META-INF/context.xml
/var/lib/tomcat9/webapps/ROOT/META-INF/context.xml
/var/lib/tomcat9/webapps/oscar/WEB-INF/classes/META-INF/context.xml

The cache itself is stored in /var/cache/tomcat9/Catalina/

Tomcat log complains about missing children. OSCAR needs all its libraries expanded. Sometimes the expansion fails. If so simply delete the expanded directories which will force a redo expansion from the war archive

sudo rm -rf/var/lib/tomcat9/webapps/oscar