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: Sebastian.Mate@imi.med.uni-erlangen.de
Webseite: http://www.imi.med.uni-erlangen.de
Autor 2: Jan Christoph
91054 ERLANGEN
Telefon +49 9131/85-26726
Fax +49 9131/85-26754
E-Mail: jan.christoph@uk-erlangen.de
Autor 3: Prof. Dr. Hans-Ulrich Prokosch
Lehrstuhl für Medizinische Informatik
91054 ERLANGEN
Telefon +49 9131/85-26701
Fax +49 9131/85-36799
E-Mail: Hans-Ulrich.Prokosch@uk-erlangen.de
sowie:
Medizinisches Zentrum für Informations- und Kommunikationstechnik
91054 ERLANGEN
Autor 4: Dr. Thomas Ganslandt
Medizinisches Zentrum für Informations- und Kommunikationstechnik
91054 ERLANGEN
Telefon +49 9131/85-26753
Fax +49 9131/85-26754
E-Mail: Thomas.Ganslandt@uk-erlangen.de
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.
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.
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.
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
10 / 11
Anhänge
i2b2-Wizard Anleitung
Präsentation mit „Installations Walk-Through“
11 / 11
i2b2 Wizard
Chair of Medical Informatics,
University of Erlangen-Nuremberg, Germany
and the IDRT team
Contact: Sebastian.Mate@imi.med.uni-erlangen.de
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
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

The first steps were very time consuming:
4
2
31.05.2013
Oracleconfiguration
PMconfiguration
5

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
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
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
Future goal
additional tools: managing the setup “in production”
install.sh
generic install: server software and i2b2 only
Project Setup
Ontology Tool
9
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
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
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
Anlegen der Ubuntu‐Linux‐VM unter VirtualBox:
13
Die VM sollte mindestens 1GB RAM haben.
14
7
31.05.2013
Die Festplatte sollte mindestens 16 GB Speicherplatz bieten.
15
In den Netzwerkeinstellungen muss ein „Host‐Only Ethernet Adapter“ hinzugefügt werden.
16
8
31.05.2013
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
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
Es muss Englisch als Systemsprache eingestellt werden!
19
Das Keyboard‐Layout darf aber wieder deutsch sein …
20
10
31.05.2013
Das manuelle Partitionieren ist der komplizierteste Teil …
21
22
11
31.05.2013
23
Mindestens 1 GB SWAP space
24
12
31.05.2013
25
Der Rest wird für / verwendet.
26
13
31.05.2013
27
„i2b2“. Für den Workshop ist das sicher genug.
28
14
31.05.2013
29
Nach dem Start von Linux
Die folgenden Folien zeigen, was nach der Linux‐Installation zu erledigen ist.
30
15
31.05.2013
eth0 aktivieren
Falls möglich, die beiden Netzwerkverbindungen aktivieren:
eth1 aktivieren
31
Das frische Linux updaten!
32
16
31.05.2013
33
34
17
31.05.2013
Root‐Passwort setzen (i2b2)
i2b2‐Wizard herunterladen
35
und entpacken …
36
18
31.05.2013
Hier beginnt der
Workshop …
Starten …
37
38
19
31.05.2013
39
Einfach /.1.6.02 anfügen und der i2b2‐Wizard lädt alles selbst herunter.
40
20
31.05.2013
Workshop: Falls jemand offline ist und deswegen die Dateien nicht herunterladen kann, „No“ auswählen und …
41
… die Dateien manuell an den richtigen Ort kopieren.
42
21
31.05.2013
8080
1521
i2b2
i2b2
y
43
44
22
31.05.2013
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
Nun den JBoss‐
Applikationsserver starten …
46
23
31.05.2013
Hoppla! Die Konfiguration hat sich geändert. i2b2‐Wizard erledigt aber alles automatisch …
47
demouser
Nun wird es spannend …
48
24
31.05.2013
Funktioniert! 
49
Hier bitte keine Sonderzeichen verwenden!
50
25
31.05.2013
Neuen Benutzer anlegen: „Main Menu >> User Management“
51
52
26
31.05.2013
Den neuen Benutzer dem neuen Projekt zuweisen
53
Nun den JBoss‐
Applikationsserver starten …
54
27
31.05.2013
Nach dem Login mit dem neuen Benutzer findet man das i2b2‐Wizard „Minimal‐
Demo‐Projekt“.
55
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
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
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
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
Netzwerksicherheit
Ubuntu UFW Firewall

SSH‐Administration erlauben:
ufw allow from XXX.XXX.XXX.XXX to any port 22

Webclient erlauben:

Workbench erlauben:

Firewall aktivieren: ufw enable

Logging aktivieren und einsehen:
ufw logging on
tail –f /var/log/syslog
61
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

D2.1 i2b2 Wizard

Transcription

Similar documents

TMF-Workshop TMF-Workshop