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