kivitendo/doc/INSTALL.fcgi @ e08d28e4
| 5585180a | Sven Schöling | |||
| a07567c2 | Sven Schöling | Diese Datei ist in Plain Old Documentation geschrieben. Mit
|
||
| 5585180a | Sven Schöling | |||
| a07567c2 | Sven Schöling | > perldoc INSTALL.fcgi
|
||
| 5585180a | Sven Schöling | |||
| a07567c2 | Sven Schöling | ist sie deutlich leichter zu lesen.
|
||
| 5585180a | Sven Schöling | |||
| 299b2a4b | Sven Schöling | =encoding utf8
|
||
| 05c6840d | Moritz Bunkus | =head1 FastCGI für Lx-Office
|
||
| a07567c2 | Sven Schöling | |||
=head2 Was ist FastCGI?
|
||||
Direkt aus L<http://de.wikipedia.org/wiki/FastCGI> kopiert:
|
||||
| 05c6840d | Moritz Bunkus | FastCGI ist ein Standard für die Einbindung externer Software zur Generierung
|
||
| a07567c2 | Sven Schöling | dynamischer Webseiten in einem Webserver. FastCGI ist vergleichbar zum Common
|
||
Gateway Interface (CGI), wurde jedoch entwickelt, um dessen
|
||||
Performance-Probleme zu umgehen.
|
||||
=head2 Warum FastCGI?
|
||||
Perl Programme (wie Lx-Office eines ist) werden nicht statisch kompiliert.
|
||||
| 05c6840d | Moritz Bunkus | 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
|
||||
| a07567c2 | Sven Schöling | gewachsen, dass immer mehr Module auf den Rest des Programms zugreifen.
|
||
| 05c6840d | Moritz Bunkus | 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.
|
||||
| a07567c2 | Sven Schöling | |||
Mit FastCGI werden nun die Module einmal geladen, und danach wird nur die
|
||||
| 05c6840d | Moritz Bunkus | eigentliche Programmlogik ausgeführt.
|
||
| a07567c2 | Sven Schöling | |||
=head2 Kombinationen aus Webservern und Plugin.
|
||||
| 5585180a | Sven Schöling | |||
Folgende Kombinationen sind getestet:
|
||||
| 4d733eed | Sven Schöling | * Apache 2.2.11 (Ubuntu) und mod_fcgid.
|
||
| a07567c2 | Sven Schöling | * Apache 2.2.11 (Ubuntu) und mod_fastcgi.
|
||
| 5585180a | Sven Schöling | |||
| 24b6b41b | Sven Schöling | Als Perl Backend wird das Modul FCGI.pm verwendet. Vorsicht: FCGI 0.69 und
|
||
| 05c6840d | Moritz Bunkus | höher ist extrem strict in der Behandlung von Unicode, und verweigert bestimmte
|
||
| 24b6b41b | Sven Schöling | Eingaben von Lx-Office. Solange diese Probleme nicht behoben sind, muss auf die
|
||
| 05c6840d | Moritz Bunkus | Vorgängerversion FCGI 0.68 ausgewichen werden.
|
||
| 5585180a | Sven Schöling | |||
| 05c6840d | Moritz Bunkus | Mit cpan lässt sie sich wie folgt installieren:
|
||
| 19f96ce5 | Sven Schöling | |||
force install M/MS/MSTROUT/FCGI-0.68.tar.gz
|
||||
| 5585180a | Sven Schöling | |||
| a07567c2 | Sven Schöling | =head2 Konfiguration des Webservers.
|
||
| 5585180a | Sven Schöling | |||
| 19f96ce5 | Sven Schöling | 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
|
||||
| 05c6840d | Moritz Bunkus | können. Sollte die Installation schon funktionieren, lesen Sie weiter.
|
||
| 19f96ce5 | Sven Schöling | |||
| 5bf5df39 | Moritz Bunkus | Zuerst muss das FastCGI-Modul aktiviert werden. Dies kann unter
|
||
Debian/Ubuntu z.B. mit folgendem Befehl geschehen:
|
||||
| 5585180a | Sven Schöling | |||
| 4d733eed | Sven Schöling | a2enmod fcgid
|
||
| 5585180a | Sven Schöling | |||
| e1d7dc46 | Sven Schöling | bzw.
|
||
| 4d733eed | Sven Schöling | a2enmod fastcgi
|
||
| e1d7dc46 | Sven Schöling | |||
| 05c6840d | Moritz Bunkus | Die Konfiguration für die Verwendung von Lx-Office mit FastCGI erfolgt
|
||
| 5bf5df39 | Moritz Bunkus | 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").
|
||||
| 5585180a | Sven Schöling | |||
| 4d733eed | Sven Schöling | Folgendes Template funktioniert mit mod_fcgid:
|
||
| e1d7dc46 | Sven Schöling | |||
| 4d733eed | Sven Schöling | AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fcgi
|
||
| e1d7dc46 | Sven Schöling | Alias /web/path/to/lx-office-erp/ /path/to/lx-office-erp/
|
||
| a07567c2 | Sven Schöling | |||
<Directory /path/to/lx-office-erp>
|
||||
AllowOverride All
|
||||
Options ExecCGI Includes FollowSymlinks
|
||||
Order Allow,Deny
|
||||
Allow from All
|
||||
</Directory>
|
||||
| 2e9d34aa | Moritz Bunkus | <DirectoryMatch /path/to/lx-office-erp/users>
|
||
| a07567c2 | Sven Schöling | Order Deny,Allow
|
||
Deny from All
|
||||
</DirectoryMatch>
|
||||
| cff55be2 | Sven Schöling | Für mod_fastcgi muss ein AddHandler ergänzt werden und die erste Zeile geändert werden:
|
||
| e1d7dc46 | Sven Schöling | |||
| cff55be2 | Sven Schöling | AddHandler fastcgi-script .fpl
|
||
| 4d733eed | Sven Schöling | AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl
|
||
| e1d7dc46 | Sven Schöling | |||
| cff55be2 | Sven Schöling | Das ganze sollte dann so aussehen:
|
||
AddHandler fastcgi-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/
|
||||
<Directory /path/to/lx-office-erp>
|
||||
AllowOverride All
|
||||
Options ExecCGI Includes FollowSymlinks
|
||||
Order Allow,Deny
|
||||
Allow from All
|
||||
</Directory>
|
||||
<DirectoryMatch /path/to/lx-office-erp/users>
|
||||
Order Deny,Allow
|
||||
Deny from All
|
||||
</DirectoryMatch>
|
||||
| e1d7dc46 | Sven Schöling | |||
| 5bf5df39 | Moritz Bunkus | Hierdurch wird nur ein zentraler Dispatcher gestartet. Alle Zugriffe
|
||
auf die einzelnen Scripte werden auf diesen umgeleitet. Dadurch, dass
|
||||
| 05c6840d | Moritz Bunkus | zur Laufzeit öfter mal Scripte neu geladen werden, gibt es hier kleine
|
||
Performance-Einbußen. Trotzdem ist diese Variante einer globalen
|
||||
| 5bf5df39 | Moritz Bunkus | Benutzung von "AddHandler fastcgi-script .pl" vorzuziehen.
|
||
| a07567c2 | Sven Schöling | |||
| 5585180a | Sven Schöling | |||
| 05c6840d | Moritz Bunkus | Es ist möglich die gleiche Lx-Office Version parallel unter cgi und fastcgi zu
|
||
| cff55be2 | Sven Schöling | betreiben. Dafür bleiben die Directorydirektiven wie oben beschrieben, die URLs
|
||
werden aber umgeleitet:
|
||||
| 5585180a | Sven Schöling | |||
| cff55be2 | Sven Schöling | # Zugriff über cgi
|
||
| e1d7dc46 | Sven Schöling | Alias /web/path/to/lx-office-erp /path/to/lx-office-erp
|
||
| 5585180a | Sven Schöling | |||
| e3d06081 | Sven Donath | # Zugriff mit mod_fcgid:
|
||
| cff55be2 | Sven Schöling | AliasMatch ^/web/path/to/lx-office-erp-fcgid/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fcgi
|
||
Alias /web/path/to/lx-office-erp-fcgid/ /path/to/lx-office-erp/
|
||||
# Zugriff mit mod_fastcgi:
|
||||
AliasMatch ^/web/path/to/lx-office-erp-fastcgi/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl
|
||||
Alias /web/path/to/lx-office-erp-fastcgi/ /path/to/lx-office-erp/
|
||||
| 63a90446 | Sven Schöling | |||
Dann ist unter C</web/path/to/lx-office-erp/> die normale Version erreichbar,
|
||||
| 22ce5b07 | Sven Donath | und unter C</web/path/to/lx-office-erp-fcgid/> bzw.
|
||
C</web/path/to/lx-office-erp-fastcgi/> die FastCGI Version.
|
||||
| 63a90446 | Sven Schöling | |||
| e1d7dc46 | Sven Schöling | Achtung:
|
||
Die AddHandler Direktive vom Apache ist entgegen der Dokumentation
|
||||
| 05c6840d | Moritz Bunkus | anscheinend nicht lokal auf das Verzeichnis beschränkt sondern global im
|
||
| e1d7dc46 | Sven Schöling | vhost.
|
||
=head2 Entwicklungsaspekte
|
||||
| 05c6840d | Moritz Bunkus | Wenn Änderungen in der Konfiguration von Lx-Office gemacht werden, muss der
|
||
| 22ce5b07 | Sven Donath | Webserver neu gestartet werden.
|
||
| e1d7dc46 | Sven Schöling | |||
| 05c6840d | Moritz Bunkus | 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
|
||||
| 63a90446 | Sven Schöling | geachtet werden:
|
||
| 2e9d34aa | Moritz Bunkus | =head3 Programmende und Ausnahmen: C<warn>, C<die>, C<exit>, C<carp>, C<confess>
|
||
| 63a90446 | Sven Schöling | |||
| 2e9d34aa | Moritz Bunkus | Fehler, die dass Programm normalerweise sofort beenden (fatale Fehler), werden
|
||
mit dem FastCGI Dispatcher abgefangen, um das Programm am Laufen zu halten. Man
|
||||
| 63a90446 | Sven Schöling | kann mit C<die>, C<confess> oder C<carp> 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<warn> und C<exit> hingegen werden nicht
|
||||
abgefangen. C<warn> wird direkt nach STDERR, also in Server Log eine Nachricht
|
||||
| e1d7dc46 | Sven Schöling | schreiben (sofern in der Konfiguration nicht die Warnungen in das Lx-Office Log
|
||
| 05c6840d | Moritz Bunkus | umgeleitet wurden), und C<exit> wird die Ausführung beenden.
|
||
| 63a90446 | Sven Schöling | |||
| 2e9d34aa | Moritz Bunkus | Prinzipiell ist es kein Beinbruch, wenn sich der Prozess beendet, fcgi wird ihn
|
||
sofort neu starten. Allerdings sollte das die Ausnahme sein. Quintessenz: Bitte
|
||||
| e1d7dc46 | Sven Schöling | kein C<exit> benutzen, alle anderen Exceptionmechanismen sind ok.
|
||
| 63a90446 | Sven Schöling | |||
=head3 Globale Variablen
|
||||
| 2e9d34aa | Moritz Bunkus | Um zu vermeiden, dass Informationen von einem Request in einen anderen gelangen,
|
||
| 05c6840d | Moritz Bunkus | müssen alle globalen Variablen vor einem Request sauber initialisiert werden.
|
||
| 63a90446 | Sven Schöling | Das ist besonders wichtig im C<$::cgi> und C<$::auth> Objekt, weil diese nicht
|
||
| 05c6840d | Moritz Bunkus | gelöscht werden pro Instanz, sondern persistent gehalten werden.
|
||
| 63a90446 | Sven Schöling | |||
| e1d7dc46 | Sven Schöling | In C<SL::Dispatcher> gibt es einen sauber abgetrennten Block der alle
|
||
| 05c6840d | Moritz Bunkus | kanonischen globalen Variablen listet und erklärt. Bitte keine anderen
|
||
einführen ohne das sauber zu dokumentieren.
|
||||
| e1d7dc46 | Sven Schöling | |||
| 22ce5b07 | Sven Donath | Datenbankverbindungen wird noch ein Guide verfasst werden, wie man sicher geht,
|
||
| 63a90446 | Sven Schöling | dass man die richtige erwischt.
|
||
| a07567c2 | Sven Schöling | =head2 Performance und Statistiken
|
||
| 5585180a | Sven Schöling | |||
| a07567c2 | Sven Schöling | Die kritischen Pfade des Programms sind die Belegmasken, und unter diesen ganz
|
||
besonders die Verkaufsrechnungsmaske. Ein Aufruf der Rechnungsmaske in
|
||||
| e1d7dc46 | Sven Schöling | Lx-Office 2.4.3 stable dauert auf einem Core2duo mit 4GB Arbeitsspeicher und
|
||
| a07567c2 | Sven Schöling | 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.
|
||||
| f805c9a2 | Moritz Bunkus | |||
| e1d7dc46 | Sven Schöling | Mit FastCGI ist die neuste Version auf 0,26 Sekunden selbst in den kritischen
|
||
| a07567c2 | Sven Schöling | Pfaden, unter 0,15 sonst.
|
||
| f805c9a2 | Moritz Bunkus | |||
| a07567c2 | Sven Schöling | =head2 Bekannte Probleme
|
||
| f805c9a2 | Moritz Bunkus | |||
| e1d7dc46 | Sven Schöling | =head3 Encoding Awareness
|
||
| 05c6840d | Moritz Bunkus | UTF-8 kodierte Installationen sind sehr anfällig gegen fehlerhfate Encodings
|
||
| e1d7dc46 | Sven Schöling | unter FCGI. latin9 Installationen behandeln falsch kodierte Zeichen eher
|
||
unwissend, und geben sie einfach weiter. UTF-8 verweigert bei fehlerhaften
|
||||
Programmpfaden kurzerhand aus ausliefern. Es wird noch daran gearbeitet alles
|
||||
Fehler da zu beseitigen.
|