projekt kivitendo

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<title>kivitendo: Installation, Konfiguration, Entwicklung</title>

<chapter id="Aktuelle-Hinweise">

<title>Aktuelle Hinweise</title>

<para>Aktuelle Installations- und Konfigurationshinweise gibt es:</para>

<itemizedlist>

<listitem>

url="https://forum.kivitendo.org/">https://forum.kivitendo.org/</ulink></para>

</itemizedlist>

</chapter>

<sect1 id="Benötigte-Software-und-Pakete">

<title>Benötigte Software und Pakete</title>

<sect2 id="Betriebssystem">

<title>Betriebssystem</title>

diese Version im speziellen auf Debian und Ubuntu, grundsätzlich wurde

bei der Auswahl der Pakete aber darauf Rücksicht genommen, dass es

ohne große Probleme auf den derzeit aktuellen verbreiteten

Distributionen läuft.</para>

dass kivitendo auf ihnen läuft:</para>

<itemizedlist>

<itemizedlist>

<listitem>

<para>6.0 Squeeze (hier muss allerdings das Modul FCGI in der Version >= 0.72 compiled werden)</para>

</listitem>

<listitem>

<para>7.0 Wheezy</para>

</listitem>

</itemizedlist>

<listitem>

<listitem>

<listitem>

<para>SuSE Linux Enterprice Server 11</para>

</listitem>

<listitem>

</itemizedlist>

</sect2>

<sect2 id="Pakete" xreflabel="Pakete">

<title>Pakete</title>

benötigt.</para>

<itemizedlist>

linkend="config.sending-email.smtp"/>")</para></listitem>

linkend="config.sending-email.smtp"/>")</para></listitem>

<literal>Net::SSLGlue</literal>.</para>

hinzugekommen, <literal>URI</literal> und

<para>Gegenüber Version 2.6.1 sind <literal>parent</literal>,

<literal>DateTime</literal>, <literal>Rose::Object</literal>,

<literal>Rose::DB</literal> und <literal>Rose::DB::Object</literal>

neu hinzugekommen. <literal>IO::Wrap</literal> wurde entfernt.</para>

<para>Gegenüber Version 2.6.3 ist <literal>JSON</literal> neu

hinzugekommen.</para>

<para><literal>Email::Address</literal> und

<literal>List::MoreUtils</literal> sind schon länger feste

zukünftigen Version aber aus dem Paket entfernt werden. Es wird

empfohlen diese Module zusammen mit den anderen als Bibliotheken zu

installieren.</para>

<para>Die zu installierenden Pakete können in den verschiedenen

Distributionen unterschiedlich heißen.</para>

libtemplate-perl libtext-csv-xs-perl libtext-iconv-perl liburi-perl \

libxml-writer-perl libyaml-perl libconfig-std-perl \

libnet-sslglue-perl libnet-smtp-ssl-perl</programlisting>

<para>Für Fedora Core benötigen Sie diese Pakete:</para>

perl-Template-Toolkit perl-Text-CSV_XS perl-Text-Iconv perl-URI \

<para>Für OpenSuSE benötigen Sie diese Pakete:</para>

folgt:</para>

<programlisting>./scripts/installation_check.pl</programlisting>

</sect2>

</sect1>

<sect1 id="Manuelle-Installation-des-Programmpaketes"

xreflabel="Manuelle Installation des Programmpaketes">

<title>Manuelle Installation des Programmpaketes</title>

<filename>/var/www/html/</filename>,

<filename>/srv/www/htdocs</filename> oder

<filename>/var/www/</filename>) entpackt:</para>

tar xvzf kivitendo-erp-2.6.3.tgz</programlisting>

<para>Alternativ können Sie auch einen Alias in der

Webserverkonfiguration benutzen, um auf das tatsächliche

Installationsverzeichnis zu verweisen.</para>

beschreibbar sein, unter dem der Webserver läuft. Die restlichen Dateien müssen für diesen Benutzer lesbar sein. Die Benutzer- und

Gruppennamen sind bei verschiedenen Distributionen unterschiedlich (z.B. bei Debian/Ubuntu <constant>www-data</constant>, bei Fedora

core <constant>apache</constant> oder bei OpenSuSE <constant>wwwrun</constant>).</para>

<para>Der folgende Befehl ändert den Besitzer für die oben genannten

Verzeichnisse auf einem Debian/Ubuntu-System:</para>

