Upgrading Your OSCAR Server

UpdatedJuly 10, 2024

By Peter Hutten-CzapskiPeter Hutten-Czapski

Preface

These instructions are a method of transferring production from one Ubuntu to a newer Ubuntu. They have been lightly tested with conversion of OSCAR 19 from Ubuntu 18.04 to Ubuntu 22.04 but are generic. This is advanced Oscar Service Provider type work and this overview is thin lightly tested gruel. Consider hiring someone with experience with the inner workings of OSCAR as might be found on the oscarmcmaster-devel list server (subscribe at sourceforge oscar mcmaster)

Document Version History

v0.1 – Initial instructions for LTS Ubuntu 18.04 conversion – Jan 10, 2023

Prerequisites

Time. You can test transfer at anytime at any rate but your final transfer should be done with no time pressure
Fortitude. This is finicky work and almost never goes smoothly.
A DEB installed OSCAR on an older Ubuntu
Comfort of the Linux command line
Understanding of how to use the command line to do a backup, restart Tomcat, roll back the DEB, create and load ssh keys etc
Insight as to what functionality of OSCAR you depend on
Backups

Step 1 – Prepare the previous OSCAR

Best to make sure everything is up to date and working

Do NOT try to upgrade your old Ubuntu as it will break OSCAR but you can apply the latest system updates as suggested by the Ubuntu Update Manager.

Backup your existing production and have at hand the existing DEB so that you can roll back to your prior state.

Upgrade your production to the latest OSCAR DEB and check all functionality. The newest DEB should transform any problematic tables in your database to be accepted by the newer MariaDB that exists in the newer Ubuntu.

If this is not working you should not proceed. You will need to roll back your install with your previous DEB, and if is really off, restore your Backup.

Step 2 – Prepare a new Server

Create a new OSCAR server on the latest Ubuntu with the same latest DEB based on the instructions on this site. The new DEB will prepare the latest Tomcat to specifications that will accept OSCAR and its file structures.

Load the test data and check all functionality. Do not forget to test saving a document and eform image as this is where Tomcat 9 requires the most work to configure. If you have problems check the troubleshooting suggestions at the bottom of the OSCAR installation instructions.

Save the oscar.properties on your new server as new.properties

Transfer over your previous oscar.properties,restart Tomcat, and check all functionality again.

Step 3 – Dump a Copy of the Database

Change to the documents directory and create a backup file. Replace ${DBPWD} with your mysql password

cd /usr/share/oscar-emr/OscarDocument
sudo mysqldump --opt --dump-date --single-transaction --skip-lock-tables oscar_15 -uroot -p${DBPWD} > OscarBackup.sql

Step 4 – Transfer the documents

A simple rsync from the new to the old will get the existing documents, AND the OscarBackup.sql file.

sudo rsync -aW --exclude 'oscar/oscar_backup.sh' --progress --chown=tomcat:tomcat --rsh='ssh -C -p22' ${REMOTE_USER}@${REMOTE_IP}:/usr/share/oscar-emr/OscarDocument /usr/share/oscar-emr/

Note that you are likely needing to change the file permissions on some of the files (chmod -R 644 /usr/share/oscar-emr/OscarDocument/oscar/) on the source server to ensure that they can be copied. The first file can be copied, the second won’t.

-rw-r--r-- 1 tomcat8 tomcat8 130185 Jan 11 11:36 /1079083746.pdf_1.png
-rw-r----- 1 tomcat8 tomcat8 20650 Jan 12 06:36 /LabUpload.0AB609.HL7.1673523363574

If you have HRM files some directories will be drwxr-x— and thus their contents cannot be read without a chmod

Step 5 – Load the Database

Load the schema

mysql -uroot -p${DBPWD} oscar_15 < /usr/share/oscar-emr/OscarDocument/oscar/OscarBackup.sql

Test that the data is correct and that functionality is intact.

Step 6 – Rinse and Repeat

When you have established a successful transfer, repeat steps 3-5 with your latest data and transfer production to the new server

Troubleshooting

This troubleshooting guide covers how Oscar works and some things you can check when it doesn’t. These notes are relevant for a normal installation of Oscar v15/19 with Ubuntu 16/18.

Unable to login to server: If you have physical access to the server, you can always press the ‘c’ key while booting to get a command prompt. If the server uses Passphrase authentication and Password authentication is off, you can change the /etc/ssh/sshd_config file. Change PasswordAuthentication to yes. Save the change and reboot. It should now ask for a password instead of a passphrase.
Don’t have root access: If your login does not have root access, you can boot the server into the command prompt (see above). Eg. If the username is ‘oscar’, then ‘usermod -aG sudo oscar’ will add oscar to the sudo group. Restart the server to try it.
Unable to login to MySQL: There are lots of instructions online to explain how to reset the root mysql password.
Tomcat doesn’t start / No Oscar login screen: There are multiple settings that need to be correct before Tomcat can present a login screen. Check ‘/var/log/tomcat#/catalina.out’ for fatal errors. The basic tomcat settings are in ‘/etc/tomcat7/server.xml’. Look for the ‘Connector port’ to confirm you are using the correct port. Values are usually 8443 or 8080. The oscar application is in ‘/var/lib/tomcat#/webapps/’. You should see multiple folders like ‘drugref’ and ‘oscar’. The ‘oscar’ folder contains all the code expanded from the .war installation file. The oscar properties files are in ‘/usr/share/tomcat#/’. The foldernames in ‘/var/lib/tomcat#/webapps/’ is usually an exact match with the properties file in ‘/usr/share/tomcat#/’. So ‘/var/lib/tomcat#/webapps/oscar’ would have important parameters in ‘/usr/share/tomcat#/oscar.properties’. Key parameters are ‘db_name’, ‘db_password’ and ‘tomcat_path’.