doc/INSTALL.fcgi

   1
   2 Diese Datei ist in Plain Old Documentation geschrieben. Mit
   3
   4 > perldoc INSTALL.fcgi
   5
   6 ist sie deutlich leichter zu lesen.
   7
   8 =head1 FastCGI für Lx-Office
   9
  10 =head2 Was ist FastCGI?
  11
  12 Direkt aus L<http://de.wikipedia.org/wiki/FastCGI> kopiert:
  13
  14   FastCGI ist ein Standard für die Einbindung externer Software zur Generierung
  15   dynamischer Webseiten in einem Webserver. FastCGI ist vergleichbar zum Common
  16   Gateway Interface (CGI), wurde jedoch entwickelt, um dessen
  17   Performance-Probleme zu umgehen.
  18
  19
  20 =head2 Warum FastCGI?
  21
  22 Perl Programme (wie Lx-Office eines ist) werden nicht statisch kompiliert.
  23 Stattdessen werden die Quelldateien bei jedem Start übersetzt, was bei kurzen
  24 Laufzeiten einen Großteil der Laufzeit ausmacht. Während SQL Ledger einen
  25 Großteil der Funktionalität in einzelne Module kapselt, um immer nur einen
  26 kleinen Teil laden zu müssen, ist die Funktionalität von Lx-Office soweit
  27 gewachsen, dass immer mehr Module auf den Rest des Programms zugreifen.
  28 Zusätzlich benutzen wir umfangreiche Bibliotheken um Funktionaltät nicht selber
  29 entwickeln zu müssen, die zusätzliche Ladezeit kosten. All dies führt dazu dass
  30 ein Lx-Office Aufruf der Kernmasken mittlerweile deutlich länger dauert als
  31 früher, und dass davon 90% für das Laden der Module verwendet wird.
  32
  33 Mit FastCGI werden nun die Module einmal geladen, und danach wird nur die
  34 eigentliche Programmlogik ausgeführt.
  35
  36 =head2 Kombinationen aus Webservern und Plugin.
  37
  38 Folgende Kombinationen sind getestet:
  39
  40  * Apache 2.2.11 (Ubuntu) und mod_fastcgi.
  41
  42 Folgende Kombinationen funktionieren nicht:
  43
  44  * Apache 2.2.11 (Ubuntu) + mod_fcgid:
  45
  46 Als Perl Backend wird das Modul FCGI.pm verwendet. Vorsicht: FCGI 0.69 und
  47 höher ist extrem strict in der Behandlung von Unicode, und verweigert bestimmte
  48 Eingaben von Lx-Office. Solange diese Probleme nicht behoben sind, muss auf die
  49 Vorgängerversion FCGI 0.68 ausgewichen werden.
  50
  51
  52 =head2 Konfiguration des Webservers.
  53
  54 Zuerst muss das FastCGI-Modul aktiviert werden. Dies kann unter
  55 Debian/Ubuntu z.B. mit folgendem Befehl geschehen:
  56
  57   a2enmod fastcgi
  58
  59 Die Konfiguration für die Verwendung von Lx-Office mit FastCGI erfolgt
  60 durch Anpassung der vorhandenen Alias- und Directory-Direktiven. Dabei
  61 wird zwischen dem Installationspfad von Lx-Office im Dateisystem
  62 ("/path/to/lx-office-erp") und der URL unterschieden, unter der
  63 Lx-Office im Webbrowser erreichbar ist ("/web/path/to/lx-office-erp").
  64
  65   AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl
  66
  67   <Directory /path/to/lx-office-erp>
  68     AllowOverride All
  69     AddHandler fastcgi-script .fpl
  70     Options ExecCGI Includes FollowSymlinks
  71     Order Allow,Deny
  72     Allow from All
  73   </Directory>
  74
  75   <DirectoryMatch /path/to/lx-office-erp/users>
  76     Order Deny,Allow
  77     Deny from All
  78   </DirectoryMatch>
  79
  80 Hierdurch wird nur ein zentraler Dispatcher gestartet. Alle Zugriffe
  81 auf die einzelnen Scripte werden auf diesen umgeleitet. Dadurch, dass
  82 zur Laufzeit öfter mal Scripte neu geladen werden, gibt es hier kleine
  83 Performance-Einbußen. Trotzdem ist diese Variante einer globalen
  84 Benutzung von "AddHandler fastcgi-script .pl" vorzuziehen.
  85
  86
  87 =head2 Entwicklungsaspekte
  88
  89 Die AddHandler Direktive vom Apache ist entgegen der Dokumentation
  90 anscheinend nicht lokal auf das Verzeichnis beschränkt sondern global im
  91 vhost.
  92
  93 Wenn Änderungen in der Konfiguration von Lx-Office gemacht werden, oder wenn
  94 Templates editiert werden muss der Server neu gestartet werden.
  95
  96 Es ist möglich die gleiche Lx-Office Version parallel unter cgi und fastcgi zu
  97 betreiben. Da nimmt man Variante 2 wie oben beschrieben, und ändert die
  98 AliasMatch Zeile auf eine andere URL, und lässt alle anderen URLs auch
  99 weiterleiten:
 100
 101   # Zugriff ohne FastCGI
 102   Alias /web/path/to/lx-office-erp /path/to/lx-office-erp
 103
 104   # Zugriff mit FastCGI:
 105   AliasMatch ^/web/path/to/lx-office-erp-fcgi/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl
 106   Alias       /web/path/to/lx-office-erp-fcgi/          /path/to/lx-office-erp/
 107
 108 Dann ist unter C</web/path/to/lx-office-erp/> die normale Version erreichbar,
 109 und unter C</web/opath/to/lx-office-erp-fcgi/> die FastCGI Version.
 110
 111 Bei der Entwicklung für FastCGI ist auf ein paar Fallstricke zu achten. Dadurch
 112 dass das Programm in einer Endlosschleife läuft, müssen folgende Aspekte
 113 geachtet werden:
 114
 115 =head3 Programmende und Ausnahmen: C<warn>, C<die>, C<exit>, C<carp>, C<confess>
 116
 117 Fehler, die dass Programm normalerweise sofort beenden (fatale Fehler), werden
 118 mit dem FastCGI Dispatcher abgefangen, um das Programm am Laufen zu halten. Man
 119 kann mit C<die>, C<confess> oder C<carp> Fehler ausgeben, die dann vom Dispatcher
 120 angezeigt werden. Die Lx-Office eigene C<$::form->error()> tut im Prinzip das
 121 Gleiche, mit ein paar Extraoptionen. C<warn> und C<exit> hingegen werden nicht
 122 abgefangen. C<warn> wird direkt nach STDERR, also in Server Log eine Nachricht
 123 schreiben, und C<exit> wird die Ausführung beenden.
 124
 125 Prinzipiell ist es kein Beinbruch, wenn sich der Prozess beendet, fcgi wird ihn
 126 sofort neu starten. Allerdings sollte das die Ausnahme sein. Quintessenz: Bitte
 127 kein C<warn> oder C<exit> benutzen, alle anderen Exceptionmechanismen sind ok.
 128
 129 =head3 Globale Variablen
 130
 131 Um zu vermeiden, dass Informationen von einem Request in einen anderen gelangen,
 132 müssen alle globalen Variablen vor einem Request sauber initialisiert werden.
 133 Das ist besonders wichtig im C<$::cgi> und C<$::auth> Objekt, weil diese nicht
 134 gelöscht werden pro Instanz, sondern persistent gehalten werden.
 135
 136 Datenbankverbindungen wird noch ein Guide verfasst werden, wie man sichergeht,
 137 dass man die richtige erwischt.
 138
 139 =head2 Performance und Statistiken
 140
 141 Die kritischen Pfade des Programms sind die Belegmasken, und unter diesen ganz
 142 besonders die Verkaufsrechnungsmaske. Ein Aufruf der Rechnungsmaske in
 143 Lx-Office 2.4.3 stable dauert auf einem Core2duo mit 2GB Arbeitsspeicher und
 144 Ubuntu 9.10 eine halbe Sekunde. In der 2.6.0 sind es je nach Menge der
 145 definierten Variablen 1-2s. Ab der Moose/Rose::DB Version sind es 5-6s.
 146
 147 Mit FastCGI ist die neuste Version auf 0,4 Sekunden selbst in den kritischen
 148 Pfaden, unter 0,15 sonst.
 149
 150 =head2 Bekannte Probleme
 151