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 =encoding utf8
   9
  10 =head1 FastCGI für Lx-Office
  11
  12 =head2 Was ist FastCGI?
  13
  14 Direkt aus L<http://de.wikipedia.org/wiki/FastCGI> kopiert:
  15
  16   FastCGI ist ein Standard für die Einbindung externer Software zur Generierung
  17   dynamischer Webseiten in einem Webserver. FastCGI ist vergleichbar zum Common
  18   Gateway Interface (CGI), wurde jedoch entwickelt, um dessen
  19   Performance-Probleme zu umgehen.
  20
  21
  22 =head2 Warum FastCGI?
  23
  24 Perl Programme (wie Lx-Office eines ist) werden nicht statisch kompiliert.
  25 Stattdessen werden die Quelldateien bei jedem Start übersetzt, was bei kurzen
  26 Laufzeiten einen Großteil der Laufzeit ausmacht. Während SQL Ledger einen
  27 Großteil der Funktionalität in einzelne Module kapselt, um immer nur einen
  28 kleinen Teil laden zu müssen, ist die Funktionalität von Lx-Office soweit
  29 gewachsen, dass immer mehr Module auf den Rest des Programms zugreifen.
  30 Zusätzlich benutzen wir umfangreiche Bibliotheken um Funktionaltät nicht selber
  31 entwickeln zu müssen, die zusätzliche Ladezeit kosten. All dies führt dazu dass
  32 ein Lx-Office Aufruf der Kernmasken mittlerweile deutlich länger dauert als
  33 früher, und dass davon 90% für das Laden der Module verwendet wird.
  34
  35 Mit FastCGI werden nun die Module einmal geladen, und danach wird nur die
  36 eigentliche Programmlogik ausgeführt.
  37
  38 =head2 Kombinationen aus Webservern und Plugin.
  39
  40 Folgende Kombinationen sind getestet:
  41
  42  * Apache 2.2.11 (Ubuntu) und mod_fcgid.
  43  * Apache 2.2.11 (Ubuntu) und mod_fastcgi.
  44
  45 Als Perl Backend wird das Modul FCGI.pm verwendet. Vorsicht: FCGI 0.69 und
  46 höher ist extrem strict in der Behandlung von Unicode, und verweigert bestimmte
  47 Eingaben von Lx-Office. Solange diese Probleme nicht behoben sind, muss auf die
  48 Vorgängerversion FCGI 0.68 ausgewichen werden.
  49
  50 Mit cpan lässt sie sich wie folgt installieren:
  51
  52  force install M/MS/MSTROUT/FCGI-0.68.tar.gz
  53
  54 =head2 Konfiguration des Webservers.
  55
  56 Bevor Sie versuchen eine Lx-Office Installation unter FCGI laufen zu lassen,
  57 empfliehlt es sich die Installation ersteinmal unter CGI aufzusetzen. FCGI
  58 macht es nicht einfach Fehler zu debuggen die beim ersten aufsetzen auftreten
  59 können. Sollte die Installation schon funktionieren, lesen Sie weiter.
  60
  61 Zuerst muss das FastCGI-Modul aktiviert werden. Dies kann unter
  62 Debian/Ubuntu z.B. mit folgendem Befehl geschehen:
  63
  64   a2enmod fcgid
  65
  66 bzw.
  67
  68   a2enmod fastcgi
  69
  70 Die Konfiguration für die Verwendung von Lx-Office mit FastCGI erfolgt
  71 durch Anpassung der vorhandenen Alias- und Directory-Direktiven. Dabei
  72 wird zwischen dem Installationspfad von Lx-Office im Dateisystem
  73 ("/path/to/lx-office-erp") und der URL unterschieden, unter der
  74 Lx-Office im Webbrowser erreichbar ist ("/web/path/to/lx-office-erp").
  75
  76 Folgendes Template funktioniert mit mod_fcgid:
  77
  78   AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fcgi
  79   Alias       /web/path/to/lx-office-erp/          /path/to/lx-office-erp/
  80
  81   <Directory /path/to/lx-office-erp>
  82     AllowOverride All
  83     Options ExecCGI Includes FollowSymlinks
  84     Order Allow,Deny
  85     Allow from All
  86   </Directory>
  87
  88   <DirectoryMatch /path/to/lx-office-erp/users>
  89     Order Deny,Allow
  90     Deny from All
  91   </DirectoryMatch>
  92
  93 Für mod_fastcgi muss ein AddHandler ergänzt werden und die erste Zeile geändert werden:
  94
  95   AddHandler fastcgi-script .fpl
  96   AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl
  97
  98 Seit mod_fcgid-Version 2.6.3 gelten sehr kleine Grenzen für die
  99 maximale Größe eines Requests. Diese sollte wie folgt hochgesetzt werden:
 100
 101   FcgidMaxRequestLen 10485760
 102
 103 Das ganze sollte dann so aussehen:
 104
 105   AddHandler fastcgi-script .fpl
 106   AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl
 107   Alias       /web/path/to/lx-office-erp/          /path/to/lx-office-erp/
 108   FcgidMaxRequestLen 10485760
 109
 110   <Directory /path/to/lx-office-erp>
 111     AllowOverride All
 112     Options ExecCGI Includes FollowSymlinks
 113     Order Allow,Deny
 114     Allow from All
 115   </Directory>
 116
 117   <DirectoryMatch /path/to/lx-office-erp/users>
 118     Order Deny,Allow
 119     Deny from All
 120   </DirectoryMatch>
 121
 122 Hierdurch wird nur ein zentraler Dispatcher gestartet. Alle Zugriffe
 123 auf die einzelnen Scripte werden auf diesen umgeleitet. Dadurch, dass
 124 zur Laufzeit öfter mal Scripte neu geladen werden, gibt es hier kleine
 125 Performance-Einbußen. Trotzdem ist diese Variante einer globalen
 126 Benutzung von "AddHandler fastcgi-script .pl" vorzuziehen.
 127
 128
 129 Es ist möglich die gleiche Lx-Office Version parallel unter cgi und fastcgi zu
 130 betreiben. Dafür bleiben die Directorydirektiven wie oben beschrieben, die URLs
 131 werden aber umgeleitet:
 132
 133   # Zugriff über cgi
 134   Alias       /web/path/to/lx-office-erp                /path/to/lx-office-erp
 135
 136   # Zugriff mit mod_fcgid:
 137   AliasMatch ^/web/path/to/lx-office-erp-fcgid/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fcgi
 138   Alias       /web/path/to/lx-office-erp-fcgid/          /path/to/lx-office-erp/
 139
 140   # Zugriff mit mod_fastcgi:
 141   AliasMatch ^/web/path/to/lx-office-erp-fastcgi/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl
 142   Alias       /web/path/to/lx-office-erp-fastcgi/          /path/to/lx-office-erp/
 143
 144 Dann ist unter C</web/path/to/lx-office-erp/> die normale Version erreichbar,
 145 und unter C</web/path/to/lx-office-erp-fcgid/> bzw.
 146 C</web/path/to/lx-office-erp-fastcgi/> die FastCGI Version.
 147
 148 Achtung:
 149
 150 Die AddHandler Direktive vom Apache ist entgegen der Dokumentation
 151 anscheinend nicht lokal auf das Verzeichnis beschränkt sondern global im
 152 vhost.
 153
 154 =head2 Entwicklungsaspekte
 155
 156 Wenn Änderungen in der Konfiguration von Lx-Office gemacht werden, muss der
 157 Webserver neu gestartet werden.
 158
 159 Bei der Entwicklung für FastCGI ist auf ein paar Fallstricke zu achten. Dadurch
 160 dass das Programm in einer Endlosschleife läuft, müssen folgende Aspekte
 161 geachtet werden:
 162
 163 =head3 Programmende und Ausnahmen: C<warn>, C<die>, C<exit>, C<carp>, C<confess>
 164
 165 Fehler, die dass Programm normalerweise sofort beenden (fatale Fehler), werden
 166 mit dem FastCGI Dispatcher abgefangen, um das Programm am Laufen zu halten. Man
 167 kann mit C<die>, C<confess> oder C<carp> Fehler ausgeben, die dann vom Dispatcher
 168 angezeigt werden. Die Lx-Office eigene C<$::form->error()> tut im Prinzip das
 169 Gleiche, mit ein paar Extraoptionen. C<warn> und C<exit> hingegen werden nicht
 170 abgefangen. C<warn> wird direkt nach STDERR, also in Server Log eine Nachricht
 171 schreiben (sofern in der Konfiguration nicht die Warnungen in das Lx-Office Log
 172 umgeleitet wurden), und C<exit> wird die Ausführung beenden.
 173
 174 Prinzipiell ist es kein Beinbruch, wenn sich der Prozess beendet, fcgi wird ihn
 175 sofort neu starten. Allerdings sollte das die Ausnahme sein. Quintessenz: Bitte
 176 kein C<exit> benutzen, alle anderen Exceptionmechanismen sind ok.
 177
 178 =head3 Globale Variablen
 179
 180 Um zu vermeiden, dass Informationen von einem Request in einen anderen gelangen,
 181 müssen alle globalen Variablen vor einem Request sauber initialisiert werden.
 182 Das ist besonders wichtig im C<$::cgi> und C<$::auth> Objekt, weil diese nicht
 183 gelöscht werden pro Instanz, sondern persistent gehalten werden.
 184
 185 In C<SL::Dispatcher> gibt es einen sauber abgetrennten Block der alle
 186 kanonischen globalen Variablen listet und erklärt. Bitte keine anderen
 187 einführen ohne das sauber zu dokumentieren.
 188
 189 Datenbankverbindungen wird noch ein Guide verfasst werden, wie man sicher geht,
 190 dass man die richtige erwischt.
 191
 192 =head2 Performance und Statistiken
 193
 194 Die kritischen Pfade des Programms sind die Belegmasken, und unter diesen ganz
 195 besonders die Verkaufsrechnungsmaske. Ein Aufruf der Rechnungsmaske in
 196 Lx-Office 2.4.3 stable dauert auf einem Core2duo mit 4GB Arbeitsspeicher und
 197 Ubuntu 9.10 eine halbe Sekunde. In der 2.6.0 sind es je nach Menge der
 198 definierten Variablen 1-2s. Ab der Moose/Rose::DB Version sind es 5-6s.
 199
 200 Mit FastCGI ist die neuste Version auf 0,26 Sekunden selbst in den kritischen
 201 Pfaden, unter 0,15 sonst.
 202
 203 =head2 Bekannte Probleme
 204
 205 =head3 Encoding Awareness
 206
 207 UTF-8 kodierte Installationen sind sehr anfällig gegen fehlerhfate Encodings
 208 unter FCGI. latin9 Installationen behandeln falsch kodierte Zeichen eher
 209 unwissend, und geben sie einfach weiter. UTF-8 verweigert bei fehlerhaften
 210 Programmpfaden kurzerhand aus ausliefern. Es wird noch daran gearbeitet alles
 211 Fehler da zu beseitigen.
 212