<sect1 id="config.config-file">

xreflabel="Einführung in die Konfigurationsdatei">

<title>Einführung</title>

die benötigt wird: <filename>config/kivitendo.conf</filename> (kurz:

der Hauptkonfigurationsdatei stehen, überschreiben die Werte aus der

Default-Datei. Die Hauptkonfigurationsdatei muss also nur die

<para>

Vor der Umbenennung in kivitendo hieß diese Datei noch <filename>config/lx_office.conf</filename>. Aus Gründen der Kompatibilität

wird diese Datei eingelesen, sofern die Datei <filename>config/kivitendo.conf</filename> nicht existiert.

</para>

</note>

installationsspezifische Datei, d.h. sie enthält bspw. lokale

Passwörter und wird auch nicht im Versionsmanagement (git)

verwaltet.</para>

Mandaten, bzw. Datenbanken gleich.</para>

</sect2>

<title>Abschnitte und Parameter</title>

entsprechend kommentiert sind:</para>

linkend="Benutzerauthentifizierung-und-Administratorpasswort"/>" in diesem Kapitel)</para></listitem>

einzustellen oder zu kontrollieren sind, sind:</para>

<programlisting>[authentication]

[authentication/database]

host = localhost

port = 5432

password =

[system]

dbcharset = UTF-8</programlisting>

<varname>[periodic_invoices]</varname> den Login eines Benutzers

angeben, der nach Erstellung der Rechnungen eine entsprechende E-Mail

mit Informationen über die erstellten Rechnungen bekommt.</para>

<para>Nutzt man den <link

linkend="config.task-server">Taskserver</link> für <link

linkend="features.periodic-invoices">wiederkehrende Rechnungen</link>,

muss unter <varname>[task_server]</varname> ein Login eines Benutzers

<para>Für Entwickler finden sich unter <varname>[debug]</varname>

wichtige Funktionen, um die Fehlersuche zu erleichtern.</para>

</sect2>

<sect2 id="config.config-file.prior-versions">

<title>Versionen vor 2.6.3</title>

<filename>authentication.pl</filename> und

<filename>lx-erp.conf</filename>, die jeweils Perl-Dateien waren. Es

gab auch die Möglichkeit, eine lokale Version der Konfigurationsdatei

zu erstellen (<filename>lx-erp-local.conf</filename>). Dies ist ab

2.6.3 nicht mehr möglich, aber auch nicht mehr nötig.</para>

manuell übertragen und die alten Konfigurationsdateien anschließend

</sect2>

<sect1 id="Anpassung-der-PostgreSQL-Konfiguration">

<title>Anpassung der PostgreSQL-Konfiguration</title>

<para>PostgreSQL muss auf verschiedene Weisen angepasst werden.</para>

<sect2 id="Zeichensätze-die-Verwendung-von-UTF-8">

<title>Zeichensätze/die Verwendung von UTF-8</title>

eingreifen</para>

<para>Dieses kann überprüft werden: ist das Encoding der Datenbank

<programlisting>su postgres

echo '\l' | psql

exit </programlisting>

UTF-8-Encoding anzulegen und diesen zu verwenden. Unter Debian und

Ubuntu kann dies z.B. für PostgreSQL 8.2 mit dem folgenden Befehl

getan werden:</para>

Versionsnummer angepasst werden.</para>

<para>Unter anderen Distributionen gibt es ähnliche Methoden.</para>

<para>Wurde PostgreSQL nicht mit UTF-8 als Encoding initialisiert und

ist ein Neuanlegen eines weiteren Clusters nicht möglich, so kann

<literal>\l</literal> geprüft werden.</para>

<sect2 id="Änderungen-an-Konfigurationsdateien">

<title>Änderungen an Konfigurationsdateien</title>

dass TCP/IP-Verbindungen aktiviert sind. Das Verhalten wird über den

Datenbankverbindungen auch von anderen Rechnern aus zugelassen werden,

sein sollte, müssen die Berichtigungen für den Zugriff geändert

nögiten Verbindungen immer zuzulassen, für eine lokal laufenden

Datenbank zum Beispiel:</para>

host all kivitendo 127.0.0.1 255.255.255.255 password</programlisting>

<sect2 id="Erweiterung-für-servergespeicherte-Prozeduren">

<title>Erweiterung für servergespeicherte Prozeduren</title>

<para>In der Datenbank <literal>template1</literal> muss die

Unterstützung für servergespeicherte Prozeduren eingerichet werden.

<programlisting>su - postgres

psql template1</programlisting>

\q</programlisting>

<sect2 id="Datenbankbenutzer-anlegen">

<title>Datenbankbenutzer anlegen</title>

<para>Wenn Sie nicht den Datenbanksuperuser “postgres” zum Zugriff

benutzen wollen, so sollten Sie bei PostgreSQL einen neuen Benutzer

anlegen. Ein Beispiel, wie Sie einen neuen Benutzer anlegen

können:</para>

beantworten, genauso ist die Berechtigung neue User (Roles) zu

generieren nicht nötig.</para>

exit</programlisting>

<para>Wenn Sie später einen Datenbankzugriff konfigurieren, verändern

</sect2>

</sect1>

<sect1 id="Apache-Konfiguration">

<title>Webserver-Konfiguration</title>

<sect2>

<title>Grundkonfiguration mittels CGI</title>

<note>

<para>Für einen deutlichen Performanceschub sorgt die Ausführung

mittels FastCGI/FCGI. Die Einrichtung wird ausführlich im Abschnitt

<para>Der Zugriff auf das Programmverzeichnis muss in der Apache

Webserverkonfigurationsdatei <literal>httpd.conf</literal> eingestellt

werden. Fügen Sie den folgenden Abschnitt dieser Datei oder einer

anderen Datei hinzu, die beim Starten des Webservers eingelesen

wird:</para>

Deny from All

&lt;/Directory&gt;</programlisting>

<para>Ersetzen Sie dabei die Pfade durch diejenigen, in die Sie vorher

Plus ‘<literal>+</literal>’ gesetzt werden.</para>

<para>Auf einigen Webservern werden manchmal die Grafiken und

Style-Sheets nicht ausgeliefert. In solchen Fällen hat es oft

geholfen, die folgende Option in die Konfiguration aufzunehmen:</para>

<sect2 id="Apache-Konfiguration.FCGI"

xreflabel="Konfiguration für FastCGI/FCGI">

<title>Konfiguration für FastCGI/FCGI</title>

<sect3 id="Apache-Konfiguration.FCGI.WasIstEs">

<title>Was ist FastCGI?</title>

<para>Direkt aus <ulink

url="http://de.wikipedia.org/wiki/FastCGI">Wikipedia</ulink>

kopiert:</para>

<para><citation> 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. </citation></para>

</sect3>

<sect3 id="Apache-Konfiguration.FCGI.Warum">

<title>Warum FastCGI?</title>

ü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

benutzen wir umfangreiche Bibliotheken um Funktionaltät nicht selber

entwickeln zu müssen, die zusätzliche Ladezeit kosten. All dies

der Module verwendet wird.</para>

<para>Mit FastCGI werden nun die Module einmal geladen, und danach

wird nur die eigentliche Programmlogik ausgeführt.</para>

</sect3>

<sect3 id="Apache-Konfiguration.FCGI.WebserverUndPlugin">

<title>Getestete Kombinationen aus Webservern und Plugin</title>

<para>Folgende Kombinationen sind getestet:</para>

<itemizedlist>

<listitem>

<para>Apache 2.2.11 (Ubuntu) und mod_fcgid.</para>

</listitem>

<listitem>

<para>Apache 2.2.11 (Ubuntu) und mod_fastcgi.</para>

</listitem>

</itemizedlist>

<para>Dabei wird mod_fcgid empfohlen, weil mod_fastcgi seit geraumer

Zeit nicht mehr weiter entwickelt wird. Im Folgenden wird auf

mod_fastcgi nicht mehr explizit eingegangen.</para>

<para>Als Perl Backend wird das Modul <filename>FCGI.pm</filename>

verwendet.</para>

<warning>

bestimmte Eingaben von kivitendo. Falls es Probleme mit Umlauten in Ihrere Installation gibt, muss zwingend Version 0.68 oder

aber Version 0.72 und neuer eingesetzt werden.</para>

</warning>

<sect3 id="Apache-Konfiguration.FCGI.Konfiguration">

<title>Konfiguration des Webservers</title>

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.</para>

<para>Zuerst muss das FastCGI-Modul aktiviert werden. Dies kann

unter Debian/Ubuntu z.B. mit folgendem Befehl geschehen:</para>

<programlisting>a2enmod fcgid</programlisting>

und <function>Directory</function>-Direktiven. Dabei wird zwischen

("<filename>/path/to/kivitendo-erp</filename>") und der URL

unterschieden, unter der kivitendo im Webbrowser erreichbar ist

("<filename>/url/for/kivitendo-erp</filename>").</para>

<para>Folgender Konfigurationsschnipsel funktioniert mit

mod_fastcgi:</para>

Alias /url/for/kivitendo-erp/ /path/to/kivitendo-erp/

Options ExecCGI Includes FollowSymlinks

Order Allow,Deny

Allow from All

&lt;/Directory&gt;

Deny from All

&lt;/DirectoryMatch&gt;</programlisting>

<para>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:</para>

<programlisting>FcgidMaxRequestLen 10485760</programlisting>

<para>Das ganze sollte dann so aussehen:</para>

<programlisting>AddHandler fcgid-script .fpl

Alias /url/for/kivitendo-erp/ /path/to/kivitendo-erp/

Options ExecCGI Includes FollowSymlinks

Order Allow,Deny

Allow from All

&lt;/Directory&gt;

Deny from All

&lt;/DirectoryMatch&gt;</programlisting>

<para>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.</para>

wie oben beschrieben, die URLs werden aber umgeleitet:</para>

<programlisting># Zugriff über CGI

# Zugriff mit mod_fcgid:

Alias /url/for/kivitendo-erp-fcgid/ /path/to/kivitendo-erp/</programlisting>

</sect2>

</sect1>

<para>Der Task-Server ist ein Prozess, der im Hintergrund läuft, in

regelmäßigen Abständen nach abzuarbeitenden Aufgaben sucht und diese zu

festgelegten Zeitpunkten abarbeitet (ähnlich wie Cron). Dieser Prozess

wird bisher nur für die Erzeugung der wiederkehrenden Rechnungen

benutzt, wird aber in Zukunft deutlich mehr Aufgaben übertragen

bekommen.</para>

<sect2 id="Konfiguration-des-Task-Servers">

<title>Verfügbare und notwendige Konfigurationsoptionen</title>

<para>Die Konfiguration erfolgt über den Abschnitt

<literal>[task_server]</literal> in der Datei

<term><varname>login</varname></term>

in der Administration angelegt werden. Diese Option muss

angegeben werden.</para>

</listitem>

</varlistentry>

<term><varname>run_as</varname></term>

<listitem>

<para>Wird der Server vom Systembenutzer <literal>root</literal>

gestartet, so wechselt er auf den mit <literal>run_as</literal>

angegebenen Systembenutzer. Der Systembenutzer muss dieselben

Lese- und Schreibrechte haben, wie auch der Webserverbenutzer

(siehe see <xref

linkend="Manuelle-Installation-des-Programmpaketes" />). Daher

ist es sinnvoll, hier denselben Systembenutzer einzutragen,

unter dem auch der Webserver läuft.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>debug</varname></term>

<listitem>

<para>Schaltet Debug-Informationen an und aus.</para>

</listitem>

</varlistentry>

<sect2 id="Einbinden-in-den-Boot-Prozess">

<title>Automatisches Starten des Task-Servers beim Booten</title>

<para>Der Task-Server verhält sich von seinen Optionen her wie ein

reguläres SystemV-kompatibles Boot-Script. Außerdem wechselt er beim

<para>Deshalb ist es möglich, ihn durch Setzen eines symbolischen

Links aus einem der Runlevel-Verzeichnisse heraus in den Boot-Prozess

einzubinden. Da das bei neueren Linux-Distributionen aber nicht

zwangsläufig funktioniert, werden auch Start-Scripte mitgeliefert, die

anstelle eines symbolischen Links verwendet werden können.</para>

<sect3>

<title>SystemV-basierende Systeme (z.B. Debian, OpenSuSE, Fedora

Core)</title>

<para>Kopieren Sie die Datei

nach <filename>/etc/init.d/kivitendo-server</filename>. Passen

<literal>DAEMON=....</literal>). Binden Sie das Script in den

Boot-Prozess ein. Dies ist distributionsabhängig:</para>

<itemizedlist>

<listitem>

<para>Debian-basierende Systeme:</para>

<listitem>

<para>OpenSuSE und Fedora Core:</para>

</itemizedlist>

<sect3>

<title>Upstart-basierende Systeme (z.B. Ubuntu)</title>

<para>Kopieren Sie die Datei