view 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 source
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
-----------
Für die Entwicklung ist es notwenig in dem Wurzelordner die ExtJS-Bibliothek
in der Version >=4.2.0 unter dem Namen "extjs" zur Verfügung zu stellen.

Diese lässt sich unter der folgenden URL herunterladen:
http://cdn.sencha.com/ext/gpl/ext-4.2.0-gpl.zip

SHA1 Checksum: 2ce990d9e90c48a76078e8533c72b5452f9ed809

Beispiel:
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-gpl extjs

Zusätzlich wird für diese Anwendung eine Bibliothek zur Internationalisierung
verwendet, die unter der URL

https://github.com/elmasse/Ext.i18n.Bundle

verfügbar ist, verwendet.
Diese muss in dem Ordner 'src' der vorher zur Verfügung gestellten ExtJS
Bibliothek eingebunden werden. Dazu wird der Ordner 'i18n' in den Ordner 'src' kopiert
oder verlinkt.

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.

Sencha Cmd kann unter der URL

http://www.sencha.com/products/sencha-cmd/download

heruntergeladen und dann installiert werden.

Mit dem folgenden Befehl kann dann der Lada-Client compiliert und minifiziert werden:

sencha -sdk /path/to/extjs compile \
       -classpath=app,app/view/widgets/resources/datetime page -yui \
       -in index.html -out build/index.html

Dies erzeugt in dem Ordner 'build' die minifizierte Version der Anwendung, die
alle benötigten Klassen der ExtJS Bibliothek beinhaltet und eine entsprechende
index.html, die zur Auslieferung in einem Webserver verwendet werden kann.

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.

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.

Die folgenden Hinweise beziehen sich auf die Installation und Einrichtung auf
Basis eines Oracle-RedHat Linux Systems.

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