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  * Apache 2.2.11 (Ubuntu) und mod_fcgid:
  42
  43 Als Perl Backend wird das Modul FCGI.pm verwendet. Vorsicht: FCGI 0.69 und
  44 höher ist extrem strict in der Behandlung von Unicode, und verweigert bestimmte
  45 Eingaben von Lx-Office. Solange diese Probleme nicht behoben sind, muss auf die
  46 Vorgängerversion FCGI 0.68 ausgewichen werden.
  47
  48 Mit cpan lässt sie sich wie folgt installieren:
  49
  50  force install M/MS/MSTROUT/FCGI-0.68.tar.gz
  51
  52 =head2 Konfiguration des Webservers.
  53
  54 Bevor Sie versuchen eine Lx-Office Installation unter FCGI laufen zu lassen,
  55 empfliehlt es sich die Installation ersteinmal unter CGI aufzusetzen. FCGI
  56 macht es nicht einfach Fehler zu debuggen die beim ersten aufsetzen auftreten
  57 können. Sollte die Installation schon funktionieren, lesen Sie weiter.
  58
  59 Zuerst muss das FastCGI-Modul aktiviert werden. Dies kann unter
  60 Debian/Ubuntu z.B. mit folgendem Befehl geschehen:
  61
  62   a2enmod fastcgi
  63
  64 bzw.
  65
  66   a2enmod fcgid
  67
  68 Die Konfiguration für die Verwendung von Lx-Office mit FastCGI erfolgt
  69 durch Anpassung der vorhandenen Alias- und Directory-Direktiven. Dabei
  70 wird zwischen dem Installationspfad von Lx-Office im Dateisystem
  71 ("/path/to/lx-office-erp") und der URL unterschieden, unter der
  72 Lx-Office im Webbrowser erreichbar ist ("/web/path/to/lx-office-erp").
  73
  74 Folgendes Template funktioniert mit mod_fastcgi:
  75
  76   AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl
  77   Alias       /web/path/to/lx-office-erp/          /path/to/lx-office-erp/
  78
  79   <Directory /path/to/lx-office-erp>
  80     AllowOverride All
  81     AddHandler fastcgi-script .fpl
  82     Options ExecCGI Includes FollowSymlinks
  83     Order Allow,Deny
  84     Allow from All
  85   </Directory>
  86
  87   <DirectoryMatch /path/to/lx-office-erp/users>
  88     Order Deny,Allow
  89     Deny from All
  90   </DirectoryMatch>
  91
  92 ...und für mod_fcgid muss die erste Zeile geändert werden in:
  93
  94   AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fcgi
  95
  96
  97 Hierdurch wird nur ein zentraler Dispatcher gestartet. Alle Zugriffe
  98 auf die einzelnen Scripte werden auf diesen umgeleitet. Dadurch, dass
  99 zur Laufzeit öfter mal Scripte neu geladen werden, gibt es hier kleine
 100 Performance-Einbußen. Trotzdem ist diese Variante einer globalen
 101 Benutzung von "AddHandler fastcgi-script .pl" vorzuziehen.
 102
 103
 104 Es ist möglich die gleiche Lx-Office Version parallel unter cgi und fastcgi zu
 105 betreiben. Dafür bleiben Directorydirektiven bleiben wie oben beschrieben, die
 106 URLs werden aber umgeleitet:
 107
 108   # Zugriff ohne FastCGI
 109   Alias       /web/path/to/lx-office-erp                /path/to/lx-office-erp
 110
 111   # Zugriff mit FastCGI:
 112   AliasMatch ^/web/path/to/lx-office-erp-fcgi/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl
 113   Alias       /web/path/to/lx-office-erp-fcgi/          /path/to/lx-office-erp/
 114
 115 Dann ist unter C</web/path/to/lx-office-erp/> die normale Version erreichbar,
 116 und unter C</web/opath/to/lx-office-erp-fcgi/> die FastCGI Version.
 117
 118 Achtung:
 119
 120 Die AddHandler Direktive vom Apache ist entgegen der Dokumentation
 121 anscheinend nicht lokal auf das Verzeichnis beschränkt sondern global im
 122 vhost.
 123
 124 =head2 Entwicklungsaspekte
 125
 126 Wenn Änderungen in der Konfiguration von Lx-Office gemacht werden, muss der
 127 Server neu gestartet werden.
 128
 129 Bei der Entwicklung für FastCGI ist auf ein paar Fallstricke zu achten. Dadurch
 130 dass das Programm in einer Endlosschleife läuft, müssen folgende Aspekte
 131 geachtet werden:
 132
 133 =head3 Programmende und Ausnahmen: C<warn>, C<die>, C<exit>, C<carp>, C<confess>
 134
 135 Fehler, die dass Programm normalerweise sofort beenden (fatale Fehler), werden
 136 mit dem FastCGI Dispatcher abgefangen, um das Programm am Laufen zu halten. Man
 137 kann mit C<die>, C<confess> oder C<carp> Fehler ausgeben, die dann vom Dispatcher
 138 angezeigt werden. Die Lx-Office eigene C<$::form->error()> tut im Prinzip das
 139 Gleiche, mit ein paar Extraoptionen. C<warn> und C<exit> hingegen werden nicht
 140 abgefangen. C<warn> wird direkt nach STDERR, also in Server Log eine Nachricht
 141 schreiben (sofern in der Konfiguration nicht die Warnungen in das Lx-Office Log
 142 umgeleitet wurden), und C<exit> wird die Ausführung beenden.
 143
 144 Prinzipiell ist es kein Beinbruch, wenn sich der Prozess beendet, fcgi wird ihn
 145 sofort neu starten. Allerdings sollte das die Ausnahme sein. Quintessenz: Bitte
 146 kein C<exit> benutzen, alle anderen Exceptionmechanismen sind ok.
 147
 148 =head3 Globale Variablen
 149
 150 Um zu vermeiden, dass Informationen von einem Request in einen anderen gelangen,
 151 müssen alle globalen Variablen vor einem Request sauber initialisiert werden.
 152 Das ist besonders wichtig im C<$::cgi> und C<$::auth> Objekt, weil diese nicht
 153 gelöscht werden pro Instanz, sondern persistent gehalten werden.
 154
 155 In C<SL::Dispatcher> gibt es einen sauber abgetrennten Block der alle
 156 kanonischen globalen Variablen listet und erklärt. Bitte keine anderen
 157 einführen ohne das sauber zu dokumentieren.
 158
 159 Datenbankverbindungen wird noch ein Guide verfasst werden, wie man sichergeht,
 160 dass man die richtige erwischt.
 161
 162 =head2 Performance und Statistiken
 163
 164 Die kritischen Pfade des Programms sind die Belegmasken, und unter diesen ganz
 165 besonders die Verkaufsrechnungsmaske. Ein Aufruf der Rechnungsmaske in
 166 Lx-Office 2.4.3 stable dauert auf einem Core2duo mit 4GB Arbeitsspeicher und
 167 Ubuntu 9.10 eine halbe Sekunde. In der 2.6.0 sind es je nach Menge der
 168 definierten Variablen 1-2s. Ab der Moose/Rose::DB Version sind es 5-6s.
 169
 170 Mit FastCGI ist die neuste Version auf 0,26 Sekunden selbst in den kritischen
 171 Pfaden, unter 0,15 sonst.
 172
 173 =head2 Bekannte Probleme
 174
 175 =head3 Encoding Awareness
 176
 177 UTF-8 kodierte Installationen sind sehr anfällig gegen fehlerhfate Encodings
 178 unter FCGI. latin9 Installationen behandeln falsch kodierte Zeichen eher
 179 unwissend, und geben sie einfach weiter. UTF-8 verweigert bei fehlerhaften
 180 Programmpfaden kurzerhand aus ausliefern. Es wird noch daran gearbeitet alles
 181 Fehler da zu beseitigen.
 182