Installation of OSCAR 19 on Ubuntu 20.04
Preface
These instructions are well tried and true. This basic install is adequate for a local install of OSCAR with scripted encrypted backups and Secure Socket Layer technology on Ubuntu 20.4.
Note that instructions for newer distributions such as Ubuntu 22.04 and other Debian based linux are also available.
Document Version History
- v1.5 – Initial instructions for LTS Ubuntu 20.04 – Oct 5, 2021
- v1.6 – Updated to Open Java 11 – Nov 1, 2021
- v1.7 – Updated MariaDB authentication configuration – Jan 18, 2022
- v1.8 – Promoted to production status – Feb 3, 2022
- v1.9 – Added note in Troubleshooting concerning IOFileUploadException when uploading documents – Jun 19, 2022
- v2.0 – Added Manual SSL setup per Bradeon Hendy – Oct 30, 2022
- v2.1 – Replaced instructions for wkhtmltopdf to those for internal htmltopdf – Dec 27, 2022
Documentation Copyright © 2012-2022 by Peter Hutten-Czapski MD under the Creative Commons Attribution-Share Alike 3.0 Unported License
Manual SSL instructions provided by Braedon Hendy Copyright © 2022
Prerequisites
It is assumed that:
- You have the time. Allow a minimum of 30 minutes to install Ubuntu, 11 minutes to install the infrastructure packages, and a final 15 minutes to install OSCAR itself. Downloading the software adds additional time and is dependent on your connection and can take 20 additional minutes @150KB/s.
- 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.
- We do not assume you are using a virtual machine (VM) but we recommend it 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.
- You have installed the 20.04 64 bit LTS version of Ubuntu. Both desktop and server versions have been tested and are supported to April 2025. We strongly recommend *full disk encryption*, if you are able to manually provide the password after a power outage or reboot.
- 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
WE REITERATE Its a noob 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 better 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.
First ensure that the Universe repository is available (it probably is) and regardless update to ensure that the appropriate packages are available.
sudo add-apt-repository universe
sudo apt update
sudo apt upgrade SSL configuration (optional)
Note if you don’t use Certbot the Deb installer will still configure a secure https connection for you with a self signed certificate. Use Certbot it you have a fully qualified domain name FQDN (I mean you own your website name eg www.example.com).
A. Certbot
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 certbotCertbot 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 FQDNTest by checking if there are files as below
sudo ls /etc/letsencrypt/live/FQDN
cert.pem chain.pem fullchain.pem privkey.pem READMEThe OSCAR Deb installer will install the certificate for you when it runs.
B. Manual Configuration
keytool -genkey -alias tomcat -keyalg RSA -keysize 2048 -keystore YOURDOMAIN.jks
keytool -certreq -alias tomcat -file csr.txt -keystore YOURDOMAIN.jks
openssl crl2pkcs7 -nocrl -certfile PEMCHAINFILE -out RESULTINGFILE.p7b
keytool -import -trustcacerts -alias tomcat -file RESULTINGFILE.p7b -keystore YOURDOMAIN.jks
<Connector port="8443" maxHttpHeaderSize="8192" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" acceptCount="100" scheme="https"
secure="true"enableLookups="false",disableUploadTimeout="true" clientAuth="false"
keystoreFile="LOCATIONTOYOURFILE/DOMAIN.jks"
keystorePass="PASSWORDTHATYOUWILLYSE"
sslProtocol="TLS"
keyAlias="tomcat"
...
JAVA 8 or 11
The Open JDK 11 packaged by Ubuntu is the default recommendation. For other choices see version notes
$ sudo apt install openjdk-11-jre-headlessTest with (your output will be slightly different):
$ java -version
openjdk version "11.0.11" 2021-04-20 OpenJDK Runtime Environment (build 11.0.11+9-Ubuntu-0ubuntu2.20.04) OpenJDK 64-Bit Server VM (build 11.0.11+9-Ubuntu-0ubuntu2.20.04, mixed mode, sharing))Setting the Java for the one you want
While you may only have the above java you just installed you should make sure that if some other software installed a different version that you have the above configured for OSCAR. You should check and change what /usr/bin/java points at with update-alternatives BEFORE you run the OSCAR DEB
$ update-alternatives --config java There are 4 choices for the alternative java (providing /usr/bin/java). Selection Path Priority Status ------------------------------------------------------------ 0 /usr/lib/jvm/zulu17/bin/java 2173001 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 3 /usr/lib/jvm/java-8-oracle/jre/bin/java 1081 manual mode 4 /usr/lib/jvm/zulu17/bin/java 2173001 manual mode
in this example there are four Java configured and Openjdk 11 is set as the default
Other Infrastructure Dependencies
Html To PDF
To enable the internal html to pdf converter used for converting eForms to pdf for faxing, attachments or printing, you need to install the following documented dependencies :
- libc6 (or glibc)
- libx11
- libxext
- libxrender
- libstdc++
- libssl1.0 (or libssl1.1)
- freetype
- fontconfig
The following will get those dependencies and a few more that are not documented but may be needed depending on the eForm
sudo apt-get install ca-certificates fontconfig libc6 libfreetype6 libjpeg62 libpng16-16 libssl1.1 libstdc++6 libx11-6 libxcb1 libxext6 libxrender1 xfonts-75dpi xfonts-base zlib1g
For legacy reasons OSCAR still supports wkhtmltopdf (see version notes for hardening suggestions) as an alternative.
MariaDB 10.3
OSCAR uses this database to store your data. You can use the latest version of MariaDB obtained on Ubuntu 20.04 Universe re with:
sudo apt install mariadb-server mariadb-client libmariadb-javaThis installation has no initial password and will need to be secured with the following (follow the scripts suggested defaults)
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
Enter current password for root (enter for none):
Set 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.
You can check that it is installed with the following
$ sudo systemctl status mariadb
mariadb.service - MariaDB 10.3.22 database server
Loaded: loaded (/lib/systemd/system/mariadb.service; enabled; vendor preset: enabled)
Active: active (running) since Tue 2020-05-12 13:38:18 UTC; 3min 55s ago
Docs: man:mysqld(8)
https://mariadb.com/kb/en/library/systemd/
Main PID: 25914 (mysqld)
Status: "Taking your SQL requests now..."
Tasks: 31 (limit: 2345)
Memory: 65.6M
CGroup: /system.slice/mariadb.service
└─25914 /usr/sbin/mysqldOPTIONAL: If you want to install phpmyadmin (not described) as a MariaDB front end, do it now before the next step.
Log into the MariaDB server with that ‘root’ user and provide the password you just set with the following command:
$ sudo mysql -uroot -p
Enter password:
Welcome to the MariaDB monitor. Commands end with ; or \g.
Your MariaDB connection id is 61
Server version: 10.3.31-MariaDB-1ubuntu1 Ubuntu 20.04
Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
MariaDB [(none)]>
Then you will want OSCAR to be able to login without using the unix_socket plugin to pass Linux root credentials. Supply the MariaDB password to replace ****** below
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 the non privileged tomcat user) can, and has to, sign into MariaDB by providing the MariaDB password.
MariaDB [(none)]>ALTER USER root@localhost IDENTIFIED VIA mysql_native_password;MariaDB [(none)]>SET PASSWORD = PASSWORD('******');
Tomcat 9
Java uses Apache Tomcat to present OSCAR’s webpages to your internet browser from the Universe repository.
sudo apt install tomcat9This will trigger the installation of the following additional packages tomcat9-common libtcnative-1 libtomcat9-java
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
Installing OSCAR
Download the OSCAR deb package from Sourceforge. The latest DEBs are listed in the feed at the bottom of this page. There are several to choose from.
The naming format is oscar_emr{OSCAR_VERSION}-{DEB_VERSION}~{BUILD}.deb
- The progression of any release is alpha, beta, release candidate, and then general release which reflects the amount of formal and informal testing that the build has undergone
- We recommend the latest OSCAR 19 general release for production
- Note that stability is not necessarily improved by a higher build number.
- If you are experiencing bugs, try either upgrading to a higher number build (the last 3 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 following version is the FIRST one that is supported to install on Ubuntu 20.04. The latest filename or path may be slightly different than exampled below.
wget http://sourceforge.net/projects/oscarmcmaster/files/Oscar\ Debian\+Ubuntu\ deb\ Package/oscar_emr19-49~1508.debNow simply run the package and follow the instructions
sudo dpkg -i oscar_emr19-49~1508.debThe deb will provide feedback as to what it is doing however if you want more verbose details open another terminal window and invoke
tail -f /usr/share/oscar-emr/Oscar19install.logNew installs get the following install screens. (for upgrades see Appendix 1 below)
Start by providing the MySQL/MariaDB password you assigned. OSCAR will use it to set up a modernized version of the oscar_15 database for OSCAR 19.
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.
The terminal will provide feedback as OSCAR is assembled and configured.
Selecting previously unselected package oscar-emr.
(Reading database ... 1460065 files and directories currently installed.)
Preparing to unpack oscar_emr19-49~1508.deb ...
Unpacking oscar-emr (19-49~1508) ...
Setting up oscar-emr (19-49~1508) ...
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
Tomcat 9 already has read write on /usr/share/oscar-emr
Setting initial defaults for areacode 705 in ON
[x] Checking the MySQL password 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 49~1508
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) 1117Allow 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.txtTrying 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 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?
Whatever browser you choose you should see the OSCAR login page with clicking on one of the following links.
In most cases you will be prompted to reach your SSL secured OSCAR server at https://localhost:8443/oscar .
Firefox will complain with an “insecure connection” error as the certificate is either self-signed, or it is a proper certificate but accessed on the local network and not on what you supplied for the FQDN (www.something.org) . As it is your installation you can safely click on “Advanced” and set an exception and proceed to your OSCAR server.
Sometimes you get an Apache Tomcat error page indicating that the resource (oscar) is not available. This usually will occur if you have inadequate memory allocated (see above for minimum and suggested provisioning).
Rarely if the installer was unable to configure SSL for you, the deb will warn you that your installation may be INSECURE but will work at http://localhost:8080/oscar
In the latter case, if you had not already done so please manually secure your Oscar server using standard instructions for hardening for Tomcat 8 provided by Apache and others on the web.
The initial login parameters for OSCAR are as follows:
User Name: oscardoc Password: mac2002 PIN (Second Level Passcode): 1117
When you login, you will be presented with a one time password reset for security purposes. 8 characters upper and lower case numbers and symbols are required in a password with default oscar.properties settings
Version Notes
The above is tested as the default installation that works with the DEB. Certain variations are supported, some of which are mentioned here. Everything else is not tested and will likely require more time than you think to get it to work (usually accomplished by backtracking to the above tested methods)
See the article on software and versions for variations and considerations when using other software as well as duration of open source security patches with end of life dates for various components of the OSCAR stack.
For finishing security touches see the second article in this series
Troubleshooting
Things happen. Over time we have run into a number of instalation issues that can be easily fixed.
- 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
- Error when uploading documents: ‘Processing of multipart/form-data request failed. Stream ended unexpectedly’ This can be fixed by changing protocol=”org.apache.coyote.http11.Http11NioProtocol” to protocol=”org.apache.coyote.http11.Http11Nio2Protocol” in /etc/tomcat9/server.xml, then restarting Tomcat.
- OSCAR runs but you are unable to upload a file. 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/ - The tomcat9.service has to have an entry ReadWritePaths=/usr/share/oscar-emr/. Edit tomcat9.service override with sudo systemctl edit tomcat9 to list the allowed directories to include /tmp/ and /usr/share/oscar-emr/
[Service]
ReadWritePaths=/tmp/
ReadWritePaths=/usr/share/oscar-emr/
- eform_image = /usr/share/oscar-emr/OscarDocument/oscar/eform/images/
- Cache. 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]”. OSCAR is huge and requires a lot of caching. Newer debs set context.xml <Resources cacheMaxSize=”102400″ />
To increase cache:
sudo nano /var/lib/tomcat9/conf/context.xmlNote that there are a number of files that will give cache information to Tomcat:
/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
Add the following before </Context>:
<Resources>
cachingAllowed="true"
cacheMaxSize="1012000"
</Resources>The cache is stored in /var/cache/tomcat9/Catalina/
Catalina logs are in /var/log/tomcat9
- Database errors. MariaDB 10.3 uses strict mode. Some early databases have definitions that are not supported
For migration from OSCAR 15 see the section on updates and migrations