Dokumentation für Flags in Variablen in Druckvorlagen

[kivitendo-erp.git] / doc / INSTALL.fcgi

diff --git a/doc/INSTALL.fcgi b/doc/INSTALL.fcgi
index 4583901..31ba60f 100644 (file)
--- a/doc/INSTALL.fcgi
+++ b/doc/INSTALL.fcgi
@@ -5,13 +5,15 @@ Diese Datei ist in Plain Old Documentation geschrieben. Mit
 
 ist sie deutlich leichter zu lesen.
 
 
 ist sie deutlich leichter zu lesen.
 

-=head1 FastCGI für Lx-Office
+=encoding utf8
+
+=head1 FastCGI für Lx-Office

 
 =head2 Was ist FastCGI?
 
 Direkt aus L<http://de.wikipedia.org/wiki/FastCGI> kopiert:
 
 
 =head2 Was ist FastCGI?
 
 Direkt aus L<http://de.wikipedia.org/wiki/FastCGI> kopiert:
 

-  FastCGI ist ein Standard für die Einbindung externer Software zur Generierung
+  FastCGI ist ein Standard für die Einbindung externer Software zur Generierung

   dynamischer Webseiten in einem Webserver. FastCGI ist vergleichbar zum Common
   Gateway Interface (CGI), wurde jedoch entwickelt, um dessen
   Performance-Probleme zu umgehen.
   dynamischer Webseiten in einem Webserver. FastCGI ist vergleichbar zum Common
   Gateway Interface (CGI), wurde jedoch entwickelt, um dessen
   Performance-Probleme zu umgehen.


@@ -20,32 +22,35 @@ Direkt aus L<http://de.wikipedia.org/wiki/FastCGI> kopiert:
 =head2 Warum FastCGI?
 
 Perl Programme (wie Lx-Office eines ist) werden nicht statisch kompiliert.
 =head2 Warum FastCGI?
 
 Perl Programme (wie Lx-Office eines ist) werden nicht statisch kompiliert.

-Stattdessen werden die Quelldateien bei jedem Start übersetzt, was bei kurzen
-Laufzeiten einen Großteil der Laufzeit ausmacht. Während SQL Ledger einen
-Großteil der Funktionalität in einzelne Module kapselt, um immer nur einen
-kleinen Teil laden zu müssen, ist die Funktionalität von Lx-Office soweit
+Stattdessen werden die Quelldateien bei jedem Start übersetzt, was bei kurzen
+Laufzeiten einen Großteil der Laufzeit ausmacht. Während SQL Ledger einen
+Großteil der Funktionalität in einzelne Module kapselt, um immer nur einen
+kleinen Teil laden zu müssen, ist die Funktionalität von Lx-Office soweit

 gewachsen, dass immer mehr Module auf den Rest des Programms zugreifen.
 gewachsen, dass immer mehr Module auf den Rest des Programms zugreifen.

-Zusätzlich benutzen wir umfangreiche Bibliotheken um Funktionaltät nicht selber
-entwickeln zu müssen, die zusätzliche Ladezeit kosten. All dies führt dazu dass
-ein Lx-Office Aufruf der Kernmasken mittlerweile deutlich länger dauert als
-früher, und dass davon 90% für das Laden der Module verwendet wird.
+Zusätzlich benutzen wir umfangreiche Bibliotheken um Funktionaltät nicht selber
+entwickeln zu müssen, die zusätzliche Ladezeit kosten. All dies führt dazu dass
+ein Lx-Office Aufruf der Kernmasken mittlerweile deutlich länger dauert als
+früher, und dass davon 90% für das Laden der Module verwendet wird.

 
 Mit FastCGI werden nun die Module einmal geladen, und danach wird nur die
 
 Mit FastCGI werden nun die Module einmal geladen, und danach wird nur die

-eigentliche Programmlogik ausgeführt.
+eigentliche Programmlogik ausgeführt.

 
 =head2 Kombinationen aus Webservern und Plugin.
 
 Folgende Kombinationen sind getestet:
 
 
 =head2 Kombinationen aus Webservern und Plugin.
 
 Folgende Kombinationen sind getestet:
 

+ * Apache 2.2.11 (Ubuntu) und mod_fcgid.

  * Apache 2.2.11 (Ubuntu) und mod_fastcgi.
  * Apache 2.2.11 (Ubuntu) und mod_fastcgi.

