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">

<chapter id="Aktuelle-Hinweise">

<title>Aktuelle Hinweise</title>

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

<itemizedlist>

<listitem>

<para>in der doc/UPGRADE Datei im doc-Verzeichnis der Installation</para>

</listitem>

<listitem>

<para>Im Schulungs- und Dienstleistungsangebot der entsprechenden kivitendo-Partner: <ulink

url="http://www.kivitendo.de/partner.html">http://www.kivitendo.de/partner.html</ulink></para>

</listitem>

</chapter>

<title>Übersicht</title>

<para>

Die Installation von kivitendo umfasst mehrere Schritte. Die folgende Liste kann sowohl für Neulinge als auch für alte Hasen als

Übersicht und Stichpunktliste zum Abhaken dienen, um eine Version mit minimalen Features möglichst schnell zum Laufen zu kriegen.

</para>

<orderedlist>

<listitem><para><emphasis>Voraussetzungen überprüfen</emphasis>: kivitendo benötigt gewisse Ressourcen und benutzt weitere

Programme. Das Kapitel "<xref linkend="Benötigte-Software-und-Pakete"/>" erläutert diese. Auch die Liste der benötigten Perl-Module

befindet sich hier.</para></listitem>

<listitem><para><emphasis>Installation von kivitendo</emphasis>: Diese umfasst die "<xref

linkend="Manuelle-Installation-des-Programmpaketes"/>" sowie grundlegende Einstellungen, die der "<xref

linkend="config.config-file"/>" erläutert.</para></listitem>

<listitem><para><emphasis>Konfiguration externer Programme</emphasis>: hierzu gehören die Datenbank ("<xref

linkend="Anpassung-der-PostgreSQL-Konfiguration"/>") und der Webserver ("<xref

linkend="Apache-Konfiguration"/>"). </para></listitem>

<listitem><para><emphasis>Benutzerinformationen speichern können</emphasis>: man benötigt mindestens eine Datenbank, in der

Informationen zur Authentifizierung sowie die Nutzdaten gespeichert werden. Wie man das als Administrator macht, verrät "<xref

linkend="Benutzerauthentifizierung-und-Administratorpasswort"/>".</para></listitem>

<listitem><para><emphasis>Benutzer, Gruppen und Datenbanken anlegen</emphasis>: wie dies alles zusammenspielt erläutert "<xref

linkend="Benutzer--und-Gruppenverwaltung"/>".</para></listitem>

<listitem><para><emphasis>Los geht's</emphasis>: alles soweit erledigt? Dann kann es losgehen: "<xref

linkend="kivitendo-ERP-verwenden"/>"</para></listitem>

</orderedlist>

<para>

</para>

</sect1>

<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>

<itemizedlist>

<itemizedlist>

<listitem>

<listitem>

</itemizedlist>

<listitem>

<listitem>

<listitem>

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

</listitem>

<listitem>

</itemizedlist>

</sect2>

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

überprüfen, ob die erforderlichen Pakete installiert und aktuell genug sind, wird ein Script mitgeliefert, das wie folgt aufgerufen

wird:</para>

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

<para>Die vollständige Liste der benötigten Perl-Module lautet:</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>

<title>Debian und Ubuntu</title>

<programlisting>apt-get install apache2 libarchive-zip-perl libclone-perl \

libconfig-std-perl libdatetime-perl libdbd-pg-perl libdbi-perl \

libemail-address-perl libemail-mime-perl libfcgi-perl libjson-perl \

liblist-moreutils-perl libnet-smtp-ssl-perl libnet-sslglue-perl \

libparams-validate-perl libpdf-api2-perl librose-db-object-perl \

librose-db-perl librose-object-perl libsort-naturally-perl \

libstring-shellquote-perl libtemplate-perl libtext-csv-xs-perl \

libtext-iconv-perl liburi-perl libxml-writer-perl libyaml-perl \

<para>Für das Paket HTML::Restrict gibt es kein Debian-Paket, dies muß per CPAN installiert werden. Der entsprechende Befehl wird beim Aufruf von installation_check.pl angezeigt.</para>

<title>Fedora Core</title>

perl-DBI perl-DateTime perl-Email-Address perl-Email-MIME perl-FCGI \

perl-Rose-Object perl-Sort-Naturally perl-String-ShellQuote \

cpan Config::Std</programlisting>

<title>openSUSE</title>

<para>Für openSUSE stehen die meisten der benötigten Perl-Pakete als RPM-Pakete zur Verfügung. Sie können mit folgendem Befehl

installiert werden:</para>

<programlisting>zypper install apache2 perl-Archive-Zip perl-Clone \

perl-Config-Std perl-DBD-Pg perl-DBI perl-DateTime perl-Email-Address \

perl-Sort-Naturally perl-Template-Toolkit perl-Text-CSV_XS perl-Text-Iconv \

perl-URI perl-XML-Writer perl-YAML postgresql-server</programlisting>

<para>Zusätzlich müssen einige Pakete aus dem CPAN installiert werden. Dazu können Sie die folgenden Befehle nutzen:</para>

<programlisting>yum install perl-CPAN

cpan Rose::Db::Object</programlisting>

</sect3>

</sect1>

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

xreflabel="Manuelle Installation des Programmpaketes">

<title>Manuelle Installation des Programmpaketes</title>

<ulink url="https://github.com/kivitendo/kivitendo-erp/releases">hier</ulink> heruntergeladen werden.</para>

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

Webserverkonfiguration benutzen, um auf das tatsächliche

Installationsverzeichnis zu verweisen.</para>

<programlisting>mkdir webdav</programlisting>

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

<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>

<listitem><para><literal>testing/database</literal></para></listitem>

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

<programlisting>[authentication]

[authentication/database]

host = localhost

port = 5432

<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>

linkend="config.task-server">Taskserver</link>. Er wird u.a. für Features wie die <link

linkend="features.periodic-invoices">wiederkehrenden Rechnungen</link> benötigt, erledigt aber auch andere erforderliche Aufgaben

und muss daher in Betrieb genommen werden. Der Taskserver benötigt zwei Konfigurationseinstellungen, die unter

<varname>[task_server]</varname> anzugeben sind: ein Mandant (entweder der Mandantenname oder eine Datenbank-ID, Variable

<varname>client</varname>), aus dem die Datenbankkonfiguration entnommen wird, sowie ein Login (Variable <varname>login</varname>)

eines Benutzers, der für gewisse Dinge wie die Rechnungserstellung als Verkäufer eingetragen wird.</para>

<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">

braucht man hier meist nicht einzugreifen.</para>

braucht man nichts weiteres diesbezüglich unternehmen. Zum Testen:</para>

<programlisting>su postgres

echo '\l' | psql

exit </programlisting>

Unicode-Encoding anzulegen und diesen zu verwenden. Unter Debian und

Versionsnummer angepasst werden.</para>

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

<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

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>

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

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>

diese zu festgelegten Zeitpunkten abarbeitet (ähnlich wie Cron). Dieser Prozess wird u.a. für die Erzeugung der wiederkehrenden

Rechnungen und weitere essenzielle Aufgaben benutzt.</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