Personal tools
You are here: Home / Self Book / Installation


Installation of the self book project


These instructions are adequate for a local instance of the selfbook project for development work. 

Document Version History

  • v1.0 – initial public release on – Oct 10, 2016
  • v1.1 - update to .war path and additional setup notes - Sep 21,2017
  • v1.2 - update to .war path to use https - Feb 15, 2019
copyright by Peter Hutten-Czapski 2016-2019 © under the Creative Commons Attribution-Share Alike 3.0 Unported License


  1. Preface
    1. Document Version History
  2. Prerequisites
  3. Overview
  4. War File Installation


It is assumed that
  1. You already have a recent OSCAR installed
  2. You have a moderate level of Linux knowledge.


Configuring and installing the self book project involves two servers.

  1. The original OSCAR itself.  These instructions will work for OSCAR 12.1 and newer
  2. The selfbook server.  This is the server that administers appointment setting, and is normally accessed directly by the client/patient

These servers can be on the same machine or separated. 

If you are installing on the same machine as an OSCAR 15 instance you can skip the details for installing Java and Tomcat and start with the War file installation section

Separate Selfbooking Server

Java 8 Installation

Technically any Java 7 or newer may do, however development is done on Oracle Java 8.

Details on Oracle Java PPA approach:

Paste this lines on your root prompt and accept the Oracle License terms:

echo "deb xenial main" | tee /etc/apt/sources.list.d/webupd8team-java.list
echo "deb-src xenial main" | tee -a /etc/apt/sources.list.d/webupd8team-java.list
apt-key adv --keyserver hkp:// --recv-keys EEA14886
apt-get update
apt-get install oracle-java8-installer
Oracle Java 8 should now be installed and you should get automatic updates for future Oracle Java 8 versions.

Test it if needed:

# java -version
java version "1.8.0_91"
Java(TM) SE Runtime Environment (build 1.8.0_91-b14)
Java HotSpot(TM) 64-Bit Server VM (build 25.91-b14, mixed mode)

 Tomcat 7 Installation 

The following instructions will install Tomcat 7

sudo apt-get update
sudo apt-get install tomcat7

Now stop the tomcat7 service

sudo service tomcat7 stop
Stopping Tomcat servlet engine tomcat7 [ OK ]

Run the following command in your console to edit JAVA_HOME in the default tomcat7 start-up configuration file:

sudo nano /etc/default/tomcat7

Change the JAVA_HOME option to the following:


Save the file and you are done. Tomcat will now start using the Oracle JDK instead of OpenJDK when you start the tomcat7 service

sudo service tomcat7 start

Check to ensure that Tomcat is running and you are running on the Oracle JDK


Now change to a directory and then skip to the instructions that follow for setting up SSL work

cd /var/lib

SSL connections for Everyone

SSL, or Secure Socket Layer, is a technology which allows web browsers and web servers to communicate over a secured connection.For My Oscar the major use is for security to ensure that the data being sent is encrypted by one side, transmitted, then decrypted by the other side before processing

You can set up SSL connection via Tomcat with the instructions below.  If you need lower port numbers or need to run a full web server you can set up SSL with Apache (see Installing Oscar to run on port 443)

a) Prepare a Certificate

