diff README @ 469:9ba41a46f6e5

README added hints for installation, license etc.
author Torsten Irländer <torsten.irlaender@intevation.de>
date Tue, 14 Jan 2014 15:08:35 +0100
parents 067ecffac15d
children dd2b468dc1c2
line wrap: on
line diff
--- a/README	Tue Jan 14 12:29:07 2014 +0100
+++ b/README	Tue Jan 14 15:08:35 2014 +0100
@@ -1,5 +1,42 @@
 Lada-Client
 ===========
+Dies ist die Prototypversion eines EXTJS basierten Klienten für die
+Verarbeitung von Labordaten (Lada) zur Überwachung der Umweltradioaktivität.
+
+Die Software bietet grundlegende Funktionalität zur Erfassung und Bearbeitung
+von Messdaten. Weitere Informationen finden sich auf der Projektwebseite unter
+der Adresse:
+
+	https://wald.intevation.org/projects/lada/
+
+Die Software entstand im Rahmen einer Software Entwicklung durch die
+Intevation GmbH im Auftrag des Bundesamt für Strahlenschutz im Jahre 2013.
+
+Lizenz
+------
+Die Software unter der GPL Affero Lizenz verfügbar.
+
+Quellen
+-------
+Die Quelldateien lassen sich wie folgt auschecken:
+hg clone https://scm.wald.intevation.org/hg/lada/lada-client
+
+Dokumentation
+-------------
+Die Dokumentation wird mit dem Tool JSDuck erzeugt.
+Im Wurzelordner lässt sich nach der Installation von JSDuck dann mit dem
+Befehl "jsduck" die Dokumentation für den Lada-Clienten erzeugen.
+Die Dokumentation findet sich nach der Generierung in dem Order "doc".
+Einstiegseite ist die Seite template.html.
+
+JSDuck ist unter der Adresse
+
+https://github.com/senchalabs/jsduck
+
+zu finden und muss installiert werden.
+
+Einstellung bezüglich der Generierung der Dokumentation ist in der Datei
+jsduck.json hinterlegt.
 
 Entwicklung
 -----------
@@ -26,8 +63,8 @@
 Bibliothek eingebunden werden. Dazu wird der Ordner 'i18n' in den Ordner 'src' kopiert
 oder verlinkt.
 
-Installation
-------------
+Build
+-----
 Die Anwendung wird mit Hilfe des von Sencha bereitgestellten Tools 'Sencha Cmd'
 compiliert und minifiziert. Vorbedingung für den Compilevorgang ist die unter
 Entwicklung beschriebene Verzeichnisstruktur.
@@ -48,19 +85,113 @@
 alle benötigten Klassen der ExtJS Bibliothek beinhaltet und eine entsprechende
 index.html, die zur Auslieferung in einem Webserver verwendet werden kann.
 
-Dokumentation
--------------
-Die Dokumentation wird mit dem Tool JSDuck erzeugt.
-Im Wurzelordner lässt sich nach der Installation von JSDuck dann mit dem
-Befehl "jsduck" die Dokumentation für den Lada-Clienten erzeugen.
-Die Dokumentation findet sich nach der Generierung in dem Order "doc".
-Einstiegseite ist die Seite template.html.
+Installation
+------------
+Für den Betrieb des Lada-Clients muss dieser innerhalb einer Webserver-Umgebung
+installiert werden. Die folgenden Hinweise geben eine Kurze Anleitung zur
+Installation eines Apache-Webserver.
 
-JSDuck ist unter der Adresse
-
-https://github.com/senchalabs/jsduck
+Hinweis: Für den Betrieb einer vollständigen Installation ist neben dem
+Klienten auch die Installation eines Servers und entsprechender Datenbank
+notwendig. Für die Installation des Servers folgen Sie bitte den Hinweisen in
+der README Datei des Server-Pakets. Siehe Projektwebseite. Optional: Die
+Authentifizierung kann gegen einen LDAP-Server durchgeführt werden. Beispiele
+finde sich in dem Installationbeispiel.
 
-zu finden und muss installiert werden.
+Die folgenden Hinweise beziehen sich auf die Installation und Einrichtung auf
+Basis eines Oracle-RedHat Linux Systems.
 