- * Apache 2.2.11 (Ubuntu) und mod_fcgid:
+
+Dabei wird mod_fcgid empfohlen, weil mod_fastcgi seit geraumer Zeit
+nicht mehr weiter entwickelt wird.

 
 Als Perl Backend wird das Modul FCGI.pm verwendet. Vorsicht: FCGI 0.69 und
 
 Als Perl Backend wird das Modul FCGI.pm verwendet. Vorsicht: FCGI 0.69 und

-höher ist extrem strict in der Behandlung von Unicode, und verweigert bestimmte
+höher ist extrem strict in der Behandlung von Unicode, und verweigert bestimmte

 Eingaben von Lx-Office. Solange diese Probleme nicht behoben sind, muss auf die
 Eingaben von Lx-Office. Solange diese Probleme nicht behoben sind, muss auf die

-Vorgängerversion FCGI 0.68 ausgewichen werden.
+Vorgängerversion FCGI 0.68 ausgewichen werden.

 
 

-Mit cpan lässt sie sich wie folgt installieren:
+Mit cpan lässt sie sich wie folgt installieren:

 
  force install M/MS/MSTROUT/FCGI-0.68.tar.gz
 
 
  force install M/MS/MSTROUT/FCGI-0.68.tar.gz
 


@@ -54,18 +59,18 @@ Mit cpan l
 Bevor Sie versuchen eine Lx-Office Installation unter FCGI laufen zu lassen,
 empfliehlt es sich die Installation ersteinmal unter CGI aufzusetzen. FCGI
 macht es nicht einfach Fehler zu debuggen die beim ersten aufsetzen auftreten
 Bevor Sie versuchen eine Lx-Office Installation unter FCGI laufen zu lassen,
 empfliehlt es sich die Installation ersteinmal unter CGI aufzusetzen. FCGI
 macht es nicht einfach Fehler zu debuggen die beim ersten aufsetzen auftreten

-können. Sollte die Installation schon funktionieren, lesen Sie weiter.
+können. Sollte die Installation schon funktionieren, lesen Sie weiter.

 
 Zuerst muss das FastCGI-Modul aktiviert werden. Dies kann unter
 Debian/Ubuntu z.B. mit folgendem Befehl geschehen:
 
 
 Zuerst muss das FastCGI-Modul aktiviert werden. Dies kann unter
 Debian/Ubuntu z.B. mit folgendem Befehl geschehen:
 

-  a2enmod fastcgi
+  a2enmod fcgid

 
 bzw.
 
 
 bzw.
 

-  a2enmod fcgid
+  a2enmod fastcgi

 
 

-Die Konfiguration für die Verwendung von Lx-Office mit FastCGI erfolgt
+Die Konfiguration für die Verwendung von Lx-Office mit FastCGI erfolgt

 durch Anpassung der vorhandenen Alias- und Directory-Direktiven. Dabei
 wird zwischen dem Installationspfad von Lx-Office im Dateisystem
 ("/path/to/lx-office-erp") und der URL unterschieden, unter der
 durch Anpassung der vorhandenen Alias- und Directory-Direktiven. Dabei
 wird zwischen dem Installationspfad von Lx-Office im Dateisystem
 ("/path/to/lx-office-erp") und der URL unterschieden, unter der


@@ -73,12 +78,11 @@ Lx-Office im Webbrowser erreichbar ist ("/web/path/to/lx-office-erp").
 
 Folgendes Template funktioniert mit mod_fastcgi:
 
 
 Folgendes Template funktioniert mit mod_fastcgi:
 

-  AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl
+  AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fcgi

   Alias       /web/path/to/lx-office-erp/          /path/to/lx-office-erp/
 
   <Directory /path/to/lx-office-erp>
     AllowOverride All
   Alias       /web/path/to/lx-office-erp/          /path/to/lx-office-erp/
 
   <Directory /path/to/lx-office-erp>
     AllowOverride All

-    AddHandler fastcgi-script .fpl

     Options ExecCGI Includes FollowSymlinks
     Order Allow,Deny
     Allow from All
     Options ExecCGI Includes FollowSymlinks
     Order Allow,Deny
     Allow from All


@@ -89,45 +93,67 @@ Folgendes Template funktioniert mit mod_fastcgi:
     Deny from All
   </DirectoryMatch>
 
     Deny from All
   </DirectoryMatch>
 

-...und für mod_fcgid muss die erste Zeile geändert werden in:
+Für mod_fcgid muss ein AddHandler ergänzt werden und die erste Zeile geändert werden:

 
 

