Kundentyp in Rechnungssuche auch als Wert in Rechnungsübersicht anzeigen und exportieren
[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 =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