D2.1 i2b2 Wizard
Transcription
D2.1 i2b2 Wizard
Integrated Data Repository Toolkit (IDRT) TMF-Projekt V091-MI_03 Deliverable 2.1: Bereitstellung integrierte Installation, Administration Sebastian Mate Jan Christoph Prof. Dr. Hans-Ulrich Prokosch Dr. Thomas Ganslandt Autoren Autor 1: Sebastian Mate Friedrich-Alexander-Universität Erlangen-Nürnberg Lehrstuhl für Medizinische Informatik Krankenhausstraße 12 91054 ERLANGEN Telefon +49 9131/85-26785 Fax +49 9131/85-26754 E-Mail: [email protected] Webseite: http://www.imi.med.uni-erlangen.de Autor 2: Jan Christoph Friedrich-Alexander-Universität Erlangen-Nürnberg Krankenhausstraße 12 91054 ERLANGEN Telefon +49 9131/85-26726 Fax +49 9131/85-26754 E-Mail: [email protected] Webseite: http://www.imi.med.uni-erlangen.de Autor 3: Prof. Dr. Hans-Ulrich Prokosch Friedrich-Alexander-Universität Erlangen-Nürnberg Lehrstuhl für Medizinische Informatik Krankenhausstraße 12 91054 ERLANGEN Telefon +49 9131/85-26701 Fax +49 9131/85-36799 E-Mail: [email protected] Webseite: http://www.imi.med.uni-erlangen.de sowie: Medizinisches Zentrum für Informations- und Kommunikationstechnik Krankenhausstraße 12 91054 ERLANGEN Autor 4: Dr. Thomas Ganslandt Medizinisches Zentrum für Informations- und Kommunikationstechnik Krankenhausstraße 12 91054 ERLANGEN Telefon +49 9131/85-26753 Fax +49 9131/85-26754 E-Mail: [email protected] Webseite: http://www.uk-erlangen.de Abschlussbericht Projektname, Projekt-Nr. XY, Monat Jahr 2 / 11 Inhaltsverzeichnis Autoren ......................................................................................................................... 2 Inhaltsverzeichnis ........................................................................................................... 3 Einleitung ...................................................................................................................... 4 Methode ........................................................................................................................ 5 Ergebnisse ..................................................................................................................... 6 Diskussion und Ausblick .................................................................................................. 9 Literatur ...................................................................................................................... 10 Anhänge ...................................................................................................................... 11 Abschlussbericht Projektname, Projekt-Nr. XY, Monat Jahr 3 / 11 Einleitung Im Jahr 2009 wurden im Rahmen des TMF-Projekts V054-01 „IT-Strategie“ [1, 2] international frei verfügbare IT-Lösungen hinsichtlich deren Verwendbarkeit für die deutsche Forschungslandschaft evaluiert (siehe: http://www.tmf-ev.de/Themen/Projekte/V054_01_ IT_Strategie.aspx). Die neben caBIG ebenso evaluierte Software i2b2 (Informatics for Integrating Biology and the Bedside) wurde für verschiedene Anwendungsszenarien als nützlich deklariert. Daraufhin hat sich neben dem Einsatz von i2b2 an diversen deutschen Universitäten eine deutsche i2b2-Community gebildet, die sich, vernetzt durch die TMF, bisher zu drei i2b2-Workshops zusammengefunden hat. Sowohl im Rahmen des IT-Strategie-Projekts, der Workshops und in der Literatur [3, 4] wurde jedoch immer wieder die komplizierte, zeitaufwändige und schwer reproduzierbare Installation bemängelt. Bereits im Rahmen des IT-Strategie-Projekts wurde damit begonnen, die Installation durch Skripte zu automatisieren. Diese Automatismen zeigten sich jedoch nicht für typische Anwendungen in der Praxis tauglich. Beispielsweise wurde bereits im ITStrategie-Projekt darauf hingewiesen, dass weitere Lösungen zur Administration von i2b2Servern (i2b2-Projektverwaltung, Ontologie-Verwaltung und –Erzeugung) geschaffen werden müssen. Im Rahmen einer studentischen Vorarbeit am Lehrstuhl für Medizinische Informatik der Friedrich-Alexander-Universität wurde das Skript aus dem IT-Strategie-Projekt im Jahre 2010 neu implementiert und stark erweitert. Fortan „i2b2-Wizard“ genannt, ermöglichte es neben der reinen i2b2-Installation auch die Administration. Da das vorliegende IDRT-Projekt den „Aufbau eines integrierten Werkzeugpakets auf Basis bewährter, etablierter Komponenten“ beabsichtigt, soll dieser i2b2-Wizard weiterentwickelt und neben i2b2 selbst als eine zentrale Kernkomponente in das IDRT-Softwarepaket eingebunden werden. Methode Innerhalb des Arbeitspakets „AP2.1 Bereitstellung integrierte Installation, Administration“ sollte ein integriertes Setup- und Administrationstool für das i2b2-System entwickelt werden. Aufgrund der bereits erfolgten Vorarbeiten in Erlangen sollte in AP2.1 keine neue Software geschaffen werden. Stattdessen sollte der existierende i2b2-Wizard entsprechend der Anforderungen des IDRT-Projekts verbessert und erweitert werden. Dies entspricht auch dem übergeordneten Ziel des IDRT-Projekts, in dem „basierend auf frei verfügbaren ITKomponenten […] eine nachhaltig nutzbare […] Plattform für die Zusammenführung und Abfrage heterogener Datenbestände […] geschaffen werden [soll].“ [IDRT Projektantrag]. Im Rahmen eines 3. deutschen i2b2-Workshops, der zum Kick-Off des IDRT-Projekt am 27.02.2012 in Berlin durch die TMF organisiert wurde, konnten weitere Anforderungen und Anwenderbedürfnisse an eine solche Plattform ermittelt werden (vgl. Deliverable D1.1). Bezüglich AP2.1 konnten in einem Hands-On-Tutorial gegen Ende des Workshops interessierte Teilnehmer eine i2b2-Instanz auf der Basis des i2b2-Wizards installieren und Verbesserungspotenziale am i2b2-Wizard aufgedeckt und diskutiert werden. Der i2b2-Wizard wird als Bash-Shellscript bereitgestellt. Zu Demonstrationszwecken wird er darüber hinaus zusammen mit den anderen IDRT-Komponenten als virtuelle Maschine zur Verfügung gestellt. Deliverable D1.1: Anforderungsanalyse, Integrated Data Repository Toolkit (IDRT), März 2012 5 / 11 Ergebnisse Im Rahmen dieser Arbeit wurde mit dem i2b2-Wizard ein Bash-Programm (siehe: https://www.gnu.org/software/bash/) weiterentwickelt, das den kompletten „Lebenszyklus“ einer i2b2-Instanz abdeckt. Dies betrifft sowohl die Vorbereitung der Linux-Installation, das Herunterladen von benötigter Software, die Installation, Pflege und Administration des i2b2Systems sowie eine automatische Fehlererkennung und – im beschränkten Rahmen – automatischen Fehlerkorrektur: Durch die ausgiebige Nutzung des Tools „dialog“ (siehe: http://hightek.org/dialog/) arbeitet die Software vollständig Menü-gesteuert. Diese Benutzeroberfläche ist jedoch vollständig textbasiert, wodurch sie sich insbesondere auch über SSH-Verbindungen einsetzen lässt. Die Software unterstützt die vollständige Installation eines i2b2-Servers: o Es wird erkannt, ob erforderliche Softwarepakete von Dritt-Herstellern fehlen (d. h. Software, die nicht im Repository der Linux-Distribution enthalten ist, z.B. Oracle XE). Falls erforderlich, werden diese automatisch von dem Skript heruntergeladen und entpackt. o Das Skript unterstützt darüber hinaus die automatische Überprüfung und, falls erforderlich, die Installation von benötigten Softwarepakten aus den Repositories der jeweiligen Linux-Distribution. Grundsätzlich wurde das Skript für Ubuntu 10.04 entwickelt; es ist jedoch leicht möglich, weitere DebianDistributionen zu unterstützen, insofern die Paket-Namen im Skript ergänzt werden. Durch die Kapselung der Repository-Softwareinstallation in eigenständige Funktionen kann das Skript auch für weitere Distributionen ergänzt werden. Exemplarisch wurde eine partielle Unterstützung für CentOS umgesetzt. o Das Skript hält in einem Verzeichnis eine vollständige i2b2-Serverkonfiguration (jedoch ohne die Oracle-Datenbankinhalte) vor, die bei der Verwendung des i2b2-Wizards ständig aktualisiert wird. Beim Deployen des i2b2-Quellcodes wird diese Konfiguration dazu verwendet, den i2b2-Quellcode vorab auf die aktuelle Serverkonfiguration zu aktualisieren. Dies ermöglicht es, die Konfiguration des Applikationsserver im Notfall binnen Sekunden wieder herzustellen. Wird auch der Inhalt der Oracle-Datenbank berücksichtigt, kann der i2b2Server auch recht einfach auf eine neue Hardware migriert werden, was jedoch etwas manuelle Arbeit erfordert. o Das Skript übernimmt auch sämtliche administrativen Arbeiten, die in Bezug mit der Oracle-Datenbank stehen. Hierzu gehört beispielweise das bedarfsweise Prüfen, Anlegen und Löschen von Datenbankschemata, die Erzeugung von Tabellen und deren Einträgen, usw. Die Software übernimmt auch administrative Aufgaben, die im Betrieb des i2b2Servers ständig anfallen: o Das Anlegen und Löschen von neuen i2b2-Projekten und i2b2-Benutzerkonten sowie die Registrierung von i2b2-Benutzern für i2b2-Projekte o Illustration, wie Daten ins i2b2 importiert werden können („i2b2-Wizard ETL“, diese Funktion ist jedoch nicht Gegenstand des ETL-Prozesses, der im IDRTProjekt entwickelt werden soll) o Das Laden oder Entfernen der „offiziellen“ Demodaten der i2b2-Entwickler o Diverse andere administrative Aufgaben wie zum Beispiel Unterstützung bei der Netzwerkkonfiguration (menübasierte Auswahl des erforderlichen Netzwerk-Interfaces), die Festlegung von Datenbankpasswörtern, der Hive-ID, usw. Deliverable D1.1: Anforderungsanalyse, Integrated Data Repository Toolkit (IDRT), März 2012 6 / 11 Bei der Auswahl einer Aufgabe über das Menü werden sämtliche erforderliche andere Aufgaben (Dependencies) durch das Skript automatisch rekursiv aufgelöst. Beispiel: wird das Skript zum allerersten Mal gestartet und sofort versucht, einen neuen Benutzer anzulegen, erkennt das Skript automatisch, dass es erst noch Software herunterladen und installieren muss. Nachdem der Anwender die Benutzerangaben eingegeben hat, erfolgen diese Arbeitsschritte durch das Skript automatisch im Hintergrund ohne weitere Benutzerinteraktion. Das Skript ist seit längerer Zeit für die Installation (jedoch noch nicht für die Administration) von SHRINE vorbereitet. In der hier vorliegenden Version wird SHRINE jedoch nicht unterstützt, da die aktuelle SHRINE-Version nicht mit i2b2 1.6 zusammenarbeitet. Sobald SHRINE von seinen Entwicklern aktualisiert wird, kann die SHRINEUnterstützung im i2b2-Wizard wieder aktiviert werden. Änderungen am i2b2-Wizard im Rahmen des IDRT-Projekts Im Rahmen dieser Arbeit konnten einige der Anforderungen der deutschen i2b2Community, welche im dritten deutschen i2b2-Workshop genannt wurden, umgesetzt wurden. Beispielsweise wurde mit dem Ziel der besseren Benutzerführung die MenüStruktur (Benutzer- und Projekte-Menü) und die Anzeige des JBoss/SHRINE-Status verbessert. Es hat sich gezeigt, dass die Auswahl einer „offiziellen“ Unterstützung von Ubuntu-Linux durch den i2b2-Wizard zwar von vielen Anwendern begrüßt wird, jedoch nicht immer im Einklang mit den IT-Richtlinien in den einzelnen Instituten steht. Beispielsweise sollen Server (wie der für i2b2) häufig virtualisiert werden und die Rechenzentren der Institute stellen hierfür ausgesuchte Linux-Distributionen (z. B. CentOS, SuSE-Linux) bereit, die dann auch automatisch durch das Rechenzentrum administriert werden. Im Rahmen des Wechsels von Version 1 auf 2 wurde der Quellcode des i2b2-Wizards fast vollständig refokturiert und das Programm modularisiert. Einzelne Module (Shell-Skripte) werden nun abhängig von der Systemkonfiguration beim Programmstart in das Hauptskript eingebunden. Dadurch wird eine Unterstützung für weitere Betriebssysteme und Linux-Distributionen möglich; ebenso können verschiedene i2b2-Versionen von ein und demselben i2b2-Wizard installiert und administriert werden. Da die Skripte grundsätzlich vor- und rückwärtskompatibel sind, kann beispielsweise nur der i2b2-Wizard aktualisiert werden, ohne jedoch die i2b2-Version zu ändern. So kann ein möglicherweise gut funktionierendes i2b2 beibehalten und trotzdem von den Verbesserungen der neuen i2b2-Wizard-Version profitiert werden. Des Weiteren wurden die Datenbankroutinen modularisiert und in diesem Zuge (experimentelle) Unterstützung für Microsoft SQL-Server integriert. Eine weitere Änderung ist die Möglichkeit, gewisse administrative i2b2Datenbankschemata (üblicherweise mit I2B2PM und I2B2HIVE bezeichnet) nach eigenen Wünschen zu bezeichnen. Weiterhin wurden Funktionen zur automatischen Fehlererkennung stark verbessert. So wird nun auch der JBoss-Start überwacht und im Falle eines Fehlers eine Fehlermeldung und dann das JBoss-Log angezeigt. Darüber hinaus wurde eine Erkennung der Verwendung falscher Passwörter eingebaut. So prüft der i2b2-Wizard nun zunächst, ob er eine Datenbankverbindung aufbauen kann, bevor er eine Datenbankoperation durchführt. Einen großen Anteil der Änderungen am i2b2-Wizard im Rahmen des IRDT-Projekts stellen jedoch viele kleine Fehlerkorrekturen und allgemeine Verbesserungen dar (z. B. hinsichtlich der zukünftigen Maintainance des Tools). Die folgende Abbildung visualisiert die ÄnDeliverable D1.1: Anforderungsanalyse, Integrated Data Repository Toolkit (IDRT), März 2012 7 / 11 derungen zwischen Version 1.3.6 (letzte Version ohne IDRT-Features) und Version 1.4.1 (erste Version mit IDRT-Features). Man beachte die geänderten Zeilen, die auf dem Balken rechts durch rot dargestellt ersichtlich sind. Deliverable D1.1: Anforderungsanalyse, Integrated Data Repository Toolkit (IDRT), März 2012 8 / 11 Diskussion und Ausblick Durch die Verwendung des i2b2-Wizards wird den Anwendern erheblich vereinfacht, eine i2b2-Instanz zu installieren und zu administrieren, da das Tool einen Großteil der dafür erforderlichen Konfigurationsschritte reproduzierbar in Programmcode abbildet und vor dem Anwender „versteckt“. Nachdem damit die – neben der Datenaufbereitung – größte Hürde am i2b2-System überwunden wird, ist zu erhoffen, dass das i2b2-System weiterhin an Popularität gewinnt, insbesondere im deutschsprachigen Anwenderraum. Für Anwender außerhalb Deutschlands ist sicherlich die Tatsache interessant, dass der i2b2Wizard zwar grundsätzlich in das IDRT-Softwarepaket integriert wurde, jedoch nicht an dieses gekoppelt ist. Es ist weiterhin möglich, den i2b2-Wizard auch ohne die sonstigen IDRTKomponenten zu benutzen. Für eine breitere Unterstützung anderer Linux-Distributionen neben dem „offiziell“ unterstützten Ubuntu-Linux ist jedoch auch die internationale i2b2-Community gefragt. Insbesondere Interesse für eine Unterstützung für SuSE-Linux und CentOS wurde bereits des Öfteren in der i2b2-Community bekundet. Es bleibt zu hoffen, dass das Tool auch in Zukunft weitergepflegt und –entwickelt werden kann – sei es durch Feedback aus der Community oder das Aufgreifen des Projekts durch die Community selbst. Durch die GPL2-Lizenz ist dies ohne weiteres möglich. Deliverable D1.1: Anforderungsanalyse, Integrated Data Repository Toolkit (IDRT), März 2012 9 / 11 Literatur 1. Prokosch HU (2009) Abschlussbericht TMF-Projekt V054-01 IT-Strategie 2. Mate S (2009) Evaluation von i2b2 am Universitätsklinikum Erlangen. Studienarbeit, Friedrich-Alexander-Universität Erlangen-Nürnberg 3. Deshmukh VG, Meystre SM, Mitchell JA (2009) Evaluating the Informatics for Integrating Biology and the Bedside System for Clinical Research. BMC Medical Research Methodology 9:70 4. Ganslandt T, Mate S, Helbing K, Sax U, Prokosch H (2011) Unlocking Data for Clinical Research - The German i2b2 Experience. Applied Clinical Informatics 2(1):116-127 Deliverable D1.1: Anforderungsanalyse, Integrated Data Repository Toolkit (IDRT), März 2012 10 / 11 Anhänge i2b2-Wizard Anleitung Präsentation mit „Installations Walk-Through“ Deliverable D1.1: Anforderungsanalyse, Integrated Data Repository Toolkit (IDRT), März 2012 11 / 11 i2b2 Wizard Chair of Medical Informatics, University of Erlangen-Nuremberg, Germany and the IDRT team Contact: [email protected] May 16, 2012 Contents 1 Introduction 2 2 Copyright and Licensing 3 3 How to start 3 4 VirtualBox VM Setup 4 5 Linux Installation 5 5.1 Ubuntu Linux 10.04.x Desktop Edition . . . . . . . . . . . . . . . . . . . . 5 5.2 Ubuntu Linux 10.04.x Server Edition Some Hints . . . . . . . . . . . . . 7 6 i2b2 Wizard Installation 7 7 How i2b2 Wizard works important things you need to know 9 8 i2b2 Wizard Quick-Start 10 9 All i2b2 Wizard Functions 12 9.1 Setting The Default Parameters . . . . . . . . . . . . . . . . . . . . . . . . 12 9.2 Automatic Software Download 13 9.3 Automatic Software Installation . . . . . . . . . . . . . . . . . . . . . . . . 14 9.4 Updating the server IP address . . . . . . . . . . . . . . . . . . . . . . . . 14 9.5 Loading or Dropping I2B2HIVE and I2B2PM . . . . . . . . . . . . . . . . 16 9.6 Creating a new i2b2 Project . . . . . . . . . . . . . . . . . . . . . . . . . . 16 9.7 Removing an i2b2 Project . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 9.8 Creating an i2b2 User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 9.9 Removing an i2b2 User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 9.10 Assigning an User to a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 9.11 Loading and Removing the Boston Demodata . . . . . . . . . . . . . . . . 18 9.12 Building the i2b2 Source Code . . . . . . . . . . . . . . . . . . . . . . . . 19 9.13 Controlling the JBoss Process . . . . . . . . . . . . . . . . . . . . . . . . . 19 9.14 Creating a Separate JBoss Linux User . . . . . . . . . . . . . . . . . . . . 20 9.15 Running ETL-Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 10 Using the i2b2 Wizard ETL Approach 21 1 Introduction The Wizard for Simplied i2b2 Administration or i2b2 Wizard is a bash-based program to manage your i2b2 instance. Instead of working with the i2b2 source code, you can use a semi-graphical menu system to install i2b2, create i2b2 projects, create users and much more. Special Features: • Semi-graphical program to install and congure i2b2 • Full i2b2 installation support Automatic download and extraction of required software packages Automatic installation of Linux software packages Automatic conguration and compilation of the i2b2 source code Automatic handling of all database stu (schema creation, etc.) • Full support for i2b2 administration Create and remove i2b2 projects and users Load and remove the Boston Demodata Change Hive ID and network interface and database conguration Change various passwords (e. g. from I2B2HIVE and I2B2PM) • Recursive resolving of dependencies for setup targets / administration tasks 2 • Preparation of special template ETL SQL scripts which can be used to load data into the i2b2 Hive, the ETL process can also be triggered directly in i2b2 Wizard (please note that is is not part of the IDRT functionality). • SHRINE Installation (does not cover SHRINE conguration) 2 Copyright and Licensing Copyright (C) 2010-2012 Chair of Medical Informatics, Friedrich-Alexander-University of Erlangen-Nuremberg, Germany Portions by 'Integrated Data Repository Toolkit' project (IDRT) Copyright (C) 2012 Technologie- und Methodenplattform fuer die vernetzte medizinische Forschung e.V. (TMF) This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 3 How to start Don't worry: This document appears longish because it describes many things and conguration steps in detail. The use of i2b2 Wizard, however, is easy and straigtforward. If you're alredy experienced in using Linux and if you keep some important properties of i2b2 Wizard in mind, you will be able to install future i2b2 hives in about 60 minutes including the Linux system! Section 4 describes how you can create the VirtualBox virtual machine with Ubunu Linux. It is important to use 1 GB of RAM, a hard disk with at least 16 GB of space and 3 an additional Host-only Adapter network interface if you are using VirtualBox. That's it! Section 5 describes in detail how you can set up the Linux. Currently, only Ubuntu Linux 10.04.x (32 bit desktop or server edition) is ocially supported. Also make sure that you provide more than 1 GB swap space and use English as your system's language. That's all! Section 6 describes how you can use SFTP to copy the i2b2 Wizard installation les and i2b2 source packages onto your virtual machine and how you launch wizard.sh. Very easy! Section 7 explains how i2b2 Wizard works from very top-level view and outlines some very important aspects, for example the one-way communication with the database. Section 8 contains a walk-though and explains the most important functions of i2b2 Wizard. Section 9 explains all functions of i2b2 Wizard in detail. You should read this if you plan to load more than just the provided Demodata ... 4 VirtualBox VM Setup In order to use the i2b2 Wizard, you need either a physical computer or a virtual machine, both running Ubuntu Linux 10.04. In this guide, we use Sun VirtualBox because it is free and works on a variety of operating systems. In addition, a virtual machine has many advantages compared to a physical computer, such as storing the current machine state and reverting to it. 1. Get yourself a copy of VirtualBox from http://www.virtualbox.org and install it. In this guide version 3.1.6 is used (on a Macintosh). 2. Get a copy of Ubuntu Linux 10.04.x from http://www.ubuntu.com. To be more specic: you need the le ubuntu-10.04-desktop-i386.iso. The server edition works too, but is more dicult to install below are some hints regarding this version. The i2b2 Wizard will probably not work with other Linux editions! 3. Launch VirtualBox and choose New . In the new window press Next . Choose a name for your i2b2 instance, for example and Ubuntu . Press Next . 4 i2b2 Server . Below, choose Linux 4. On the next screen, choose 1024 MB of memory. Press 5. Choose choose Next . Create new hard disk , Next . In the new window press Next , Dynamically expanding storage , Next . Choose 16 GB (8 GB is not enough), Next , Finish and Finish . The new virtual machine will be listed in the VirtualBox main window. 6. On the right side of the window in the Details tab you will nd the entry Network (printed in blue color) with one entry: Adapter 1: PCnet-FAST III (NAT) . Click on this blue Network entry. In the new window select the tab Adapter 2 , check Enable Network Adapter and select Attached to: Host-only Adapter . Press OK . The main window should now list Adapter 1 and Adapter 2 below Net- work . 7. Now add the Ubuntu ISO-le. Select the blue Storage entry in the VirtualBox main window. On the left side of the new window in the the CD-icon labeled Storage Tree select Empty . On the right side, click on the yellow/green folder icon. A new window will pop up. Click on Add and choose the ubuntu-10.04- desktop-i386.iso which you have previously downloaded. The entry IDE Secondary Master (CD/DVD): ubuntu-10.04-desktop- i386.iso (699.44 MB) should now be listed in the VirtualBox main window under Storage . 5 Linux Installation 5.1 Ubuntu Linux 10.04.x Desktop Edition 1. Start your new (virtual) machine and wait until the graphical installation manager comes up. Select English on the left side (other languages will probably fail, because this choice aects how the Oracle database is initialized (date format, etc.) and how various Linux tools print messages). Then select 10.04.x LTS . 5 Install Ubuntu Figure 1: Hard disk partitioning with > 1 GB swap space. 2. Choose your keyboard layout. It is OK to choose one dierent to English. Press Forward . 3. The next step is to partition the hard disk manually to get more than 1 GB swap space. Select Select Specify partitions manually (advanced) and press Forward . New Partition Table... and Continue . Select the free space entry in the table above and click on the in Add... button. In the new window enter New partition size in megabytes: the value 1101 and select Use as: swap area . Click OK . A new swap partition with 1101 MB should show up. Again, select the free space entry in the table and click on the Add... button. In the new window enter in Mount point: the value / . Click OK . A new ext4 partition with 15 GB should show up. If the whole partitioning looks like in Figure 1 on page 6 , press 4. In the Forward . Who are you? screen ll in your desired information. Click Next . This will install Ubuntu Linux on your (virtual) machine. press After the installation Restart Now . After the shut-down, hit enter to eject the disc. 6 5. It is a good idea to install the VirtualBox Guest Additions and to assign a static IP address to the VirtualBox Host-Only-Adapter if you have more than one virtual machine in VirtualBox. The Host-Only-Adapter is the interface with the 192.168.56.***-IP. Also install all system updates if the the update-manager pops up. 5.2 Ubuntu Linux 10.04.x Server Edition Some Hints • Partitioning: create two primary partitions: create a 1.1 GB swap partition, and use the rest as Ext4 partition with mount point /. Set the second one to bootable . • Network setup: Modify /etc/network/interfaces. You should have two net- work interfaces (eth0 and eth1 where one is the NAT interface and the other one the vboxnet0 interface), but only one has been congured by the Ubuntu installer. Assuming eth1 is the vboxnet0 interface, the le should contain these contents: ... auto eth0 auto eth1 iface eth0 inet dhcp iface eth1 inet static address 192.168.56.101 netmask 255.255.255.0 Replace 192.168.56.101 with your desired (static) IP address. After the modication, run ifup eth1 to get the interface working. • Adding a repository for Sun Java: Add the following line to /etc/apt/- sources.list: deb http://archive.canonical.com/ubuntu lucid partner After this run apt-get update. 6 i2b2 Wizard Installation All you need to do is to copy the required les to the Ubuntu machine and launch the script wizard.sh. 7 1. Download the required i2b2 les from http://www.i2b2.org. The i2b2 Wizard automatically downloads all required les, however, those from http://www.i2b2.org cannot be downloaded automatically. You need the following les: • i2b2core-src-XXX.zip (i2b2 Hive source code) • i2b2createdb-XXX.zip (Boston Demodata) • i2b2webclient-XXX.zip (i2b2 webclient source code) Here, XXX is a placeholder for the current version. Please note that each version of i2b2 Wizard is designed for a specic i2b2 version. To nd out which i2b2 version you need, open wizard.sh in a text editor and look at the rst few lines. Put these les into the packages folder from the i2b2 Wizard installation directory. If you haven't downloaded the les (because you are unable to do so), i2b2 Wizard will ask you to provide a server path in a later step. If this URL contains the valid i2b2 source code repository, i2b2 Wizard can download all les automatically. If you experience diculties in downloading the i2b2 source code les from the i2b2 website, please contact the developer of i2b2 Wizard. 2. Start your new Ubuntu Linux and log in. source which is required for Sun Java. Select You need to an additional package System => Administration => Software Sources , click on the Other Software . Check ... lucid partner and click on Close , then Reload . 3. Open a Terminal (Applications => Accessories => Terminal ) and type in the following commands: sudo -s (and provide your password) passwd root (assign a password for user 'root') apt-get update apt-get upgrade apt-get install openssh-server This installs the OpenSSH server which allows you to copy the i2b2 Wizard installation les to the Ubuntu machine. 4. Copy all les with SFTP to the Ubuntu machine. On Windows, you can use WinSCP (http://winscp.net), on a Mac the program Cyberduck (http://www.cyberduck.ch) or the excellent MacFusion (http://www.macfusionapp.org, a x for OS X 10.6.3 exists here: http://github.com/downloads/nall/MacFusion2/Macfusion-2.0.4-SL.zip). 8 To connect to your virtual machine, use the Host-Only-Adapter. The Host-OnlyAdapter is the interface with the 192.168.56.***-IP. You can use the command ifcong to nd out the IP. 5. It is highly recommended to create a snapshot of your VirtualBox virtual machine before running the i2b2 Wizard. 7 How i2b2 Wizard works important things you need to know /i2b2wizard-1.x.x/ /i2b2src/ Configured*i2b2*source*code* config/ Project*and*user*configura5on* i2b2%Wizard$ i2b2$ wizard.sh /opt/jboss-4.2.2.GA/ Warning:' one:way!' Create'users' and'i2b2'projects' JBoss*applica5on*server*with*i2b2* webservices* Oracle'DB' Project*and*user*config* i2b2*project*data* Manage'users'and' projects' /var/www/admin official*i2*admin*interface*(h@p:// localhost/admin)* Figure 2: i2b2 Wizard's interaction with the i2b2 and Linux system. Figure 2 on page 9 illustrates how i2b2 Wizard interacts with i2b2 and the overall Linux system. The large white rectangle in the upper left part shows the i2b2 Wizard directory, which contains wizard.sh (the i2b2 Wizard bash program) and, besides others, a cong directory. This cong directory stores the current conguration of your i2b2 hive, i.e. information about all created i2b2 projects, users, passwords, ... everything that can be congured through i2b2 Wizard's menu system. 9 This conguration is used to congure the i2b2 hive source code during deployment (the source code is automatically extracted to /i2b2scr/, then cogured and deployed to /opt/jboss-4.2.2.GA/ by i2b2 Wizard during setup, see gure 2, right part). It is OK to delete /i2b2scr/ and /opt/jboss-4.2.2.GA/ if something gets messed up, because i2b2 Wizard will automatically rebuild these directories whenever necessary. i2b2 Wizard also writes conguration information to the Oracle database (see bottom left part of gure 2). However, it is important to keep in mind is that this a one-way communication only. This means that i2b2 Wizard only writes to the database but never reads it (future versions of i2b2 Wizard might be able to do this). Because these writes happen as soon as they are necessary (e.g. if a new i2b2 project is being set up and therefore a new Oracle database schema has to be created) but are not stored anywhere, it is not possible to rebuild the database from the cong directory afterwards. Therefore it is possible to migrate an i2b2 server to a new physical machine easily just by copying the i2b2 Wizard directory along with the whole Oracle database. Another important implication from the one-way database communication is that it is not possible to convert an existing i2b2 server into an i2b2 Wizard i2b2 server you'll always have to start from scratch (or rebuild the i2b2 Wizard cong directory to match your existing conguration, which is dicult and out of the scope of this manual). 8 i2b2 Wizard Quick-Start Launch the i2b2 Wizard by executing sh wizard.sh as root. If everything is OK, you will be greeted by the i2b2 Wizard after a few seconds (it will probably install the required tool dialog rst), see Figure 3 on page 11: 1. To download and to install the required server software, select System Setup => Install Software . This will take a considerable amount of time depending on your internet connection speed. Please note that this installs Oracle XE. The license is accepted automatically by i2b2 Wizard. 2. Go to the Menu Hive Tasks and select Load I2B2PM and I2B2HIVE . A window will pop up and ask you which network interface is used to communicate with the i2b2 Workbenches, see Figure 5 on page 15. Select the interface with the 192.168.56.***-IP by pressing the space bar. This is the Host-Only-Adapter if you are using VirtualBox. 3. To create an i2b2 project, go to Projects & Users and select Create i2b2 Project . Enter your desired parameters as shown in gure 7 on page 17. 10 Figure 3: The i2b2 Wizard Main Menu. Note that this has also created a new ETL-job, which can be started with Run ETL from the main menu. The corresponding SQL is ETL/scripts/GyrosResearch.sql. Use this le to load real data into your i2b2 project. 4. Now you need to create an i2b2 user. From the main menu, select Projects & Users' => Create i2b2 User . Enter your desired parameters as shown in gure 8 on page 18. This creates an i2b2 user. Please note that the default password is demouser. The password can later be changed in the admin console (http://localhost/admin). To open the webclient, open http://localhost/webclient on your i2b2 Hive. 5. The next step is to assign the user to the project. From the main menu, select Projects & Users'=> Assign User as shown in gure 9 on page 19. For all the roles and permissions please refer to the ocial i2b2 documentation. 6. Deploy the changes and launch JBoss by selecting JBoss from the main menu. 11 JBoss Control => Start 7. You can now log into your new project. However, you need to congure your i2b2 Workbench to match your conguration rst. Modify your i2b2workbench.properties which is located in the i2b2 Workbench directory: writeTimelineFile=yes applicationName=i2b2 messageversion=1.1 demoUser=no I2b2.1=HarvardDemo,REST,http://webservices.i2b2.org/i2b2/rest/PMService/ I2b2.2=i2b2demo,REST,http://192.168.56.101:9090/i2b2/rest/PMService/ Make sure that the Hive-ID is set to i2b2demo and that the IP is correct. You can then connect to your i2b2 Hive. 8. If you want to load the Boston Demodata as well, select Boston Demodata => Load Boston Demodata from the main menu. This creates the project as well as the two i2b2 users i2b2 and demo. Their password is demouser. Please note that loading the Demodata will take very long: about 30 minutes. It is OK if error messages appear after the import (because there are/were errors in the Demodata SQL les). 9. To access the i2b2 Webclient, open http://localhost/webclient (replace localhost with the IP if you want to access it from a dierent machine). 10. To access the i2b2 admin console, open http://localhost/admin (again, replace localhost with the correct IP). 9 All i2b2 Wizard Functions This chapter describes the i2b2 Wizard functions in detail. 9.1 Setting The Default Parameters The i2b2 Wizard allows you to comfortably manage many settings from within the program. To change/update the settings, select System Setup => Set Defaults from the main menu, see gure 4 on page 13. 12 Figure 4: Setting the default parameters. The rst part describes the database connection. Currently only Oracle is supported. If you create new projects, this is are the settings which will be used. Please note that this setting should not be changed after i2b2 projects and users have been created. You can also specify a new Hive ID any time. If you change it, you will have to re-run the task System Setup => Hive Tasks => Update Hive-ID from the main menu. Don't forget to update the conguration in i2b2workbench.properties les as well as the Webclient /var/www/webclient/i2b2_cong_data.js ! If you have already created a separate Linux user for the JBoss process, you can set Use separate JBoss-user to yes and provide the correct login. Please refer to chapter 9.14 on page 20 for details. 9.2 Automatic Software Download Normally the required software packages are downloaded automatically when they are needed. You can trigger this function manually by selecting load Software from the main menu. 13 System Setup => Down- The default database-settings (see chapter 9.1 on page 12) inuence the download of the Oracle XE package: if the IP is set to localhost , it will be downloaded, otherwise not. 9.3 Automatic Software Installation Normally the required software packages are installed automatically when they are needed. You can trigger this function manually by selecting System Setup => Install Soft- ware from the main menu. The default database-settings (see chapter 9.1 on page 12) inuence the installation of the Oracle XE package: if the IP is set to localhost , it will be installed, otherwise not. Note that the licenses for Sun Java 6 and Oracle XE are automatically accepted by the i2b2 Wizard. 9.4 Updating the server IP address In order to allow the i2b2 Workbenches to communicate with the i2b2 webservices, the IP addresse must be written to the table PM_CELL_DATA in I2B2PM. This can be done automatically by selecting System Setup => Hive Tasks => Update Hive-IP from the main menu. Figure 5 on page 15 shows the following screen with the network interface selection. Figure 6 on page 15 explains the background of the networking conguration. In a default VirtualBox Linux installation, there are two network interfaces: the loop-only interface that is used internally by the Linux system and the NAT interface that connects to the internet. However, in order to allow the i2b2 Workbench and Webclient (which is, in fact, running on the physical host computer, not on the server) to connect to the i2b2 server, a host-only network interface has to be created. Therefore, if you are using VirtualBox, select the interface with the 192.168.56.***-IP by pressing the space bar. This is the Host-Only-Adapter. An alternative is to select the loop-only interface (127.0.0.1). In this case, however, the server can only be accessed from within the server itself. This means that you have to run the Workbench inside the VM or open the webclient with a browser running inside the VM. 14 Figure 5: Network Setup. VM#Host( i2b2#Server((VM#Guest)( Workbench( Webclient( 192.168.56.101( Host#Only( Webclient( i2b2# Server( 127.0.0.1( Loop#Only( Your(physical( computer( 10.0.2.15( NAT( Your(VirtualBox( Figure 6: Summary of network interfaces. 15 Internet( 9.5 Loading or Dropping I2B2HIVE and I2B2PM In the Menu System Setup => Hive Tasks two menu items can be found for loading or dropping the schemata I2B2PM and I2B2HIVE: • Load I2B2PM and I2B2HIVE • Drop I2B2PM and I2B2HIVE The rst item loads the schemata, the second one removes them. I2B2PM and I2B2HIVE contain basic administrative data and are required for an i2b2 installation. Note that you should never remove I2B2PM and I2B2HIVE once i2b2 projects and/or users have been created. If you remove I2B2PM and I2B2HIVE, all project and user settings inside the Oracle database are lost and cannot be rebuilt automatically, even from the project and users conguration from i2b2 Wizard, which is in fact kept. Please refer to section 7, which explains this in more detail. The removal of the two schemata is only applicable if you want to x a new i2b2 hive that is not properly working, which should never happen ... 9.6 Creating a new i2b2 Project To create a new i2b2 project, choose Projects & Users => Create i2b2 Project from the main menu. The dialog asks you for a project name and a database password. Do not use any special/foreign characters! This will use the database settings and create a new database schema. The schema's name is composed by removing all spaces from the project name, switching all letters to upper case and adding the prex I2B2. In this case this would result in I2B2PROSTATECANCERDATA. Please note that i2b2 Wizard handles the creation of database schemas in a dierent manner: the tables for the dierent webservices (ONT, WORK, CRC) are all loaded into one schema. Furthermore, a new ETL-job is created. 16 Figure 7: Creating a new i2b2 project. 9.7 Removing an i2b2 Project To remove an i2b2 project, select from the main menu. Projects & Users => Remove i2b2 Project This removes the database schema and all assignments of i2b2 users to this project. 9.8 Creating an i2b2 User To create a new i2b2 user, select Projects & Users => Create i2b2 User from the main menu. This creates an i2b2 user. Please note that the default password is demouser. password can only be changed in the Webclient. To open the webclient, open http://localhost/webclient on your i2b2 Hive. 17 The Figure 8: Creating a new i2b2 user. 9.9 Removing an i2b2 User To remove an i2b2 user, select Projects & Users => Remove i2b2 User from the main menu. This removes all assignments of this to all projects as well. 9.10 Assigning an User to a Project To assign an i2b2 user to a project, select either Projects & Users => Assign User from the main menu. For all the roles and permissions please refer to the ocial i2b2 documentation. 9.11 Loading and Removing the Boston Demodata To load or drop the Boston Demodata use the two functions provided in the Boston Demodata menu. Loading the data creates the project Demo and the two new i2b2 users i2b2 and demo (both having demouser as password). If you want to use the 18 Figure 9: Assigning an i2b2 user to an i2b2 project. Demodata with a dierent i2b2 User, you must assign this user with Projects & Users => Assign User from the main menu. 9.12 Building the i2b2 Source Code The function Build i2b2 from the main menu automatically compiles and deploys the i2b2 webservices. 9.13 Controlling the JBoss Process The JBoss server can be controlled with the functions in the JBoss Control menu. The description on the right side tells you which Linux user is used to run JBoss. To change the user, please refer to chapter 9.14. 19 9.14 Creating a Separate JBoss Linux User By default, the Linux user root is used to run the JBoss server. This is a bad thing and should be avoided. The i2b2 Wizard provides a special function to create a new Linux user which can then be used to run the JBoss process. From the main menu, select System Setup => Create JBoss User . Provide a login name and password to create the user. This automatically switches the setting Use separate JBoss-user to yes in the Congure Defaults Parameters window. 9.15 Running ETL-Scripts Figure 10: Executing the i2b2 Wizard ETL scripts. For every project that is created by i2b2 Wizard, a new ETL-script is created in the ETL/scripts/ directory. You can invoke the scripts by selecting Run ETL from the main menu, see gure 10 on page 20. The entries can be checked and unchecked by pressing the space key. You can use these scripts as templates to load real data into your i2b2 Hive, see next chapter. 20 !"!# $% !!# Figure 11: An exemplary ctitious HIS-sheet. 10 Using the i2b2 Wizard ETL Approach The i2b2 Wizard includes a very simple approach which can be used to load heterogeneous data from a Hospital Information System (HIS) into the i2b2 Hive. For every i2b2 project that is created by i2b2 Wizard, the program creates a ETL SQL-le in the ETL subdirectory. The SQL-le can be executed either by i2b2 Wizard or SQL-Developer. The SQL le contains a few statements to insert a few sample entries into the i2b2 database. Furthermore, it accesses three special staging tables to import data: STG_PATIENTS, STG_OBSERVATIONS and STG_ONTOLOGY. The rst table is used to map patient numbers to case numbers and holds patient demographics. The second table contains the clinical facts data stored in an EAV-format, a format which is often used by clinical systems to store data. The STG_ONTOLOGY table contains a hierarchical description of the attribute collection. It is transformed into the i2b2 Ontology format by the SQL script. Let's assume you have a sheet-based system for clinical data entry and you want to map the data into your i2b2 project. An example sheet is given in gure 11 on page 21. The sheet has the following administrative elements: • a case number for the patient and • a date-eld when the whole sheet was lled in. Furthermore, there are ve attributes: 21 CaseNum RecDate SysAbbr Value 999001 01/01/2010 A_SEV 1 999001 01/01/2010 A_SUCC Yes 999001 01/01/2010 A_DBL Yes 999001 01/01/2010 A_STRT 04/05/2009 999001 01/01/2010 A_END 12/11/2009 Table 1: STG_OBSERVATIONS • Severity with the possible values 1, 2 and 3, • Success with the possible values Yes and No, • Double dose which can be either true or false (= Yes or No), • Start of therapy which can contain an arbitrary date as value and • End of therapy which can contain any date as well. If you export the data from your hospital information system, it might look similar to table 1. This is a typical EAV (Entity-Attribute-Value) table. It exactly represents the data from the above sheet. The column SysAbbr (System Abbreviation) hold an acronym for the attribute's name. For example, A_SEV is used for Severity in our ctitious HIS. The STG_OBSERVATIONS table from i2b2 Wizard is constructed in this way. If you edit your exported HIS data to look like this, you can use Excel and SQL-Developer and upload it into the STG_OBSERVATIONS table. However, i2b2 requires more data. Additional information is required to build the PATIENT_DIMENSION table in i2b2. For this reason (and to map the case number to a patient number - this is very common in Germany because of the accounting system used there) there is a STG_PATIENTS table which looks like table 2. STG_PATIENTS contains our patient from the above sheet screenshot (the rst row) and ve others. The table provides the additional attributes Sex and Age. In order to build a working i2b2 Ontology, you must provide a hierarchy which is used to rank the attribute collection from the STG_OBSERVATIONS table as seen in table 3. Notice how Level1 to Level3 and Value are used to create a folder hierarchy. The 22 PatNum CaseNum Gender Age 10001 999001 F 17 10002 999002 M 20 10003 999003 F 23 10004 999004 M 26 10005 999005 F 29 10006 999006 M 32 Table 2: STG_PATIENTS Level1 Level2 Level3 Value SysAbbr CCode DataType HIS Sp. Treat. Severity 1 A_SEV SEV_A:1 S HIS Sp. Treat. Severity 2 A_SEV SEV_A:2 S HIS Sp. Treat. Severity 3 A_SEV SEV_A:3 S HIS Sp. Treat. Success Yes A_SUCC SUCC_A:YES S HIS Sp. Treat. Success No A_SUCC SUCC_A:NO S HIS Sp. Treat. Double Dose Yes A_DBL DBL_A:YES S HIS Sp. Treat. Double Dose No A_DBL DBL_A:NO S HIS Sp. Treat. Start of Therpy A_STRT THER_A:ST D HIS Sp. Treat. End of Therpy A_END THER_A:END D Table 3: STG_ONTOLOGY 23 Figure 12: The ontology which is derived from the table STG_ONTOLOGY. resulting i2b2 Ontology is shown in gure 12 on page 24. Note that some entries in the tables above have been abbreviated in order to save space; for example: Sp. Treat. is Special Treatment and the prex ATTRB_ from the original tables has been dropped, too. Please note that the provided STG_ONTOLOGY contains an additional Experimental Therapy folder which is not shown in the above table. Also realize how the date-elds are treated dierently. Instead of using 01/01/2010 as START_DATE in OBSERVATION_FACT, the dates 04/05/2009 and 12/11/2009 are used, respectively. Currently only the two data formats S (String) and D (Date) are used in the sample ETL SQL-le. The system is currently not capable of handling oating-point numbers such as laboratory values. Maybe we will add this in future versions ... 24 31.05.2013 Dritter TMF‐i2b2‐Workshop am 27.02.2012 in Berlin i2b2‐Hands‐On‐Tutorial Installation von i2b2 mit dem i2b2‐Wizard Sebastian Mate, Thomas Ganslandt, Hans‐Ulrich Prokosch (und viele andere) Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Willkommen beim Hands‐On‐Tutorial! In dieser Session werden die Teilnehmer einen i2b2‐Server auf Basis des i2b2‐ Wizards installieren. 2 1 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Overview & Motivation Die vom i2b2‐NCBC bereitgestellten Materialien machen einen Start leider nicht gerade einfach: Kompilierte Workbench, der sich mit einem Demo‐Server in Harvard verbindet i2b2 VMware‐Images (CentOS‐Linux, etwa 2GB Download) i2b2‐Quellcode (Java Hive & Workbench, Javascript‐Webclient) Ausführliche Dokumentation (ca. 500 Seiten) Wie angehen, damit die Arbeit nachhaltig bleibt? Die Geschichte aus Erlangen. 3 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Overview & Motivation The first steps were very time consuming: 4 2 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Overview & Motivation Oracleconfiguration PMconfiguration 5 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Overview & Motivation Die vom i2b2‐NCBC bereitgestellten Materialien machen einen Start leider nicht gerade einfach: Kompilierte Workbench, der sich mit einem Demo‐Server in Harvard verbindet i2b2 VMware‐Images (CentOS‐Linux, etwa 2GB Download) i2b2‐Quellcode (Java Hive & Workbench, Javascript‐Webclient) Ausführliche Dokumentation (ca. 500 Seiten) Installation ist sehr zeitaufwändig. Schwierig für Evaluationszwecke. Bedürfnis: Schnelles, reproduzierbares Setup 6 3 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Overview & Motivation Status: January 2009 install_pm.sh PM‐ configuration install_crc.sh install_data.sh install_fr.sh Oracle‐ configuration download.sh install_work.sh install_oracle.sh install_ontology.sh 7 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Overview & Motivation Status: June 2009 install.sh Performs all important tasks: Install server software, build and deploy i2b2 and PSX, configure hive, create ontologies and load clinical data, … Installation on any PC or at the Erlangen Hospital! 8 4 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Overview & Motivation Future goal additional tools: managing the setup “in production” install.sh generic install: server software and i2b2 only Project Setup Ontology Tool 9 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg i2b2‐Wizard: Features “Semi‐graphical” program to install and configure i2b2 Full i2b2 installation support Automatic download and extraction of required software packages Automatic installation of Linux software packages Automatic configuration and compilation of the i2b2 source code Automatic handling of all database stuff (schema creation, etc.) Full support for i2b2 administration Create and remove i2b2 projects and users Load and remove the Boston Demodata Change Hive ID and network interface and database configuration Change various passwords (e. g. from I2B2HIVE and I2B2PM) Recursive resolving of dependencies for setup targets / administration tasks SHRINE Installation (not working with i2b2 1.6) 10 5 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg The Setup – Three Small Steps 1. Install Ubuntu 10.04 with 1.1 GB swap space 2. Configure SSH and copy the setup files to the machine – or download i2b2 Wizard directly on the VM 3. Run wizard.sh 11 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Setup Walk‐Through Erstellung der Linux‐VM für i2b2 Vor dem Workshop wurde eine Linux‐VM bereitgestellt. Die folgenden Folien zeigen die Schritte, die für die Erstellung dieser VM erforderlich waren. 12 6 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Setup Walk‐Through Anlegen der Ubuntu‐Linux‐VM unter VirtualBox: 13 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Die VM sollte mindestens 1GB RAM haben. 14 7 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Die Festplatte sollte mindestens 16 GB Speicherplatz bieten. 15 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg In den Netzwerkeinstellungen muss ein „Host‐Only Ethernet Adapter“ hinzugefügt werden. 16 8 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Netzwerk‐Konfiguration Was soll das mit den vielen Netzwerk‐Interfaces?! VM‐Host i2b2‐Server (VM‐Guest) Workbench Webclient 192.168.56.101 Host‐Only 10.0.2.15 NAT Internet Webclient i2b2‐ Server 127.0.0.1 Loop‐Only Ihr Laptop Ihre VirtualBox 17 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Setup Walk‐Through Installation von Linux Die folgenden Folien zeigen, wie man das Ubuntu‐Linux in der neu angelegten VM installiert. Schritte, bei denen keine Konfiguration erforderlich ist, werden nicht gezeigt. 18 9 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Es muss Englisch als Systemsprache eingestellt werden! 19 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Das Keyboard‐Layout darf aber wieder deutsch sein … 20 10 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Das manuelle Partitionieren ist der komplizierteste Teil … 21 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg 22 11 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg 23 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Mindestens 1 GB SWAP space 24 12 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg 25 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Der Rest wird für / verwendet. 26 13 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg 27 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg „i2b2“. Für den Workshop ist das sicher genug. 28 14 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg 29 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Setup Walk‐Through Nach dem Start von Linux Die folgenden Folien zeigen, was nach der Linux‐Installation zu erledigen ist. 30 15 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg eth0 aktivieren Falls möglich, die beiden Netzwerkverbindungen aktivieren: eth1 aktivieren 31 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Das frische Linux updaten! 32 16 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg 33 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg 34 17 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Root‐Passwort setzen (i2b2) i2b2‐Wizard herunterladen 35 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg und entpacken … 36 18 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Hier beginnt der Workshop … Starten … 37 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg 38 19 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg 39 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Einfach /.1.6.02 anfügen und der i2b2‐Wizard lädt alles selbst herunter. 40 20 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Workshop: Falls jemand offline ist und deswegen die Dateien nicht herunterladen kann, „No“ auswählen und … 41 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg … die Dateien manuell an den richtigen Ort kopieren. 42 21 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg 8080 1521 i2b2 i2b2 y 43 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg 44 22 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Netzwerk‐Konfiguration Was soll das mit den vielen Netzwerk‐Interfaces?! VM‐Host i2b2‐Server (VM‐Guest) Workbench Webclient 192.168.56.101 Host‐Only 10.0.2.15 NAT Internet Webclient i2b2‐ Server 127.0.0.1 Loop‐Only Ihr Laptop Ihre VirtualBox 45 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Nun den JBoss‐ Applikationsserver starten … 46 23 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Hoppla! Die Konfiguration hat sich geändert. i2b2‐Wizard erledigt aber alles automatisch … 47 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg demouser Nun wird es spannend … 48 24 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Funktioniert! 49 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Hier bitte keine Sonderzeichen verwenden! 50 25 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Neuen Benutzer anlegen: „Main Menu >> User Management“ 51 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg 52 26 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Den neuen Benutzer dem neuen Projekt zuweisen 53 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Nun den JBoss‐ Applikationsserver starten … 54 27 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Nach dem Login mit dem neuen Benutzer findet man das i2b2‐Wizard „Minimal‐ Demo‐Projekt“. 55 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Vorsicht, Einbahnstraße! Der i2b2‐Wizard kann nur in die Oracle‐Datenbank schreiben, sie aber nicht auslesen. Verwendet man parallel andere Konfigurationswerkzeuge, gerät man möglicherweise in Probleme. Außerdem kann man den i2b2‐Wizard nicht mit einem bereits bestehenden i2b2 verwenden … 56 28 31.05.2013 /i2b2wizard-1.3.5/ /i2b2src/ config/ Projekte und Benutzer‐ Konfiguration Konfigurierter i2b2 Quellcode i2b2‐Wizard i2b2 wizard.sh /opt/jboss-4.2.2.GA/ Achtung: Einweg! Benutzer und Projekte anlegen Oracle‐DB Projekte und Benutzer‐ Konfiguration Projekt‐Daten JBoss‐Applikationsserver mit i2b2‐ Webservices /var/www/admin Benutzer und Projekte managen Offizielles i2b2‐Administrations‐ Interface (http://localhost/admin) 57 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Vorsicht, Einbahnstraße! Daraus lassen sich folgende Faustregeln ableiten: Das Admin‐Interface am besten gar nicht benutzen. Soll der Server migriert werden, muss das config‐Verzeichnis und der Inhalt der Oracle‐Datenbank übertragen werden. Wird der i2b2‐Wizard manuell geupdated, muss das config‐ Verzeichnis wiederhergestellt werden. Wenn der i2b2‐Wizard zurückgesetzt wird (z.B. neu entpackt, wobei das config‐Verzeichnis nicht wiederhergestellt wird) muss die Oracle‐ Datenbank vorher geleert werden. Es ist in der Regel nicht möglich, ein i2b2 auf eine größere Major‐ Version zu aktualisieren. 58 29 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Vorsicht, Einbahnstraße! Datenbankeinstellungen: Dürfen nur VOR der Installation von i2b2 geändert werden. Das „system“‐ Login muss dem der Oracle‐ Installation entsprechen! Hive ID: Darf jederzeit geändert werden. Danach „System Setup >> Misc. Tasks >> Update Hive‐ID“ ausführen! JBoss‐Benutzer: Darf nur aktiviert werden, wenn vorher „System Setup >> Create JBoss User“ ausgeführt wurde. Passwörter von I2B2HIVE und I2B2PM: Dürfen nur geändert werden, bevor die beiden Schemata angelegt wurden. 59 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Netzwerksicherheit Vorsicht, wenn der Server mit dem Internet verbunden ist! Einige Softwarekomponenten (z. B. JBoss 4.2.2) sind veraltet. Außerdem wird die Standardkonfiguration der Softwarepakete nicht automatisch geändert/abgesichert (z. B. JBoss Web‐Interface‐Login). Bei einer Standardinstallation ist keine Firewall aktiv! Es kursieren Exploits und Scripte, mit denen derartige „Türen“ automatisch geöffnet werden können. Die Kommunikation zwischen Client und Server erfolgt unverschlüsselt. Lösungsansätze: Firewall‐Konfiguration oder SSH‐Tunnel 60 30 31.05.2013 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Netzwerksicherheit Ubuntu UFW Firewall SSH‐Administration erlauben: ufw allow from XXX.XXX.XXX.XXX to any port 22 Webclient erlauben: ufw allow from XXX.XXX.XXX.XXX to any port 80 Workbench erlauben: ufw allow from XXX.XXX.XXX.XXX to any port 9090 Firewall aktivieren: ufw enable Logging aktivieren und einsehen: ufw logging on tail –f /var/log/syslog 61 Sebastian Mate // Chair Of Medical Informatics // University of Erlangen‐Nuremberg Sonstiges Tipps & Tricks (Workarounds) für den i2b2‐Wizard Falls mal etwas nicht mehr klappt, einfach „System Setup >> Repair Installation“ ausführen. Achtung: Dies setzt alle Änderungen am i2b2 zurück, die außerhalb des i2b2‐Wizards stattgefunden haben! Wenn der Statusbalken beim Starten oder Stoppen von JBoss endlos läuft, erkennt der i2b2‐Wizard den Betriebszustand von JBoss nicht. In diesem Fall einfach den i2b2‐Wizard beenden und sh stop.sh ausführen. ... 62 31