-  AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fcgi
+  AddHandler fcgid-script .fpl
+  AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl
+
+Seit mod_fcgid-Version 2.6.3 gelten sehr kleine Grenzen für die
+maximale Größe eines Requests. Diese sollte wie folgt hochgesetzt werden:
+
+  FcgidMaxRequestLen 10485760
+
+Das ganze sollte dann so aussehen:
+
+  AddHandler fcgid-script .fpl
+  AliasMatch ^/web/path/to/lx-office-erp/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl
+  Alias       /web/path/to/lx-office-erp/          /path/to/lx-office-erp/
+  FcgidMaxRequestLen 10485760

 
 

+  <Directory /path/to/lx-office-erp>
+    AllowOverride All
+    Options ExecCGI Includes FollowSymlinks
+    Order Allow,Deny
+    Allow from All
+  </Directory>
+
+  <DirectoryMatch /path/to/lx-office-erp/users>
+    Order Deny,Allow
+    Deny from All
+  </DirectoryMatch>

 
 Hierdurch wird nur ein zentraler Dispatcher gestartet. Alle Zugriffe
 auf die einzelnen Scripte werden auf diesen umgeleitet. Dadurch, dass
 
 Hierdurch wird nur ein zentraler Dispatcher gestartet. Alle Zugriffe
 auf die einzelnen Scripte werden auf diesen umgeleitet. Dadurch, dass

-zur Laufzeit öfter mal Scripte neu geladen werden, gibt es hier kleine
-Performance-Einbußen. Trotzdem ist diese Variante einer globalen
-Benutzung von "AddHandler fastcgi-script .pl" vorzuziehen.
+zur Laufzeit öfter mal Scripte neu geladen werden, gibt es hier kleine
+Performance-Einbußen.

 
 
 
 

-Es ist möglich die gleiche Lx-Office Version parallel unter cgi und fastcgi zu
-betreiben. Dafür bleiben Directorydirektiven bleiben wie oben beschrieben, die
-URLs werden aber umgeleitet:
+Es ist möglich die gleiche Lx-Office Version parallel unter cgi und fastcgi zu
+betreiben. Dafür bleiben die Directorydirektiven wie oben beschrieben, die URLs
+werden aber umgeleitet:

 
 

-  # Zugriff ohne FastCGI
+  # Zugriff über cgi

   Alias       /web/path/to/lx-office-erp                /path/to/lx-office-erp
 
   Alias       /web/path/to/lx-office-erp                /path/to/lx-office-erp
 

-  # Zugriff mit FastCGI:
-  AliasMatch ^/web/path/to/lx-office-erp-fcgi/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl
-  Alias       /web/path/to/lx-office-erp-fcgi/          /path/to/lx-office-erp/
+  # Zugriff mit mod_fcgid:
+  AliasMatch ^/web/path/to/lx-office-erp-fcgid/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fpl
+  Alias       /web/path/to/lx-office-erp-fcgid/          /path/to/lx-office-erp/

 
 

-Dann ist unter C</web/path/to/lx-office-erp/> die normale Version erreichbar,
-und unter C</web/opath/to/lx-office-erp-fcgi/> die FastCGI Version.
-
-Achtung:
+  # Zugriff mit mod_fastcgi:
+  AliasMatch ^/web/path/to/lx-office-erp-fastcgi/[^/]+\.pl /path/to/lx-office-erp/dispatcher.fcgi
+  Alias       /web/path/to/lx-office-erp-fastcgi/          /path/to/lx-office-erp/

 
 

-Die AddHandler Direktive vom Apache ist entgegen der Dokumentation
-anscheinend nicht lokal auf das Verzeichnis beschränkt sondern global im
-vhost.
+Dann ist unter C</web/path/to/lx-office-erp/> die normale Version erreichbar,
+und unter C</web/path/to/lx-office-erp-fcgid/> bzw.
+C</web/path/to/lx-office-erp-fastcgi/> die FastCGI Version.

 
 =head2 Entwicklungsaspekte
 
 
 =head2 Entwicklungsaspekte
 

-Wenn Änderungen in der Konfiguration von Lx-Office gemacht werden, muss der
-Server neu gestartet werden.
+Wenn Änderungen in der Konfiguration von Lx-Office gemacht werden, muss der
+Webserver neu gestartet werden.

 
 

