Merge branch 'master' of lx-office.linet-services.de:lx-office-erp
[kivitendo-erp.git] / 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 Das ganze sollte dann so aussehen:
99
100   AddHandler fastcgi-script .fpl
101   AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl
102   Alias       /web/path/to/lx-office-erp/          /path/to/lx-office-erp/
103
104   <Directory /path/to/lx-office-erp>
105     AllowOverride All
106     Options ExecCGI Includes FollowSymlinks
107     Order Allow,Deny
108     Allow from All
109   </Directory>
110
111   <DirectoryMatch /path/to/lx-office-erp/users>
112     Order Deny,Allow
113     Deny from All
114   </DirectoryMatch>
115
116 Hierdurch wird nur ein zentraler Dispatcher gestartet. Alle Zugriffe
117 auf die einzelnen Scripte werden auf diesen umgeleitet. Dadurch, dass
118 zur Laufzeit öfter mal Scripte neu geladen werden, gibt es hier kleine
119 Performance-Einbußen. Trotzdem ist diese Variante einer globalen
120 Benutzung von "AddHandler fastcgi-script .pl" vorzuziehen.
121
122
123 Es ist möglich die gleiche Lx-Office Version parallel unter cgi und fastcgi zu
124 betreiben. Dafür bleiben die Directorydirektiven wie oben beschrieben, die URLs
125 werden aber umgeleitet:
126
127   # Zugriff über cgi
128   Alias       /web/path/to/lx-office-erp                /path/to/lx-office-erp
129
130   # Zugriff mit mod_fcgid:
131   AliasMatch ^/web/path/to/lx-office-erp-fcgid/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fcgi
132   Alias       /web/path/to/lx-office-erp-fcgid/          /path/to/lx-office-erp/
133
134   # Zugriff mit mod_fastcgi:
135   AliasMatch ^/web/path/to/lx-office-erp-fastcgi/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl
136   Alias       /web/path/to/lx-office-erp-fastcgi/          /path/to/lx-office-erp/
137
138 Dann ist unter C</web/path/to/lx-office-erp/> die normale Version erreichbar,
139 und unter C</web/path/to/lx-office-erp-fcgid/> bzw.
140 C</web/path/to/lx-office-erp-fastcgi/> die FastCGI Version.
141
142 Achtung:
143
144 Die AddHandler Direktive vom Apache ist entgegen der Dokumentation
145 anscheinend nicht lokal auf das Verzeichnis beschränkt sondern global im
146 vhost.
147
148 =head2 Entwicklungsaspekte
149
150 Wenn Änderungen in der Konfiguration von Lx-Office gemacht werden, muss der
151 Webserver neu gestartet werden.
152
153 Bei der Entwicklung für FastCGI ist auf ein paar Fallstricke zu achten. Dadurch
154 dass das Programm in einer Endlosschleife läuft, müssen folgende Aspekte
155 geachtet werden:
156
157 =head3 Programmende und Ausnahmen: C<warn>, C<die>, C<exit>, C<carp>, C<confess>
158
159 Fehler, die dass Programm normalerweise sofort beenden (fatale Fehler), werden
160 mit dem FastCGI Dispatcher abgefangen, um das Programm am Laufen zu halten. Man
161 kann mit C<die>, C<confess> oder C<carp> Fehler ausgeben, die dann vom Dispatcher
162 angezeigt werden. Die Lx-Office eigene C<$::form->error()> tut im Prinzip das
163 Gleiche, mit ein paar Extraoptionen. C<warn> und C<exit> hingegen werden nicht
164 abgefangen. C<warn> wird direkt nach STDERR, also in Server Log eine Nachricht
165 schreiben (sofern in der Konfiguration nicht die Warnungen in das Lx-Office Log
166 umgeleitet wurden), und C<exit> wird die Ausführung beenden.
167
168 Prinzipiell ist es kein Beinbruch, wenn sich der Prozess beendet, fcgi wird ihn
169 sofort neu starten. Allerdings sollte das die Ausnahme sein. Quintessenz: Bitte
170 kein C<exit> benutzen, alle anderen Exceptionmechanismen sind ok.
171
172 =head3 Globale Variablen
173
174 Um zu vermeiden, dass Informationen von einem Request in einen anderen gelangen,
175 müssen alle globalen Variablen vor einem Request sauber initialisiert werden.
176 Das ist besonders wichtig im C<$::cgi> und C<$::auth> Objekt, weil diese nicht
177 gelöscht werden pro Instanz, sondern persistent gehalten werden.
178
179 In C<SL::Dispatcher> gibt es einen sauber abgetrennten Block der alle
180 kanonischen globalen Variablen listet und erklärt. Bitte keine anderen
181 einführen ohne das sauber zu dokumentieren.
182
183 Datenbankverbindungen wird noch ein Guide verfasst werden, wie man sicher geht,
184 dass man die richtige erwischt.
185
186 =head2 Performance und Statistiken
187
188 Die kritischen Pfade des Programms sind die Belegmasken, und unter diesen ganz
189 besonders die Verkaufsrechnungsmaske. Ein Aufruf der Rechnungsmaske in
190 Lx-Office 2.4.3 stable dauert auf einem Core2duo mit 4GB Arbeitsspeicher und
191 Ubuntu 9.10 eine halbe Sekunde. In der 2.6.0 sind es je nach Menge der
192 definierten Variablen 1-2s. Ab der Moose/Rose::DB Version sind es 5-6s.
193
194 Mit FastCGI ist die neuste Version auf 0,26 Sekunden selbst in den kritischen
195 Pfaden, unter 0,15 sonst.
196
197 =head2 Bekannte Probleme
198
199 =head3 Encoding Awareness
200
201 UTF-8 kodierte Installationen sind sehr anfällig gegen fehlerhfate Encodings
202 unter FCGI. latin9 Installationen behandeln falsch kodierte Zeichen eher
203 unwissend, und geben sie einfach weiter. UTF-8 verweigert bei fehlerhaften
204 Programmpfaden kurzerhand aus ausliefern. Es wird noch daran gearbeitet alles
205 Fehler da zu beseitigen.
206