rrenkert@411: Einrichtung der Anwendung LADA
rrenkert@411: ==============================
rrenkert@411: 
rrenkert@411: Dies ist die Prototypversion der Serverkomponente für die Anwendung LADA zur
rrenkert@411: Verarbeitung und Erfassung von Labordaten.
rrenkert@411: 
rrenkert@411: Die Software bietet grundlegende Funktionalität zur Erfassung und Bearbeitung
rrenkert@411: von Messdaten. Weitere Informationen finden sich auf der Projektwebseite unter
rrenkert@411: der Adresse:
rrenkert@411: 
rrenkert@411: 	https://wald.intevation.org/projects/lada/
rrenkert@411: 
rrenkert@411: Die Software entstand im Rahmen einer Software Entwicklung durch die
rrenkert@411: Intevation GmbH im Auftrag des Bundesamt für Strahlenschutz im Jahre 2013.
rrenkert@411: 
rrenkert@411: Lizenz
rrenkert@411: ------
rrenkert@411: Die Software unter der GNU GPL v>=3 Lizenz verfügbar. Details siehe die Datei
rrenkert@411: COPYING.
rrenkert@411: 
rrenkert@411: Quelltext
rrenkert@411: ---------
rrenkert@411: Die Quelldateien lassen sich wie folgt auschecken:
rrenkert@411: hg clone https://scm.wald.intevation.org/hg/lada/lada-server
rrenkert@411: 
rrenkert@411: 
rrenkert@411: Installation
rrenkert@411: ============
rrenkert@411: 
rrenkert@411: Die Installation der Serverkomponente erfordert folgende Vorraussetzungen:
rrenkert@411: 
rrenkert@411: * PostgreSQL-9.2/PostGIS-2.0 Datenbank inklusive Testdaten
rrenkert@411: * JBoss-AS
rrenkert@411: 
rrenkert@411: 
rrenkert@411: Datenbank
rrenkert@411: ---------
rrenkert@411: Die LADA Anwendung basiert auf einer PostgreSQL/PostGIS Datenbank in den
rrenkert@411: Versionen PostgreSQL 9.2/PostGIS 2.0.
rrenkert@411: Beipieldaten sind in dem Datenbankdump lada-db.zip verfügbar und können
rrenkert@411: in eine PostgreSQL/PostGIS Datenbank importiert werden.
rrenkert@411: Der dadurch verfügbare Testdatensatz enthält zusätzlich Daten zu Gemeinden und
rrenkert@411: Verwaltungen in Deutschland, die vom BKG zur Verfügung gestellt werden.
rrenkert@411: 
rrenkert@411: Einrichtung der Datenbankverbindung im JBoss AS
rrenkert@411: -----------------------------------------------
rrenkert@411: Die Datenbankverbindung wird im Application Server eingerichtet. Hierzu muss der
rrenkert@411: entsprechende Treiber zunächst als Modul eingefügt werden. Die folgenden
rrenkert@411: Schritte setzen vorraus, dass der JBoss AS in dem Ordner
rrenkert@411: /opt/jboss-as-7.1.1-Final installiert ist.
rrenkert@411: 
rrenkert@411: 1. Anlegen des Verzeichnisses und herunterladen der Treiber.
rrenkert@411: 
rrenkert@411: $cd /opt/jboss-as-7.1.1.Final/modules/org
rrenkert@411: $mkdir -p postgresql/main/
rrenkert@411: $cd postgresql/main
rrenkert@411: $curl -O "http://jdbc.postgresql.org/download/postgresql-9.2-1002.jdbc4.jar"
rrenkert@411: $curl -O "http://www.hibernatespatial.org/repository/org/postgis/postgis-jdbc/1.5.2/postgis-jdbc-1.5.2.jar"
rrenkert@411: 
rrenkert@411: 2. In dem Ordner /opt/jboss-as-7.1.1.Final/modules/org/postgresql/main/ eine
rrenkert@411: Datei module.xml mit folgendem Inhalt anlegen.
rrenkert@411: 
rrenkert@411: <?xml version="1.0" encoding="UTF-8"?>
rrenkert@411: <module xmlns="urn:jboss:module:1.0" name="org.postgresql">
rrenkert@411:     <resources>
rrenkert@411:         <resource-root path="postgresql-9.2-1002.jdbc4.jar"/>
rrenkert@411:         <resource-root path="postgis-jdbc-1.5.2.jar"/>
rrenkert@411:     </resources>
rrenkert@411:     <dependencies>
rrenkert@411:         <module name="javax.api"/>
rrenkert@411:         <module name="javax.transaction.api"/>
rrenkert@411:     </dependencies>
rrenkert@411: </module>
rrenkert@411: 
rrenkert@411: 3. Einfügen der Hibernate-Spatial Komponenten.
rrenkert@411: 
rrenkert@411: $cd /opt/jboss-as-7.1.1.Final/modules/org/hibernate/main
rrenkert@411: $curl -O "http://www.hibernatespatial.org/repository/org/hibernate/hibernate-spatial/4.0/hibernate-spatial-4.0.jar"
rrenkert@411: $curl -O "http://repo1.maven.org/maven2/com/vividsolutions/jts/1.13/jts-1.13.jar"
rrenkert@411: 
rrenkert@411: 4. Eintragen der Hibernate-Spatial Komponenten in
rrenkert@411: /opt/jboss-as-7.1.1.Final/modules/org/hibernate/main/module.xml
rrenkert@411: 
rrenkert@411: <resources>
rrenkert@411:     ...
rrenkert@411:     <resource-root path="hibernate-spatial-4.0.jar"/>
rrenkert@411:     <resource-root path="jts-1.13.jar"/>
rrenkert@411: </resources>
rrenkert@411: <dependencies>
rrenkert@411:     ...
rrenkert@411:     <module name="org.postgresql"/>
rrenkert@411: </dependencies>
rrenkert@411: 
rrenkert@411: 5. Einfügen des PostgreSQL Moduls als Treiber in die JBoss Konfiguration.
rrenkert@411: 
rrenkert@411:     In den Abschnitt <datasources> folgenden Block einfügen: 
rrenkert@411: 
rrenkert@411: <driver name="postgis" module="org.postgresql">
rrenkert@411:     <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
rrenkert@411: </driver>
rrenkert@411: 
rrenkert@411: 
rrenkert@411: Nun kann man eine neue Datenbankverbindung mit dem neuen Treiber einrichten.
rrenkert@411: Dazu verbindet man sich mit dem soeben angelegten Management-Nutzer mit der
rrenkert@411: Administrations-Webinterface unter der Adresse: http://localhost:9990
rrenkert@411: 
rrenkert@411: 1. Datesources auswählen. Hier werden alle derzeit eingerichteten Datenquellen
rrenkert@411:    angzeigt. Wir wollen eine neue einrichten. Hierzu
rrenkert@411: 2. Oben rechts von "Runtime" auf "Profile" wechseln.
rrenkert@411: 3. "Add" wählen.
rrenkert@411: 4. Name: Lada, JNDI: java:/jboss/Lada
rrenkert@411: 5. Treiber Wählen: postgis
rrenkert@411: 6. Weitere Verbindungsparameter angeben.
rrenkert@411:    a) connection url: jdbc:postgresql_postGIS://localhost:5432/lada
rrenkert@411:    b) Nutzer
rrenkert@411:    c) Password
rrenkert@411: 
rrenkert@411: 7.Da während dieser Einrichtung die Standard PostgreSQL Treiberklasse gewählt
rrenkert@411:   wird, muss diese noch in der Datei
rrenkert@411:     /opt/jboss-as-7.1.1.Final/standalone/configuration/standalone.xml
rrenkert@411:   geändert werden:
rrenkert@411:   Hierzu wird im Abschnitt <datasources> für die neu angelegte Datenquelle
rrenkert@411:     <driver-class>org.postgresql.Driver</driver-class> gegen
rrenkert@411:     <driver-class>org.postgis.DriverWrapper</driver-class> ausgetauscht.
rrenkert@411: 
rrenkert@411: Installation der LADA Anwendung
rrenkert@411: ===============================
rrenkert@411: Zur Installation der LADA Anwendung müssen folgende Schritte unternommen werden:
rrenkert@411: 
rrenkert@411: $cd /opt/jboss-as-7.1.1.Final/standalone/deployments
rrenkert@411: $cp /path/where/the/war/file/is/lada.war .
rrenkert@411: $touch lada.war.dodeploy
rrenkert@411: 
rrenkert@411: Zum Aktualisieren der Anwendung genügt es, wenn die lada.war Datei aktualisiert
rrenkert@411: wird.
rrenkert@411: 
rrenkert@411: Die Anwendung ist dann unter dem Pfad "/lada" (abhängig vom Archivnamen)
rrenkert@411: erreichbar.
rrenkert@411: 
rrenkert@411: Konfiguration der LADA Anwendung
rrenkert@411: ================================
rrenkert@411: Die Konfigurationsdateien sind Dateien im JSON-Format und können an einer
rrenkert@411: beliebigen Stelle im System abgelegt werden, solang diese Dateien für den
rrenkert@411: Nutzer, mit dem JBoss-Server gestartet wird, gelesen werden kann.
rrenkert@411: 
rrenkert@411: Bei Änderungen an der Konfigurationsdatei muss der Server nicht neu gestartet
rrenkert@411: werden. Es reicht ein erneutes Laden der Anwendung durch den Client.
rrenkert@411: Vorbereitete und vollständige Konfigurationsdateien sind in dem Ordner
rrenkert@411: 'config' zu finden.
rrenkert@411: 
rrenkert@411: Importer
rrenkert@411: --------
rrenkert@411: Der Pfad an dem diese Konfigurationsdatei zu finden ist wird in einer JBoss
rrenkert@411: Konfigurationsdatei "standalone.xml" abgelegt. Diese Datei findet sich im JBoss
rrenkert@411: Ordner ($JBOSSHOME/standalone/configuration/standalone.xml).
rrenkert@411: 
rrenkert@411: In dieser Datei wird der Pfad in Form einer Property abgelegt:
rrenkert@411: 
rrenkert@411: <server xmlns="urn:jboss:domain:1.2">
rrenkert@411: ...
rrenkert@411: 
rrenkert@411: <system-properties>
rrenkert@411:         <property name="de.intevation.lada.importconfig"
rrenkert@411: value="/pfad/zur/konfigurations/datei/des/importers.json"/>
rrenkert@411: </system-properties>
rrenkert@411: 
rrenkert@411: ...
rrenkert@411: </server>
rrenkert@411: 
rrenkert@411: Flexible Suche
rrenkert@411: --------------
rrenkert@411: Der Pfad an dem diese Konfigurationsdatei zu finden ist wird in einer JBoss
rrenkert@411: Konfigurationsdatei "standalone.xml" abgelegt. Diese Datei findet sich im JBoss
rrenkert@411: Ordner ($JBOSSHOME/standalone/configuration/standalone.xml).
rrenkert@411: 
rrenkert@411: In dieser Datei wird der Pfad in Form einer Property abgelegt:
rrenkert@411: 
rrenkert@411: <server xmlns="urn:jboss:domain:1.2">
rrenkert@411: ...
rrenkert@411: 
rrenkert@411: <system-properties>
rrenkert@411:         ...
rrenkert@411:         <property name="de.intevation.lada.sqlconfig"
rrenkert@411: value="/pfad/zur/konfigurations/datei/der/abfragen.json"/>
rrenkert@411: </system-properties>
rrenkert@411: 
rrenkert@411: ...
rrenkert@411: </server>
rrenkert@411: 
rrenkert@411: Einrichtung des Webservers (Apache)
rrenkert@411: ===================================
rrenkert@411: Die folgenden Module des Apache Webserver sind nötig, um die LADA Anwendung zu
rrenkert@411: betreiben:
rrenkert@411:   * ldap_module: Authenitfizierung gegen den LDAP
rrenkert@411:   * headers_module: Setzten der Header nach der Authenitifizierung
rrenkert@411:   * proxy_module: Reverse Proxy des Apache zum Jboss-Server
rrenkert@411: 
rrenkert@411: Damit der Client eine Verbindung zu dem Server aufbauen kann, um von dort Daten
rrenkert@411: laden zu können ist es notwendig den Server weiter zu konfigurieren.
rrenkert@411: 
rrenkert@411: togglesebool httpd_can_network_connect
rrenkert@411: service httpd restart
rrenkert@411: 
rrenkert@411: Dies erlaubt dem Apache grundsätzlich sich an einen anderen Dienst zu verbinden.
rrenkert@411: 
rrenkert@411: Nun muss noch ein Reverse-Proxy eingerichtet werden. Dieser ist nur für
rrenkert@411: bestimmte Adressen aktiv
rrenkert@411: 
rrenkert@411: Folgende Datei sollte unter "/etc/httpd/conf.d/lada.conf" angelegt werden:
rrenkert@411: 
rrenkert@411: <VirtualHost *:80>
rrenkert@411:     ServerAdmin webmaster@localhost
rrenkert@411:     #ServerName dummy-host.example.com
rrenkert@411:     ErrorLog logs/lada-error_log
rrenkert@411:     CustomLog logs/lada-access_log common
rrenkert@411: 
rrenkert@411:     # Set multiple Proxys
rrenkert@411:     ProxyPass /lada/server http://localhost:8080/lada
rrenkert@411:     ProxyPassReverse /lada/server http://localhost:8080/lada
rrenkert@411: </VirtualHost>
rrenkert@411: 
rrenkert@411: Alles Anfragen an die Adresse "/lada/service" werden nun an den JBoss
rrenkert@411: weitergeleitet.
rrenkert@411: 
rrenkert@411: Authentifizierung
rrenkert@411: 
rrenkert@411: Die Authentifizierung geschieht gegen einen LDAP-Server.
rrenkert@411: 
rrenkert@411: <Location /lada>
rrenkert@411:     AuthType basic
rrenkert@411:     AuthName "test"
rrenkert@411:     AuthBasicProvider ldap
rrenkert@411:     AuthLDAPURL "ldap://ike.polyhedra.intevation.de:389/cn=users,dc=icosahedron,dc=polyhedra,dc=intevation,dc=de?uid,memberof??(&(objectClass=inetOrgPerson)(memberOf=*))"
rrenkert@411:     Require valid-user
rrenkert@411: </Location>
rrenkert@411: 
rrenkert@411: <Location /lada/server>
rrenkert@411:     RequestHeader unset Authorization
rrenkert@411:     RequestHeader set X-LDAP-User "%{AUTHENTICATE_uid}e"
rrenkert@411:     RequestHeader set X-LDAP-Groups "%{AUTHENTICATE_memberof}e"
rrenkert@411: </Location>
rrenkert@411: 
rrenkert@411: Sofern gewünscht ist die Authentifizierung für Testzwecke zu deaktivieren muss
rrenkert@411: trotz allem die entsprechenden Header gesetzt werden, da der Server diese
rrenkert@411: derzeit erwartet.
rrenkert@411: 
rrenkert@411: # Set Headers to simulate Authentification.
rrenkert@411: <Location /lada/server>
rrenkert@411:         RequestHeader set X-LDAP-User "mst_06010"
rrenkert@411:         RequestHeader set X-LDAP-Groups "cn=Imis_world,cn=groups,dc=icosahedron,dc=polyhedra,dc=intevation,dc=de;cn=mst_06010,cn=groups,dc=icosahedron,dc=polyhedra,dc=intevation,dc=de;cn=mst_11010,cn=groups,dc=icosahedron,dc=polyhedra,dc=intevation,dc=de"
rrenkert@411: </Location>
rrenkert@411: 
rrenkert@411: Dokumentation
rrenkert@411: =============
rrenkert@411: Eine HTML-Dokumenation des Quellcodes(Javadoc) ist in dem Ordner 'doc' hinterlegt und
rrenkert@411: kann über einen Webserver (z.B. Apache WebServer) bereitgestellt werden.