-Bei der Entwicklung für FastCGI ist auf ein paar Fallstricke zu achten. Dadurch
-dass das Programm in einer Endlosschleife läuft, müssen folgende Aspekte
+Bei der Entwicklung für FastCGI ist auf ein paar Fallstricke zu achten. Dadurch
+dass das Programm in einer Endlosschleife läuft, müssen folgende Aspekte

 geachtet werden:
 
 =head3 Programmende und Ausnahmen: C<warn>, C<die>, C<exit>, C<carp>, C<confess>
 geachtet werden:
 
 =head3 Programmende und Ausnahmen: C<warn>, C<die>, C<exit>, C<carp>, C<confess>


@@ -139,7 +165,7 @@ angezeigt werden. Die Lx-Office eigene C<$::form->error()> tut im Prinzip das
 Gleiche, mit ein paar Extraoptionen. C<warn> und C<exit> hingegen werden nicht
 abgefangen. C<warn> wird direkt nach STDERR, also in Server Log eine Nachricht
 schreiben (sofern in der Konfiguration nicht die Warnungen in das Lx-Office Log
 Gleiche, mit ein paar Extraoptionen. C<warn> und C<exit> hingegen werden nicht
 abgefangen. C<warn> wird direkt nach STDERR, also in Server Log eine Nachricht
 schreiben (sofern in der Konfiguration nicht die Warnungen in das Lx-Office Log

-umgeleitet wurden), und C<exit> wird die Ausführung beenden.
+umgeleitet wurden), und C<exit> wird die Ausführung beenden.

 
 Prinzipiell ist es kein Beinbruch, wenn sich der Prozess beendet, fcgi wird ihn
 sofort neu starten. Allerdings sollte das die Ausnahme sein. Quintessenz: Bitte
 
 Prinzipiell ist es kein Beinbruch, wenn sich der Prozess beendet, fcgi wird ihn
 sofort neu starten. Allerdings sollte das die Ausnahme sein. Quintessenz: Bitte


@@ -148,15 +174,15 @@ kein C<exit> benutzen, alle anderen Exceptionmechanismen sind ok.
 =head3 Globale Variablen
 
 Um zu vermeiden, dass Informationen von einem Request in einen anderen gelangen,
 =head3 Globale Variablen
 
 Um zu vermeiden, dass Informationen von einem Request in einen anderen gelangen,

-müssen alle globalen Variablen vor einem Request sauber initialisiert werden.
+müssen alle globalen Variablen vor einem Request sauber initialisiert werden.

 Das ist besonders wichtig im C<$::cgi> und C<$::auth> Objekt, weil diese nicht
 Das ist besonders wichtig im C<$::cgi> und C<$::auth> Objekt, weil diese nicht

-gelöscht werden pro Instanz, sondern persistent gehalten werden.
+gelöscht werden pro Instanz, sondern persistent gehalten werden.

 
 In C<SL::Dispatcher> gibt es einen sauber abgetrennten Block der alle
 
 In C<SL::Dispatcher> gibt es einen sauber abgetrennten Block der alle

-kanonischen globalen Variablen listet und erklärt. Bitte keine anderen
-einführen ohne das sauber zu dokumentieren.
+kanonischen globalen Variablen listet und erklärt. Bitte keine anderen
+einführen ohne das sauber zu dokumentieren.

 
 

-Datenbankverbindungen wird noch ein Guide verfasst werden, wie man sichergeht,
+Datenbankverbindungen wird noch ein Guide verfasst werden, wie man sicher geht,

 dass man die richtige erwischt.
 
 =head2 Performance und Statistiken
 dass man die richtige erwischt.
 
 =head2 Performance und Statistiken


@@ -174,9 +200,9 @@ Pfaden, unter 0,15 sonst.
 
 =head3 Encoding Awareness
 
 
 =head3 Encoding Awareness
 

-UTF-8 kodierte Installationen sind sehr anfällig gegen fehlerhfate Encodings
+UTF-8 kodierte Installationen sind sehr anfällig gegen fehlerhfate Encodings

 unter FCGI. latin9 Installationen behandeln falsch kodierte Zeichen eher
 unwissend, und geben sie einfach weiter. UTF-8 verweigert bei fehlerhaften
 unter FCGI. latin9 Installationen behandeln falsch kodierte Zeichen eher
 unwissend, und geben sie einfach weiter. UTF-8 verweigert bei fehlerhaften

-Programmpfaden kurzerhand aus ausliefern. Es wird noch daran gearbeitet alles
+Programmpfaden kurzerhand das Ausliefern. Es wird noch daran gearbeitet, alle

 Fehler da zu beseitigen.
 
 Fehler da zu beseitigen.