Getting started with a manual installation
Marc Dumontier
Raymond Rusk
This guide is not meant to be used for deploying a production ready OSCAR database. It provides the minimal steps to get OSCAR running on your system, does not configure any security or backups.
As an alternative to this guide, which may be dated, see the installation instructions at (Current) OSCAR EMR 15 Installation. The later is being maintained.
Introduction
This guide is all about deploying OSCAR in the most minimalist way not using the DEB packaging. Why? You may want to customize how the system is deployed to better match your current processes. Being able to quickly change Java and Tomcat versions can also be a benefit of this type of install.
Prerequisites
You'll need more skills than the DEB installation. Make sure you're well versed with
- Linux 14.04 install
- GIT
- MySQL
- Tomcat7
Install mysql
Generally, it's best to stick to the Ubuntu packages. When you install mysql from Ubuntu 14.04.5 you get MySQL 5.5 which is what OSCAR EMR has been mostly used against in the real world. Be prepared for some potential problems if you go for Ubuntu 16.04 at the time of writing.
sudo apt-get install mysql-server
Install Java
The best thing to do is to install the ORACLE JRE from the binary package into a single directory, and then softlink to it. Then it's easy to update Java at any time without having to
- Uninstall your current installation
- Change environment variables
Begin by downloading the Java SE Development Kit 8 for your Architecture (tar.gz) and installing it in /opt. Note that your versions/directory could be different.
sudo tar -xzvf jdk-8u121-linux-x64.tar.gz -C /opt sudo ln -s /opt/jdk1.8.0_121 /opt/java
Update your Environment
echo "export JAVA_HOME=/opt/java" >> ~/.profile echo "export PATH=\$JAVA_HOME/bin:\$PATH" >> ~/.profile source ~/.profile
Check that you're all good
$java -version java version "1.8.0_121" Java(TM) SE Runtime Environment (build 1.8.0_121-b13) Java HotSpot(TM) 64-Bit Server VM (build 25.121-b13, mixed mode)
Install Apache Tomcat
Apache Tomcat installs can be done in very much the same way we handled Java installations. Download the latest Tomcat from Apache. You're going to want the latest 8.0.x binary distribution (.tar.gz) as of the date on this document.
Follow the following commands, changing the versions where it makes sense.
Note: This isn't meant for a production environment or anything. Remember minimalist approach in this document. You should really create a tomcat user, and make CATALINA_BASE writeable for that user. This is really just to demonstrate the basic steps for a workable setup.
sudo tar -xzvf apache-tomcat-8.0.41.tar.gz -C /opt sudo ln -s /opt/apache-tomcat-8.0.41 /opt/tomcat sudo chown -R marc:marc /opt/apache-tomcat-8.0.41 #replace marc:marc with your username:group..whoami
Start it up
$/opt/tomcat/bin/startup.sh Using CATALINA_BASE: /opt/tomcat Using CATALINA_HOME: /opt/tomcat Using CATALINA_TMPDIR: /opt/tomcat/temp Using JRE_HOME: /opt/java Using CLASSPATH: /opt/tomcat/bin/bootstrap.jar:/opt/tomcat/bin/tomcat-juli.jar Tomcat started.
Access it at http://localhost:8080/ (or whatever IP you're using)
Install OSCAR EMR
Ok, that was the warmup. OSCAR EMR needs a few things to run
- an initialized database
- a properties file with a few minimal settings
- a WAR
We start by choosing a version to install, and grabbing the artifacts. This is available on JENKINS (OSCAR EMRs Continuous Integration System). Here is the link for the latest OSCAR 15 (Even more recent than DEBs, this is equivalent to nightly builds).
https://demo.oscarmcmaster.org:11042/job/oscar15BetaMaster/lastSuccessfulBuild/artifact/
Let's download everything in a zip
Initialize the DB
cd database/mysql chmod +x createdatabase* ./createdatabase_on.sh <user> <password> oscar loading oscarinit.sql... loading oscarinit_on.sql... loading oscardata.sql... loading oscardata_on.sql... loading icd9.sql... changing to caisi directory... loading initcaisi.sql... loading initcaisidata.sql... changing back to the mysql directory... loading icd9_issue_groups.sql... loading measurementMapData.sql... loading expire_oscardoc.sql all done! the default user is oscardoc password mac2002 pin 1117 For security reasons these credentials are set to expire in a month!
Install a properties file to your home directory (or home directory of the user running tomcat)
cd target jar xf oscar-14.0.0-SNAPSHOT.war WEB-INF/classes/oscar_mcmaster.properties cp WEB-INF/classes/oscar_mcmaster.properties ~/oscar.properties
Next change a few lines..just enough to boot this up
db_name = oscar?zeroDateTimeBehavior=round&useOldAliasMetadataBehavior=true&jdbcCompliantTruncation=false db_username = root db_password = <password> BASE_DOCUMENT_DIR=/var/lib/OscarDocument/ #make sure this exists, and permissions are ok
Lastly, deploy the WAR, and restart Tomcat.
cd target /opt/tomcat/bin/shutdown.sh cp oscar-14.0.0-SNAPSHOT.war /opt/tomcat/webapps/oscar.war /opt/tomcat/bin/startup.sh
You can now access OSCAR with your browser at http://localhost:8080/oscar/
your log file is /opt/tomcat/logs/catalina.out