rrenkert@411: Installation
rrenkert@411: ============
torsten@412: Allgemeine Informationen finden Sie in der README Datei
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@415: Zum Bauen der Anwendung aus den Quellen wird zusätzlich das Build-Tool 'maven'
rrenkert@415: benötigt.
rrenkert@415: 
rrenkert@415: Installation JBoss-AS
rrenkert@415: -------------------------
rrenkert@415: 
rrenkert@415: Im folgenden ist die Installation des JBoss-AS in dem Ordner /opt beschrieben.
rrenkert@415: 
rrenkert@415: $ cd /opt
rrenkert@415: $ curl -O http://download.jboss.org/jbossas/7.1/jboss-as-7.1.1.Final/jboss-as-7.1.1.Final.zip
rrenkert@415: # Integrität prüfen. Leider bietet Redhat für diese "Community Edition" keinen
rrenkert@415: # Überprüfungsweg an. Vermutlich als Verkaufsanreiz für die professionelle
rrenkert@415: # Version. Beim Herunterladen am 2013-05-09 hatte die Datei folgende sha256
rrenkert@415: # Prüfsumme:
rrenkert@415: # 0aece7899b54c0219732112307b2bede78ab9b39ee14140ce89ac8c1b716d0ee
rrenkert@415: # jboss-as-7.1.1.Final.zip
rrenkert@415: $ unzip jboss-as-7.1.1.Final.zip
rrenkert@415: 
rrenkert@415: # Der Jboss Server soll nicht als root, sondern unter einem dedizierten Nutzer
rrenkert@415: # laufen. In diesem Fall als Nutzer "lada". Hierfür müssen einige
rrenkert@415: # Berechtigungen angepasst werden.
rrenkert@415: $ USER=lada
rrenkert@415: $ chgrp -R ${USER} jboss-as-7.1.1.Final
rrenkert@415: $ cd jboss-as-7.1.1.Final
rrenkert@415: $ chmod 775 standalone/
rrenkert@415: $ chmod 775 standalone/deployments
rrenkert@415: $ chmod 775 standalone/tmp
rrenkert@415: $ chmod 775 standalone/configuration
rrenkert@415: $ chmod 660 standalone/configuration/mgmt-users.properties
rrenkert@415: $ chmod 660 standalone/configuration/application-users.properties
rrenkert@415: 
rrenkert@415: Einrichten eines Admin Zugangs
rrenkert@415: ``````````````````````````````
rrenkert@415: Um den JBoss Server über die Weboberfläche administrieren zu können muss
rrenkert@415: zunächst ein neuer Nutzer erstellt werden:
rrenkert@415: 
rrenkert@415: $ cd jboss-as-7.1.1.Final
rrenkert@415: $ sh bin/add-user.sh
rrenkert@415: 
rrenkert@415: Einrichten von JBoss als Service
rrenkert@415: ````````````````````````````````
rrenkert@415: JBoss soll als Service start und beendbar sein.
rrenkert@415: 
rrenkert@415: $ cd /etc/init.d
rrenkert@415: $ cp /opt/jboss-as-7.1.1.Final/bin/init.d/jboss-as-standalone.sh jboss
rrenkert@415: 
rrenkert@415: # In diesem SCRIPT müssen dann folgene Variablen angepasst werden:
rrenkert@415: # 1. JBOSS_HOME=/opt/jboss-as-7.1.1.Final
rrenkert@415: # 2. JBOSS_USER=lada
rrenkert@415: 
rrenkert@415: $ servive jboss start
rrenkert@415: 
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@414: Hierzu sollte vorher ein Benutzer in der Datenbank angelegt werden. In der
rrenkert@414: folgenden Installationsanleitung wird davon ausgegangen, dass ein Benutzer
rrenkert@414: 'lada' in der Datenbank existiert.
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@414:    b) Nutzer (lada)
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@415: Erstellen der Anwendung aus den Quellen (optional)
rrenkert@415: --------------------------------------------------
rrenkert@415: 
rrenkert@415: Befehle zum Bauen der Anwendung aus den Quellen:
rrenkert@415: 
rrenkert@415: $ cd /path/to/sources/
rrenkert@415: $ mvn clean compile package
rrenkert@415: 
rrenkert@415: Das WAR-Archiv der Anwendung wird in dem Ordner 'target/' abgelegt.
rrenkert@415: 
rrenkert@415: Installation des Pakets
rrenkert@415: -----------------------
rrenkert@415: 
rrenkert@415: $ cd /opt/jboss-as-7.1.1.Final/standalone/deployments
rrenkert@415: $ cp /path/where/the/war/file/is/lada.war .
torsten@412: touch lada.war.dodeploy
torsten@412: 
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.