Date Version Changes Owner. 14-Dec First Version JC. 14-Feb Version for release at City University JC

Transcription

1 Workshop - Installation Open Health Informatics John Chelsom 21st February 2011 Revision History Date Version Changes Owner 14-Dec First Version JC 14-Feb Version for release at City University JC 21-Feb Version for general release JC 2011 City University, London. Page 1 of 13

2 Table of Contents 1.Introduction Open Source Applications Apache Tomcat Orbeon Forms Protégé Serna Free XML Editor Additional Materials Creating a Base Version of Orbeon Starting and Stopping Tomcat City University, London. Page 2 of 13

3 1. Introduction This document describes the installation of the open source applications required to run the Open Health Informatics workshop. The following applications are required: Firefox web browser (any other modern browser can be used as an alternative) Apache Tomcat 5.5 Orbeon Forms 3.8 Exist native XML database (part of Orbeon installation) Protégé 4.1 Serna Free XML Editor These applications are available for installation on any platform (Windows, Mac, Linux) as described in this installation document. In addition, some other materials are required to run the workshop exercises and can be obtained from City University, London. Page 3 of 13

4 2. Open Source Applications 2.1. Apache Tomcat 5.5 Tomcat is required to run the Orbeon Forms application framework. If you already have Tomcat installed then you can add the Orbeon application as described below and don't need a fresh installation. If you have a different Java Application server running (e.g. JBoss, Jetty, etc) then Orbeon should run successfully using that. You need to have the Java Runtime Environment set up on your machine before installing Tomcat. Generally this will be set up by default on Apple Mac, but its not always there on Windows. To test whether the JRE is installed, open a command window and type: java -version If installed you should get a response similar to: java version "1.5.0_20" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_20-b02-315) Java HotSpot(TM) Client VM (build 1.5.0_20-141, mixed mode, sharing) If you need to install the JRE on Windows, do the following: 1. Download and install from: 2. an environment variable needs to be set up after the installation of the JRE: a. right click on the 'My Computer' icon and select 'Properties' b. select the 'advanced' tab c. click 'environment variables' d. under 'System variables' click 'New' e. enter JRE_HOME as 'variable name' and 'c:\program Files\Java\jre6' as 'variable value' (use the path where the JRE was initially installed). NOTE: You may also use the full JDK rather than just the JRE. In this case set the JAVA_HOME environment variable to the pathname of the directory into which you installed the JDK, e.g. c:\j2sdk5.0 or /usr/local/java/j2sdk5.0. Tomcat can be downloaded from You should select the core.zip file, download it and unzip the contents to a suitable directory you have created for it (e.g. called tomcat-5-5). We will refer to this directory as CATALINA_HOME. If you are running Windows you may instead run the service installer which is a wizard that will guide you through the installation of Tomcat as Windows service. Assuming you are installing from the.zip, you should now see a directory structure similar to the one below in CATALINA_HOME (screen shot is from a Mac) after unzipping its contents. On Mac or Linux systems you may need to change the permissions on the files so that all users have read, write and execute permission - run chmod -R 777 from the CATALINA_HOME directory. By default, Tomcat runs on port 8080 on localhost, so you may want to change the default settings in Tomcat (CATALINA_HOME/conf/server.xml) if you want to run it alongside existing servers City University, London. Page 4 of 13

5 You should now be able to start up Tomcat using the startup script provided with the installation in CATALINA_HOME/bin (startup.bat on WIndows systems, startup.sh on Mac/Linux/Unix systems). To do this you will need to open up a command window, change to the bin directory and type the command. For more details on starting and stopping Tomcat see Section 5. To check that Tomcat is running, open your web browser go to and you should see a page similar to the one shown below. If you have trouble, see the additional instructions in CATALINA_HOME/RUNNING.txt for how to resolve some common issues City University, London. Page 5 of 13

6 2.2. Orbeon Forms 3.8 Orbeon Forms can be downloaded from We will be using the free Community Edition, so you should select the option Download Orbeon Forms CE in the table which takes you straight to the download on the Orbeon zip file. To install, create a folder for Orbeon in CATALINA_HOME/webapps (e.g. called orbeon). Unzip the Orbeon files and place the contents into the folder you created. Once you have done this you should have a folder structure similar to the one below (screen shot from a Mac). To check out your Orbeon installation go to in your web browser and you should see a screen similar to the one shown below City University, London. Page 6 of 13

7 2.3. Protégé 4.1 Protege can be downloaded from Under the heading Protégé 4.1 Beta you should select the option for: Download Protégé - platform independent installer program You should now be taken to a page similar to the one shown below, from where you can download and run the installer for your platform (e.g. Windows, Mac, etc). You should choose the download for your platform without the Java VM. Follow the on-screen instructions, or view the instructions on the web page by clicking the appropriate link. On successful installation you should be able to start up Protege and see a first screen similar to the one shown below: 2010 City University, London. Page 7 of 13

