Diese Anleitung beschreibt die Installation der Webschnittstelle von Startkladde (sk_web) unter Windows.
Es gibt verschiedene Arten, eine Rails-Anwendung wie sk_web zu betreiben. Diese Anleitung beschreibt die Verwendung des Apache-Servers mit einem Mongrel-Cluster. In dieser Konfiguration werden die Zugriff durch Apache auf einen von mehreren Mongrel-Servern weitergeleitet.
Da sk_web in Ruby geschrieben ist, muss eine Ruby-Umgebung installiert werden. Diese kann unter http://rubyinstaller.org/downloads/ heruntergeladen werden. Es wird mindestens Version 1.8.7 benötigt. Der Betrieb mit Ruby ab Version 1.9 ist nicht erprobt. Daher sollte eine Version 1.8.x verwendet werden. Die Option „Add Ruby executables to your PATH“ während der Installation sollte aktiviert werden.
Für den Webserver Apache bietet es sich an, ein Komplettpaket wie zum Beispiel XAMPP zu verwenden. Dies enthält einen vollständig konfigurierten Apache-Server sowie einen MySQL-Server (und weitere Software, die aber für die Zwecke dieser Installationsanleitung nicht relevant sind).
Apache kann auch als allein stehende Anwendung oder mit einem anderen Paket als XAMPP installiert werden. Bei der Konfiguration muss darauf geachtet werden, dass auch der verschlüsselte Zugang (SSL) aktiviert wird.
Falls ein Komplettpaket verwendet wird, ist darauf zu achten, dass mindestens Version 5.1 des MySQL-Servers benötigt wird.
Sofern der MySQL-Server nicht bereits zusammen mit dem Webserver installiert wurde, kann er von der MySQL-Webseite heruntergeladen werden (Community-Server, MSI Installer Essentials). Es wird mindestens Version 5.1 benötigt.
Darüber hinaus muss die Datei libmysql.dll aus dem bin-Verzeichnis des MySQL-Servers in das bin-Verzeichnis der Ruby-Installation kopiert werden. Auf Grund eines Problems mit aktuelleren Versionen muss die libmysql.dll aus MySQL Version 5.0.x verwendet werden. Diese kann von der MySQL-Downloadseite heruntergeladen werden (direkter Link: 32 Bit, 64 Bit).
Es wird mindestens Version 2.0.3 benötigt.
Die Anwendung wird in ein beliebiges Verzeichnis entpackt. Das Verzeichnis muss nicht im Verzeichnisbaum des Webserver liegen. Im folgenden wird davon ausgegangen, dass das Verzeichnis c:\Programme\sk_web gewählt wurde. Anderenfalls sind die Konfigurationswerte ensprechend anzupassen.
Achtung: die Anwendung darf nicht auf einem Netzlaufwerk installiert werden, da das Starten der Dienste in diesem Fall nicht funktioniert.
Ruby verwendet eine eigene Paketverwaltung. Ruby-Pakete heißen „gems“. Für den Betrieb der Anwendung müssen noch einige gems installiert werden. Dafür wird die Eingabeaufforderung („Start command prompt with Ruby“ im Startmenü unter „Ruby“) verwendet. Hierfür werden Administratorrechte benötigt.
Einige gems werden explizit installiert:
gem install --no-rdoc --no-ri "--version=~>2.3.8" rails gem install --no-rdoc --no-ri mysql gem install --no-rdoc --no-ri mongrel gem install --no-rdoc --no-ri --pre mongrel_service
Weitere benötigte gems werden automatisch installiert:
c: cd \Programme\sk_web rake gems:install
Die Gems werden über das Internet heruntergeladen und installiert. Dies kann einige Zeit in Anspruch nehmen. Während dem Herunterladen erfolgt keine Rückmeldung.
Im folgenden wird davon ausgegangen, dass die Anwendung auf dem Server unter dem Pfad /startkladde erreichbar sein soll. Anderenfalls ist die Konfiguration entsprechend anzupassen.
Die Konfiguration der der Anwendung ist unter Konfiguration - Webschnittstelle beschrieben. Für den Betrieb müssen zumindest die Zugangsdaten für die Datenbank konfiguriert werden. Die sonstigen Einstellungen können vorerst auf den Voreinstellungen belassen werden.
Darüber hinaus muss die Datei config/local_environment.rb.dist nach config/local_environment.rb kopiert werden und dort die folgende Zeile aktiviert werden:
ENV['RAILS_RELATIVE_URL_ROOT'] ||= '/startkladde'
Die Datenbank wird beim ersten Start des Erfassungsprogramms automatisch initialisiert. Dies ist erforderlich, bevor die Webschnittstelle verwendet werden kann.
Hierfür muss das Administratorpasswort des MySQL-Servers eingegeben werden. Bei XAMPP ist standardmäßig kein Administratorpasswort gesetzt. Dies kann über die Webschnittstelle von XAMPP unter http://localhost/security/xamppsecurity.php geändert werden. Anschließend muss MySQL neu gestartet werden.
Der Server wird mittels seiner Konfigurationsdatei eingerichtet. Bei XAMPP ist dies die Datei apache/conf/httpd.conf im Installationsverzeichnis von XAMPP. Bei anderen Installationen kann die Datei einen anderen Namen haben oder es kann mehrere Konfigurationsdateien geben.
In der Konfigurationsdatei müssen die Module mod_rewrite, mod_proxy, mod_proxy_http, mod_proxy_balancer und mod_headers geladen werden (LoadModule-Einträge). Bei XAMPP sind die entsprechenden Einträge bereits vorhanden und auskommentiert, müssen also nur aktiviert werden.
Außerdem wird am Ende der Konfigurationsdatei der folgende Abschnitt eingefügt:
ProxyRequests Off
<Location "/startkladde">
ProxyPass balancer://startkladde_cluster
RequestHeader set X_FORWARDED_PROTO 'https' env=HTTPS
</Location>
<Proxy balancer://startkladde_cluster lbmethod=bybusyness>
Order allow,deny
Allow from all
BalancerMember http://127.0.0.1:3001
BalancerMember http://127.0.0.1:3002
BalancerMember http://127.0.0.1:3003
</Proxy>
Damit die Änderungen wirksam werden, muss Apache neu gestartet werden.
Der Mongrel-Server wird als Windows-Dienst eingerichtet. Dafür werden im Installationsverzeichnis der Webanwendung folgende Befehle ausgeführt (hierfür sind Administratorrechte notwendig!):
mongrel_rails service::install --name sk_web_1 --environment production --port 3001 mongrel_rails service::install --name sk_web_2 --environment production --port 3002 mongrel_rails service::install --name sk_web_3 --environment production --port 3003
Die Dienste können dann über Systemsteuerung - Verwaltung - Dienste gestartet und beendet werden. Hier kann auch eingestellt werden, dass die Dienste beim Starten von Windows automatisch gestartet werden.
Zu beachten ist, dass es nach dem Starten der Dienste einige Zeit lang dauern kann, bis der Server tatsächlich ansprechbar ist (bis zu einer Minute). In dieser Zeit zeigt der Task-Manager eine hohe CPU-Auslastung an.
Zum Starten und Beenden der Dienste können alternativ auch die folgenden Kommandos verwendet werden:
net start sk_web_1 net stop sk_web_1
In diesem Beispiel werden 3 Mongrel-Prozesse verwendet. Falls eine andere Anzahl an Prozessen verwendet werden soll, ist die Anzahl der Aufrufe von mongrel_rails service::install entsprechend zu ändern. Außerdem müssen in der Konfiguration von Apache die BalancerMember-Einträge angepasst werden.
Sollen die Dienste später wieder entfernt werden, so kann dafür der folgende Befehl verwendet werden:
mongrel_rails service::remove -N sk_web_1 ...
Sofern der Apache- und die Mongrel-Dienste gestartet wurden, ist die Anwendung jetzt vom gleichen Rechner aus unter http://localhost/startkladde erreichbar. Zum Zugriff über das Netzwerk ist der Name localhost durch den Namen oder die Adresse des Servers zu ersetzen, zum Beispiel http://server/startkladde oder http://192.168.1.1/startkladde.
In der Fußzeile der Anwendung wird der Betriebsmodus angezeigt. Hier sollte unbedingt „production“ stehen, da der Entwicklungsmodus („development“) sehr langsam ist.
Um ein Update durchzuführen, muss zuerst der Mongrel-Dienst beendet werden. Dann kann das Update über die alte Installation entpackt werden, sofern nicht eigene Änderungen an der Anwendung vorgenommen wurden. Die Konfigurationsdateien werden dabei nicht überschrieben.
Danach kann der Dienst wieder gestartet werden.
Die Anwendung schreibt Meldungen über Zugriffe und Fehler in eine Protokolldatei. Diese befindet sich im Unterverzeichnis log der Anwendung. Bei Problemen kann diese Protokolldatei sowie die Protokolldatei error.log des Apache-Server nützlich sein.
Der Zugriff auf mongrel sollte auch direkt unter http://localhost:3001 etc. möglich sein. Ist dies nicht möglich, so läuft vermutlich mongrel nicht.
Anstatt als Windows-Dienst kann mongrel auch direkt gestartet werden. Dazu wird im Installationsverzeichnis der Anwendung der folgende Befehl ausgeführt:
ruby script/server
Der Startvorgang ist abgeschlossen, wenn die Meldung „Use CTRL-C to stop“ ausgegeben wird. Die Anwendung ist dann unter http://localhost:3000 erreichbar. Fehlermeldungen des Servers werden direkt im Befehlsfenster angezeigt.
Beim direkten Zugriff auf mongrel kann es sein, dass Links in der Webanwendung nicht korrekt funktionieren und Bilder sowie Style-Sheets nicht korrekt geladen werden. Diese Betriebsart ist also nur geeignet, um die prinzipielle Funktion des Servers zu überprüfen.
Außerdem ist in diesem Fall der Zugriff über das Netzwerk nicht möglich (nur vom gleichen Rechner, auf dem der Server läuft, unter dem Namen localhost). Darüber hinaus sind keine gleichzeitige Zugriffe möglich. Während also ein länger dauernder Zugriff läuft (zum Beispiel Erzeugung einer PDF-Datei) werden keine weiteren Anfragen beantwortet.