Search the OSCAR Documentation
< All Topics

Installation of OSCAR 19 on Ubuntu 20.04


These instructions are well tried and true.  At this time (late 2022) we continue to recommend these installation instructions as the default ones for OSCAR servers in production use.    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

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


It is assumed that:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. You have a basic level of Linux knowledge and you can open a Linux terminal
  6. You can cut and paste EXACTLY the following instructions (These instructions are sensitive to spelling packages and order. )
  7. 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 at the bottom), 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

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 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

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.

B. Manual Configuration

If you want to use a certification authority other than a self signed one or Certbot to secure your connection you will need to create a CSR and send it to an authority for certification.
Create a key using Keytool.  For simplicity, I would recommend the keystore password contained within /etc/TOMCAT9/server.xml and use this throughout the process for all password requests.
keytool -genkey -alias tomcat -keyalg RSA -keysize 2048 -keystore YOURDOMAIN.jks
TIP: Its not intuitive but you must specify a fully qualified domain for the “first and last name” when prompted.
Create a CSR file 
keytool -certreq -alias tomcat -file csr.txt -keystore YOURDOMAIN.jks
Upload your CSR as directed to the appropriate website and await receipt of your pem-chain file
Download your pem-chain file and convert it to a p7b file
openssl crl2pkcs7 -nocrl -certfile PEMCHAINFILE -out RESULTINGFILE.p7b
Import yourp7b file
keytool -import -trustcacerts -alias tomcat -file RESULTINGFILE.p7b -keystore YOURDOMAIN.jks  
Edit your server.xml file to something like the following (you will need to add the keyAlias line):
<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" 

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-headless

Test 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


OSCAR uses wkhtmltopdf to print some pdf content.  There are two versions of that program.  One is the version that you can apt install from an Ubuntu repository, which is feature restricted but usually gives good output.  It is not updated frequently.

If you are using a version of Ubuntu that has a GUI interface (desktop) it will be running X11 and you can use the following to install version 0.12.5 or newer.  Do not use this version if you are installing a headless server (see instructions in the version notes instead)

sudo apt install wkhtmltopdf

Test it to check the resultant pdf to see that it has the following output and displays correctly.

$ wkhtmltopdf -s Letter -T 10mm -L 8mm -R 8mm --print-media-type --disable-smart-shrinking --enable-local-file-access test.pdf
The switch --print-media-type, is not support using unpatched qt, and will be ignored.The switch --disable-smart-shrinking, is not support using unpatched qt, and will be ignored.Loading page (1/2)
Printing pages (2/2)                                               

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-java

This 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)
   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/mysqld

OPTIONAL: 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 [email protected] 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 tomcat9

This 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

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\ Debian\+Ubuntu\ deb\ Package/oscar_emr19-49~1508.deb

Now simply run the package and follow the instructions

sudo dpkg -i oscar_emr19-49~1508.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

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 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/ 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/ --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) 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 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 ( .   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 settings

You have successfully installed a plain OSCAR and you can start playing with it.

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


Note that Tomcat 9 is only newly supported. Early DEB’s are likely to fail on one or several grounds that have been fixed in current DEBs. If you need an older DEB the solution may be to install the latest and then downgrade the WAR to the one in the earlier WAR by installing the old DEB over the successfully installed new DEB.

  • Database errors. MariaDB 10.3 uses strict mode. Some early databases have definitions that are not supported
  • Cache. OSCAR is huge and requires a lot of caching. Newer debs set context.xml <Resources cacheMaxSize=”102400″ />
  • Access to custom directory. To access OSCAR files the tomcat9.service has to have an entry ReadWritePaths=/usr/share/oscar-emr/
  • 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.

For migration from OSCAR 15 see the section on updates and migrations

Latest OSCAR deb Packages Available from Sourceforge (RSS display):

Table of Contents