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