Use the Java keytool to generate a key for tomcat using standard RSA encryption.  Use the same password for both the keypass and the storepass (technically they don't have to be the same for Tomcat 7 but its simpler this way)/  Remember to use your own password instead of the placeholder "liyi". 

sudo $JAVA_HOME/bin/keytool -genkey -alias tomcat -validity 3650 -keyalg RSA -keystore /var/lib/tomcat7/.keystore -keypass liyi -storepass liyi
You will be prompted for your name (supply your server IP or domain),  organizational unit (clinic), organization (.),  city, province and country. The result is a hidden .keystore file in the tomcat7 directory. 

Now reference the generated keystore in the tomcat configuration file. Activate those connectors in server.xml specification taking care that you don't conflict with another services that might be using those ports.

sudo nano tomcat7/conf/server.xml

Now adjust the data so it looks something like the below (ports 8090 and 8091 used below as they don't conflict with default Tomcat6 settings) changing the location of the keystore File and the keystore password to match the actual ones you used. 

   <Connector port="8090" protocol="HTTP/1.1"
               redirectPort="8091" />  
   <Connector port="8091" protocol="HTTP/1.1" 
               keystorePass="liyi"   />

b) Install Oscar's Server Certificate

Copy over the base64 certificate from the -BEGIN CERTIFICATE- to the -END CERTIFICATE- you are using on the Oscar server.  if you can't access the certificate easily (you can view the certificate in FireFox) the following script may help

# usage: [port]
echo |\
openssl s_client -connect ${REMHOST}:${REMPORT} 2>&1 |sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'

sample usage to extract the certificate for an Oscar server on accessed on ssh on port 8443 would be > oscar_certificate.file

Now add the certificate you are using for the OSCAR server to the myoscar's Java 7 keystore 

$JAVA_HOME/bin/keytool -import -alias oscar -file oscar_certificate.file -keystore /var/lib/tomcat7/.keystore

You will be prompted for the passwords for the keystore, the certificate to be imported will be displayed, and then you will be asked if you Trust it

Trust this certificate? [no]:  Yes
Certificate was added to keystore

Now reciprocate for the self book server's certificate on the OSCAR server.

Installation Combined with OSCAR *OR* Separate Server Installation

The following steps need to occur if you are installing the selfbook server on the same machine as OSCAR or if you have followed the above instructions and are installing on a separate server.

War File Installation

Copy the binary war files from Sourceforge to tomcat webapps (aka $CATALINA_BASE) as below. 

sudo cp selfbook.war /var/lib/tomcat7/webapps/selfbook.war


The source is in Git.  Clone the source self_book project.  Then change to the projects directory and compile with maven and copy the resultant to the tomcat webapps directory. 

Most of these components  are built against java.   The following are not requirements per se but are versions that work for compiling

- oracle jdk1.8.0_101
- maven 2.2.1

For the selfbook server use the following.  Sometimes you need to specify to skip the tests for the war to compile.
mvn package -Dmaven.test.skip=true
sudo mv target/*-SNAPSHOT.war /var/lib/tomcat7/webapps/selfbook.war


Config.xml Settings

Edit /var/lib/tomcat7/webapps/selfbook/WEB-INF/classes/config.xml

If you are using self signed SSL certificates as installed by DEB or listed above you will probably need to enable that

<!-- set to true to allow self signed certificates / -->

This URL is used to provide links sent by email for the confirming and canceling functions.  Thus you must provide an address that can be reached from the internet and not localhost.  Ensure that you end the URL with /


Selfbook needs to communicate with the oscar server to determine available appointments and to book them.  For a selfbook installation on the same server as OSCAR set the URL as below, otherwise replace localhost with the LAN or internet accessible address.  Ensure that you end the URL with /

If that doesn't work configure with out the terminal /


Then set the user for selfbook that you will configure in OSCAR as per the Configuration section.   In consistency with the Configuration section I am using selfbook as the user, but you can use any receptionist role restricted OSCAR user here.


Provide the password for this user.  As no one will be typing it anywhere else, make the effort to make it strong (random with at least one number, one uppercase letter, one lowercase letter and one special symbol) and long (over 16 characters).


Optional NO confirmation Emails:

The default settings will not send an email to allow for appointment confirmation and cancellation, but will display a message on the webpage that implies that one is sent.  If you choose not to send the email then you should blank the string values found in the /var/lib/tomcat7/webapps/selfbook/WEB-INF/classes/string_tables/ for the following keys


OPTIONAL Confirmation Emails:

Resultant plain text emails will be sent such as

 John Smith,


An online appointment has been made in your name and email address (

) for an medical appointment from our website.

Please click this link to validate your email to confirm your appointment.



Appointment Date: Thursday, 2016-10-20, 10:30 AM

with Dr Hutten-Czapski Peter


You have confirmed that you been registered with the above family doctor.


Your appointment can be refused or modified if the information is incorrect.




To cancel your appointment, click this link


If you want to send these emails for for appointment confirmation and cancellation then adjust the password and salt which allows for an encrypted link to be sent to the patient.  The link is encrypted so that selfbook can perform the required function on the correct appointment, without providing any information about the appointment, or allowing someone to manually cancel or confirm appointments.  The salt needs to be written in hexadecimal (ie numbers 1-F where F represents 16 in hex).  It has to be random, be at least 8 bytes in length and has to have an even number of characters.  Note that if the key length is incorrect there will be an error before the appointments are displayed in the app (nothing will display for the user).  If that happens you might need to install Unlimited Strength security policies into your java.


Then set your email and SMTP settings

                 <!-- this is the name for the "sender" for the email -->
                 <senderName>OSCAR Selfbook</senderName>
            <!-- Standard port 25, 465 or 587 -->
          <!-- Debug setting to send to this email instead -->
          <!-- Debug setting when true to print the message to log instead -->

Booking Configuration

The actual booking setup is done using the booking.xml file (or demobooking.xml) which is in /var/lib/tomcat7/webaps/selfbook/WEB-INF/classes/demo

Note: Make a backup of the file before you change it!

Most of the information in the file can be changed and will take effect immediately. There is no need to restart tomcat.

In the algorithm section, if the answerType = "listprov", you must supply the valid provider number(s) in the validation field.  The list should be prefixed and suffixed with a space. (eg. validation=" 1000 1001 1002 "

In the allowedProvider section, you must have valid providers. You can make the alias and providerNo the same.  If you specify invalid providers, the page will not appear.  The alias is used if you need different options for the same provider. (eg. Annual Exam - 60 min or Follow-up - 10 min) 


External Settings


TIP: If you are going to be re-installing the war, rather than redoing this every time, copy this modified configuration outside the application itself and reference it when you start tomcat.  To do that pass a system parameter of "-Doscar_selfbook_portal_config=override.xml" where override.xml is an xml config file which trumps the default one. 

There are several ways of adding in the system parameters, as a series of files and locations are checked for this type of configuration when tomcat starts up.  You can look that up if you like.

One way of doing this is to put this information into /etc/default/tomcat7

For this purpose we want to add a parameter to JAVA_OPTS. Add the following line AFTER

the JAVA_OPTS line that is already in the file

JAVA_OPTS="${JAVA_OPTS} -Doscar_selfbook_portal_config=/var/lib/tomcat7/webapps/selfbook_override.xml"

Obviously you will also specify in the selfbook.override.xml an alternate location for the booking configuration XML file

Document Actions