-Einstellung bezüglich der Generierung der Dokumentation ist in der Datei
-jsduck.json hinterlegt.
+Installation Apache
+```````````````````
+Zunächst wird der Apache Webserver aus dem Repository installiert:
+
+	yum install httpd mod_ssl
+	service httpd start
+
+Aktivierung der Apache Module
+`````````````````````````````
+
+Die Konfiguration, welche Module beim Start des Apache geladen werden, erfolgt
+in der Datei "/etc/httpd/conf". Die zu ladende Module sind in dieser Datei mit
+der Option "LoadModule" angegeben. Folgende Module werden benötigt:
+
+	* ldap_module: Authenitfizierung gegen den LDAP
+	* headers_module: Setzten der Header nach der Authenitifizierung
+	* proxy_module: Reverse Proxy des Apache zum Jboss-Server
+
+Einrichtung der Anwendung
+`````````````````````````
+Zunächst hinterlegen wir die Anwendung in dem Server.
+
+cd /var/www/html
+hg clone https://scm.wald.intevation.org/hg/lada/lada-client/ lada
+cd lada
+git clone https://github.com/elmasse/Ext.i18n.Bundle.git
+curl -O http://cdn.sencha.com/ext/gpl/ext-4.2.0-gpl.zip
+unzip ext-4.2.0-gpl.zip
+ln -s ext-4.2.0.663 extjs
+rm ext-4.2.0-gpl.zip
+cd extjs/src
+ln -s ../../Ext.i18n.Bundle/i18n i18n
+
+# Wichtig um SELinux dazu zu überreden das neue Verzeichnis auch zu
+# servieren:
+restorecon -Rv /var/www/html/
+
+Die Anwendung sollte nun bereits unter der Adresse http://localhost/lada
+erreichbar sein.
+
+Konfiguration Proxy Server
+``````````````````````````
+Damit der Client eine Verbindung zu dem Server aufbauen kann, um von dort
+Daten laden zu können, ist es notwendig den Server weiter zu konfigurieren.
+
+	togglesebool httpd_can_network_connect
+	service httpd restart
+
+Dies erlaubt dem Apache grundsätzlich sich mit einem anderen Dienst zu verbinden.
+Nun muss noch ein Reverse-Proxy eingerichtet werden. Dieser ist nur für
+bestimmte Adressen aktiv
+
+Folgende Datei sollte unter "/etc/httpd/conf.d/lada.conf" angelegt werden:
+
+	<VirtualHost *:80>
+	    ServerAdmin webmaster@localhost
+	    #ServerName dummy-host.example.com
+	    ErrorLog logs/lada-error_log
+	    CustomLog logs/lada-access_log common
+
+	    # Set multiple Proxys
+	    ProxyPass /lada/server http://localhost:8080/lada
+	    ProxyPassReverse /lada/server http://localhost:8080/lada
+	</VirtualHost>
+
+Alle Anfragen an die Adresse "/lada/service", werden nun an den Server weitergeleitet.
+
+Authentifizierung
+`````````````````
+Die Authentifizierung geschieht gegen einen LDAP-Server.
+
+<Location /lada>
+    AuthType basic
+    AuthName "test"
+    AuthBasicProvider ldap
+    AuthLDAPURL "ldap://ike.polyhedra.intevation.de:389/cn=users,dc=icosahedron,dc=polyhedra,dc=intevation,dc=de?uid,memberof??(&(objectClass=inetOrgPerson)(memberOf=*))"
+    Require valid-user
+</Location>
+
+<Location /lada/server>
+    RequestHeader unset Authorization
+    RequestHeader set X-LDAP-User "%{AUTHENTICATE_uid}e"
+    RequestHeader set X-LDAP-Groups "%{AUTHENTICATE_memberof}e"
+</Location>
+
+Sofern gewünscht, kann die Authentifizierung für Testzwecke zu deaktivieren
+werden. Trotz allem müssen die entsprechenden Header gesetzt werden, da der
+Server zur Authentifizierung und Authorisierung erwartet.
+
+# Set Headers to simulate Authentification.
+	<Location /lada/server>
+		RequestHeader set X-LDAP-User "mst_06010"
+		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"
+	</Location>

http://lada.wald.intevation.org