8 2.4. Serna Free XML Editor Serna Free XML editor can be downloaded from You should select the correct download for your platform and follow the installation instructions provided. On successful installation you should be able to start up Serna Free and see a first screen similar to the one shown below (screen shot from a Mac) City University, London. Page 8 of 13

9 3. Additional Materials Note: these materials are due to be updated on Wednesday February 23rd. A final version will be available on memory sticks at the workshop due to run on Thursday February 24th. Other materials are required to run the workshop exercises and can be obtained from Download the zip file and unzip to a temporary directory. You should then see a directory structure similar to the one below (screen shot from a Mac). Move (or copy) the three directories xmlstore, ehr and formdata to the Tomcat directory: CATALINA_HOME/webapps You should now be able to go to the following three places in your web browser and see screens similar to the one shown below City University, London. Page 9 of 13

10 2010 City University, London. Page 10 of 13

11 4. Creating a Base Version of Orbeon The default Orbeon Forms installation comes with access to the documentation, Form Builder and Form Runner applications. Users can define their own forms-based applications and run them within the Orbeon 'skin'. However, using the Orbeon platform to run a single application without the additional Orbeon skinning requires some modifications to the default installation. The steps below show the modifications required to create a clean base installation upon which an application can be built. Assume Tomcat is installed in CATALINA_HOME and the application is called ehr. 1. Create a new folder for the application at CATALINA_HOME/webapps/ehr 2. Unzip the standard Orbeon distribution to this folder The Orbeon.war file that you download from orbeon.com is the standard distribution. On most systems you should be able to rename this file with a.zip extension, move to the folder you created and then double click to unzip. 3. Delete the contents of the folder CATALINA_HOME/webapps/ehr/WEB-INF/resources/apps 4. In this folder, create a new folder called ehr and copy to it a home page for the application. In the example below the home page is contained in a folder called views and is called ehr.xhtml. It references an image file called ohi.png in a folder called images. So both the views and images folders are located in: CATALINA_HOME/webapps/ehr/WEB-INF/resources/apps/ehr 5. You should now now have a folder structure as shown below (screen shot is from a Mac, but the Explorer will show a similar structure on Windows). 6. Now open the file page-flow.xml located in CATALINA_HOME/webapps/ehr/WEB- INF/resources 7. Modify the two <page> elements that look like: <!-- Redirect to the Home application --> <page id="root" path-info="/(welcome/?)?" matcher="oxf:perl5-matcher"> <action><result page="home"/></action> </page> 2010 City University, London. Page 11 of 13

12 <!-- Welcome application --> <page id="home" path-info="/home/" model="apps/home/page-flow.xml"/> to redirect to the ehr application as follows: <!-- Redirect to the EHR application --> <page id="root" path-info="/" view="views/ehr.xhtml"/> <!-- Handle any other pages that do not have a specifc rule --> <page path-info="/(.*)" matcher="oxf:perl5-matcher" view="oxf:/${1}"/> 8. In the directory CATALINA_HOME/webapps/ehr/WEB-INF/resources/config rename the file properties-local.xml.template to properties-local.xml 9. This can now be used to override the default properties used by Orbeon, including the stylesheet used to created each page. We want to remove the Orbeon styling (which makes all applications run inside a container with Orbeon branding) so add the following line to properties-local.xml <property as="xs:anyuri" name="oxf.epilogue.theme" value="oxf:/config/theme-ehr.xsl"/> 10. Now we just need to create our stylesheet for the ehr application by copying the file config/theme-plain.xsl to config/theme-ehr.xsl. This stylesheet strips out any formating, but we can start to add our own styling for the ehr application later on. 11. Now when you go to you should see the HTML file served from CATALINA_HOME/webapps/ehr/WEB-INF/resources/views/ehr.xhtml 2010 City University, London. Page 12 of 13

13 5. Starting and Stopping Tomcat As you tinker around with your OHI application you are likely to want to stop and start the Tomcat application server at various times. This is done by running scripts located in CATALINA_HOME/bin To start the Tomcat server startup.bat on WIndows systems startup.sh on Mac/Linux/Unix systems To stop the Tomcat server shutdown.bat on WIndows systems shutdown.sh on Mac/Linux/Unix systems Since you may need to do this quite often, its a good idea to set up shortcuts to run these scripts. On Windows you can create a shortcut to startup.bat and shutdown.bat and place them somewhere convenient on your desktop. (Navigate to CATALINA_HOME/bin in Windows Explorer, select startup.bat, right mouse click, select 'Create Shortcut', drag the shortcut onto your desktop). On the Mac its slightly more complicated since the shell scripts startup.sh and shutdown.sh need to run from inside a (unix) command shell (Mac OS is essentially a linux operating system). You can create executable applications to do this using the Automator tool which is located in your Applications folder. Run the Automator, create a new script to run the shell script with the startup.sh script and then save as an Application (which can then be dragged to your Dock for executing easily). Repeat in a similar way for the shutdown.sh script. See the screen shot below for a summary of how this is done City University, London. Page 13 of 13