X-Git-Url: http://wagnertech.de/git?a=blobdiff_plain;f=doc%2FINSTALL.fcgi;h=31ba60f18a1d1f211df8e017f07ee06d731615be;hb=76e3efe63976405fd9478eac0711a7c127ddba41;hp=b326ffcc7ece94736847b541c26de20c50a33f36;hpb=a07567c250ce184719dd7e5cfede05d5359ac65c;p=kivitendo-erp.git diff --git a/doc/INSTALL.fcgi b/doc/INSTALL.fcgi index b326ffcc7..31ba60f18 100644 --- a/doc/INSTALL.fcgi +++ b/doc/INSTALL.fcgi @@ -5,13 +5,15 @@ Diese Datei ist in Plain Old Documentation geschrieben. Mit ist sie deutlich leichter zu lesen. -=head1 FastCGI für Lx-Office +=encoding utf8 + +=head1 FastCGI für Lx-Office =head2 Was ist FastCGI? Direkt aus L kopiert: - FastCGI ist ein Standard für die Einbindung externer Software zur Generierung + FastCGI ist ein Standard für die Einbindung externer Software zur Generierung dynamischer Webseiten in einem Webserver. FastCGI ist vergleichbar zum Common Gateway Interface (CGI), wurde jedoch entwickelt, um dessen Performance-Probleme zu umgehen. @@ -20,91 +22,187 @@ Direkt aus L kopiert: =head2 Warum FastCGI? Perl Programme (wie Lx-Office eines ist) werden nicht statisch kompiliert. -Stattdessen werden die Quelldateien bei jedem Start übersetzt, was bei kurzen -Laufzeiten einen Großteil der Laufzeit ausmacht. Während SQL Ledger einen -Großteil der Funktionalität in einzelne Module kapselt, um immer nur einen -kleinen Teil laden zu müssen, ist die Funktionalität von Lx-Office soweit +Stattdessen werden die Quelldateien bei jedem Start übersetzt, was bei kurzen +Laufzeiten einen Großteil der Laufzeit ausmacht. Während SQL Ledger einen +Großteil der Funktionalität in einzelne Module kapselt, um immer nur einen +kleinen Teil laden zu müssen, ist die Funktionalität von Lx-Office soweit gewachsen, dass immer mehr Module auf den Rest des Programms zugreifen. -Zusätzlich benutzen wir umfangreiche Bibliotheken um Funktionaltät nicht selber -entwickeln zu müssen, die zusätzliche Ladezeit kosten. All dies führt dazu dass -ein Lx-Office Aufruf der Kernmasken mittlerweile deutlich länger dauert als -früher, und dass davon 90% für das Laden der Module verwendet wird. +Zusätzlich benutzen wir umfangreiche Bibliotheken um Funktionaltät nicht selber +entwickeln zu müssen, die zusätzliche Ladezeit kosten. All dies führt dazu dass +ein Lx-Office Aufruf der Kernmasken mittlerweile deutlich länger dauert als +früher, und dass davon 90% für das Laden der Module verwendet wird. Mit FastCGI werden nun die Module einmal geladen, und danach wird nur die -eigentliche Programmlogik ausgeführt. +eigentliche Programmlogik ausgeführt. =head2 Kombinationen aus Webservern und Plugin. Folgende Kombinationen sind getestet: + * Apache 2.2.11 (Ubuntu) und mod_fcgid. * Apache 2.2.11 (Ubuntu) und mod_fastcgi. -Folgende Kombinationen funktionieren nicht: +Dabei wird mod_fcgid empfohlen, weil mod_fastcgi seit geraumer Zeit +nicht mehr weiter entwickelt wird. - * Apache 2.2.11 (Ubuntu) + mod_fcgid: +Als Perl Backend wird das Modul FCGI.pm verwendet. Vorsicht: FCGI 0.69 und +höher ist extrem strict in der Behandlung von Unicode, und verweigert bestimmte +Eingaben von Lx-Office. Solange diese Probleme nicht behoben sind, muss auf die +Vorgängerversion FCGI 0.68 ausgewichen werden. +Mit cpan lässt sie sich wie folgt installieren: + force install M/MS/MSTROUT/FCGI-0.68.tar.gz =head2 Konfiguration des Webservers. -Variante 1: +Bevor Sie versuchen eine Lx-Office Installation unter FCGI laufen zu lassen, +empfliehlt es sich die Installation ersteinmal unter CGI aufzusetzen. FCGI +macht es nicht einfach Fehler zu debuggen die beim ersten aufsetzen auftreten +können. Sollte die Installation schon funktionieren, lesen Sie weiter. + +Zuerst muss das FastCGI-Modul aktiviert werden. Dies kann unter +Debian/Ubuntu z.B. mit folgendem Befehl geschehen: + + a2enmod fcgid + +bzw. + + a2enmod fastcgi + +Die Konfiguration für die Verwendung von Lx-Office mit FastCGI erfolgt +durch Anpassung der vorhandenen Alias- und Directory-Direktiven. Dabei +wird zwischen dem Installationspfad von Lx-Office im Dateisystem +("/path/to/lx-office-erp") und der URL unterschieden, unter der +Lx-Office im Webbrowser erreichbar ist ("/web/path/to/lx-office-erp"). + +Folgendes Template funktioniert mit mod_fastcgi: + + AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fcgi + Alias /web/path/to/lx-office-erp/ /path/to/lx-office-erp/ + + + AllowOverride All + Options ExecCGI Includes FollowSymlinks + Order Allow,Deny + Allow from All + + + + Order Deny,Allow + Deny from All + + +Für mod_fcgid muss ein AddHandler ergänzt werden und die erste Zeile geändert werden: - AddHandler fastcgi-script .pl + AddHandler fcgid-script .fpl + AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl + +Seit mod_fcgid-Version 2.6.3 gelten sehr kleine Grenzen für die +maximale Größe eines Requests. Diese sollte wie folgt hochgesetzt werden: -Variante 2: + FcgidMaxRequestLen 10485760 +Das ganze sollte dann so aussehen: + + AddHandler fcgid-script .fpl AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl + Alias /web/path/to/lx-office-erp/ /path/to/lx-office-erp/ + FcgidMaxRequestLen 10485760 AllowOverride All - AddHandler fastcgi-script .fpl Options ExecCGI Includes FollowSymlinks Order Allow,Deny Allow from All - + Order Deny,Allow Deny from All +Hierdurch wird nur ein zentraler Dispatcher gestartet. Alle Zugriffe +auf die einzelnen Scripte werden auf diesen umgeleitet. Dadurch, dass +zur Laufzeit öfter mal Scripte neu geladen werden, gibt es hier kleine +Performance-Einbußen. + -Variante 1 startet einfach jeden Lx-Office Request als fcgi Prozess. Für sehr -große Installationen ist das die schnellste Version, benötigt aber sehr viel -Arbeitspseicher (ca. 2GB). +Es ist möglich die gleiche Lx-Office Version parallel unter cgi und fastcgi zu +betreiben. Dafür bleiben die Directorydirektiven wie oben beschrieben, die URLs +werden aber umgeleitet: -Variante 2 startet nur einen zentralen Dispatcher und lenkt alle Scripte auf -diesen. Dadurch dass zur Laufzeit öfter mal Scripte neu geladen werden gibt es -hier kleine Performance Einbußen. + # Zugriff über cgi + Alias /web/path/to/lx-office-erp /path/to/lx-office-erp + # Zugriff mit mod_fcgid: + AliasMatch ^/web/path/to/lx-office-erp-fcgid/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl + Alias /web/path/to/lx-office-erp-fcgid/ /path/to/lx-office-erp/ -=head2 Mögliche Fallstricke + # Zugriff mit mod_fastcgi: + AliasMatch ^/web/path/to/lx-office-erp-fastcgi/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fcgi + Alias /web/path/to/lx-office-erp-fastcgi/ /path/to/lx-office-erp/ -Die AddHandler Direktive vom Apache ist entgegen der Dokumentation -anscheinend nicht lokal auf das Verzeichnis beschränkt sondern global im -vhost. +Dann ist unter C die normale Version erreichbar, +und unter C bzw. +C die FastCGI Version. -Wenn Änderungen in der Konfiguration von Lx-Office gemacht werden, oder wenn -Templates editiert werden muss der Server neu gestartet werden. +=head2 Entwicklungsaspekte +Wenn Änderungen in der Konfiguration von Lx-Office gemacht werden, muss der +Webserver neu gestartet werden. +Bei der Entwicklung für FastCGI ist auf ein paar Fallstricke zu achten. Dadurch +dass das Programm in einer Endlosschleife läuft, müssen folgende Aspekte +geachtet werden: + +=head3 Programmende und Ausnahmen: C, C, C, C, C + +Fehler, die dass Programm normalerweise sofort beenden (fatale Fehler), werden +mit dem FastCGI Dispatcher abgefangen, um das Programm am Laufen zu halten. Man +kann mit C, C oder C Fehler ausgeben, die dann vom Dispatcher +angezeigt werden. Die Lx-Office eigene C<$::form->error()> tut im Prinzip das +Gleiche, mit ein paar Extraoptionen. C und C hingegen werden nicht +abgefangen. C wird direkt nach STDERR, also in Server Log eine Nachricht +schreiben (sofern in der Konfiguration nicht die Warnungen in das Lx-Office Log +umgeleitet wurden), und C wird die Ausführung beenden. + +Prinzipiell ist es kein Beinbruch, wenn sich der Prozess beendet, fcgi wird ihn +sofort neu starten. Allerdings sollte das die Ausnahme sein. Quintessenz: Bitte +kein C benutzen, alle anderen Exceptionmechanismen sind ok. + +=head3 Globale Variablen + +Um zu vermeiden, dass Informationen von einem Request in einen anderen gelangen, +müssen alle globalen Variablen vor einem Request sauber initialisiert werden. +Das ist besonders wichtig im C<$::cgi> und C<$::auth> Objekt, weil diese nicht +gelöscht werden pro Instanz, sondern persistent gehalten werden. + +In C gibt es einen sauber abgetrennten Block der alle +kanonischen globalen Variablen listet und erklärt. Bitte keine anderen +einführen ohne das sauber zu dokumentieren. + +Datenbankverbindungen wird noch ein Guide verfasst werden, wie man sicher geht, +dass man die richtige erwischt. =head2 Performance und Statistiken Die kritischen Pfade des Programms sind die Belegmasken, und unter diesen ganz besonders die Verkaufsrechnungsmaske. Ein Aufruf der Rechnungsmaske in -Lx-Office 2.4.3 stable dauert auf einem Core2duo mit 2GB Arbeitsspeicher und +Lx-Office 2.4.3 stable dauert auf einem Core2duo mit 4GB Arbeitsspeicher und Ubuntu 9.10 eine halbe Sekunde. In der 2.6.0 sind es je nach Menge der definierten Variablen 1-2s. Ab der Moose/Rose::DB Version sind es 5-6s. -Mit FastCGI ist die neuste Version auf 0,4 Sekunden selbst in den kritischen +Mit FastCGI ist die neuste Version auf 0,26 Sekunden selbst in den kritischen Pfaden, unter 0,15 sonst. =head2 Bekannte Probleme -Bei mehreren Benutzern scheint ab und zu eine Datenbankverbidung von Rose::DB -in den falschen Benutzer zu geraten. Das ist ein kritischer Bug und muss gefixt -werden. +=head3 Encoding Awareness + +UTF-8 kodierte Installationen sind sehr anfällig gegen fehlerhfate Encodings +unter FCGI. latin9 Installationen behandeln falsch kodierte Zeichen eher +unwissend, und geben sie einfach weiter. UTF-8 verweigert bei fehlerhaften +Programmpfaden kurzerhand das Ausliefern. Es wird noch daran gearbeitet, alle +Fehler da zu beseitigen. -Bei Administrativen Tätigkeiten werden in seltenen Fällen die Locales nicht -richtig geladen und die Maske erscheint in Englisch.