Angenommen, es wird eine PostgreSQL-Datenbank namens "items3" auf dem Host database.server verwendet, können Sie das Backend beispielsweise so starten:

  docker run \
    --name items-backend \
    --detach --restart always \
    --publish 1099:1099/tcp \
    --publish 1100:1100/tcp \
    --env javax_persistence_jdbc_url=jdbc:postgresql://database.server/items3 \
    harbor.svc.factor3.de/items/backend:latest

Angenommen, das Backend läuft auf dem Host items.server, können Sie eine Web-Application, die auf dieses Backend zugreift und auf Port 8081 erreichbar ist, beispielsweise so starten:

  docker run \
    --name items-webapp \
    --detach --restart always \
    --publish 1101:1099/tcp \
    --publish 1102:1100/tcp \
    --publish 8081:8080/tcp \
    --env registryAddress=items.server \
    --env registryPort=1099 \
    harbor.svc.factor3.de/items/webapp:latest

Das Backend verwendet die folgenden Ports:

1099: die RMI-Registry, einstellbar mittels der Umgebungsvariable listenRegistryPort. Dieser Port muss für die Web-Application erreichbar sein.

1100: das Backend selbst, einstellbar mittels der Umgebungsvariable listenApplicationPort. Dieser Port muss für die Web-Application erreichbar sein.

Die Web-Application verwendet die folgenden Ports:

1099: die RMI-Registry, einstellbar mittels der Umgebungsvariable listenRegistryPort. Dieser Port muss für das Backend erreichbar sein.

1100: Event-Handler der Web-Application, einstellbar mittels der Umgebungsvariable listenApplicationPort. Dieser Port muss für das Backend erreichbar sein.

8080: HTTP/1.1 für den Zugriff auf die Anwendung. An diesen Port können Sie sich direkt mit Ihrem Webbrowser verbinden oder die Anwendung per Reverse Proxy mit Apache2 im gesamten Netzwerk verfügbar machen.

8009: AJP/1.3 für den Zugriff auf die Anwendung. Diesen Port können Sie verwenden, um die Anwendung per mod_jk mit Apache2 im gesamten Netzwerk verfügbar zu machen.

Für das Backend:

Zusätzlich werden alle Umgebungsvariablen, die mit "java_", "javax_" oder "eclipselink_" beginnen, als Java System Properties gesetzt. Der Name des System Property entspricht dabei dem Namen der Umgebungsvariablen entspricht, wobei alle "_" durch "." ersetzt werden.

Für die Web-Application:

Üblicherweise werden Sie einen dedizierten HTTP-Server als Frontend vor der Web-Application einsetzen wollen, um gesicherte Verbindungen mittels HTTPS zu verwenden, Redirects zu konfigurieren, Zugriffsprotokollierung zu ermöglichen, und ähnliches.

Apache httpd kann zu diesem Zweck als Reverse Proxy (empfohlen) eingesetzt werden. Ist der Web-Application-Container an webapp.server:8080 gebunden, können Sie in der Site-Konfiguration dazu beispielsweise folgendes angeben:

  AllowEncodedSlashes NoDecode
  ProxyRequests Off

  ProxyPass /items/ http://webapp.server:8080/items/ nocanon
  ProxyPassReverse /items/ http://webapp.server:8080/items/

  DocumentRoot /var/www/items

Damit werden alle Anfragen für URLs unterhalb von /items/ an den Web-Application-Container weitergeleitet, während alle restlichen Anfragen auf lokale Dateien unterhalb von /var/www/items zugreifen.

Um die Web-Application stattdessen mittels AJP/1.3 anzubinden, müssen Sie mod_jk (unter Debian im Paket libapache2-mod-jk enthalten) installieren und mittels a2enmod jk aktivieren. Anschließend können Sie in der Site-Konfiguration folgendes angeben:

  JkMount /items/* ajp13_worker

Um die neuen Docker-Images herunterzuladen, führen Sie auf dem Host folgendes aus:

  docker pull harbor.svc.factor3.de/items/backend:latest
  docker pull harbor.svc.factor3.de/items/webapp:latest

Dabei ersetzen Sie in beiden obigen Befehlen latest jeweils durch die Versionsnummer der ITEMS-Release, die Sie in Betrieb nehmen wollen. Wollen Sie eine Version in den Produktivbetrieb nehmen, sollte diese Versionsnummer natürlich der Version entsprechen, die Sie vorher auf Ihrem Testsystem geprüft haben. Geben Sie bei einer Übernahme in den Produktivbetrieb niemals latest an, da ansonsten eine möglicherweise zwischenzeitlich freigegebene, neue Version von ITEMS in Betrieb genommen wird anstatt derselben Version wie auf Ihrem Testsystem!

Haben Sie sich auf dem Host noch nicht bei der Factor3-Docker-Registry angemeldet, so können Sie das vor der Ausführung von obigem docker pull (bzw. falls eine entsprechende Fehlermeldung von diesen Befehlen ausgegeben wird) mittels docker login harbor.svc.factor3.de erledigen.

Wenn Sie die Docker-Container mit docker run --detach --restart always starten, werden diese von dockerd automatisch immer neu gestartet, wenn der Server neu startet.

Um eine neue Version in Betrieb zu nehmen, müssen Sie daher zunächst den jeweiligen Container beenden, für das Backend mittels docker stop items-backend und für die Web-Application mittels docker stop items-webapp sofern Sie die empfohlenen Container-Namen verwenden; anderenfalls müssen Sie in den beiden Befehlen den jeweils von Ihnen verwendeten Container-Namen einsetzen.

Anschließend können Sie die Container wie gewohnt neu starten, etwa wie unter Wie starte ich die Docker-Container? beschrieben.

Falls PostgreSQL auf dem selben Host betrieben werden soll, auf dem auch der Backend-Container läuft, aber aus Sicherheitsgründen nicht an alle Schnittstellen gebunden werden soll, können Sie die Adresse, die der docker0-Schnittstelle zugewiesen wird, zu der Einstellung listen_addresses in postgresql.conf hinzufügen, zum Beispiel folgendermaßen:

listen_addresses = 'localhost, 172.17.0.1'

Anschließend müssen Verbindungen aus dem Netzwerk, das für die Docker-Container verwendet wird, in pg_hba.conf zugelassen werden, beispielsweise wie folgt:

host all all 172.17.0.0/24 md5

Damit die Schnittstelle docker0 auch verfügbar ist, muss der Docker-Service vor PostgreSQL gestartet werden. Je nach verwendetem System können Sie dazu "docker" zum "Required-Start"-Header in /etc/init.d/postgresql hinzufügen, oder mittels systemctl edit postgresql folgendes Override für die Service-Definition erstellen:

  [Unit]
  Requires=docker
  After=docker

Nachdem Docker nsswitch nicht verwendet, erfolgen tatsächlich Namensauflösungen nicht über den gewohnten Weg, sondern nur aus /etc/hosts und über die konfigurierten DNS-Server.

Um trotzdem symbolische Namen in den Containern verwenden zu können (beispielsweise für den Datenbank-Server in der URL für das Backend), können Sie diese in einem Skript auf dem Host mittels getent hosts HOST auflösen und dann per --add-host= im docker run-Aufruf angeben.

Der Link verweist immer auf /items-help und muss von Ihnen auf die gewünschte URL umgeleitet werden.

Sofern Sie Apache httpd als Reverse Proxy einsetzen, können Sie dazu in der Site-Konfiguration folgendes angeben:

  Redirect /items-help https://www.server/items/help.html
  ProxyPass /items-help !

Die URL in obigem Beispiel können Sie nach Belieben Ihren lokalen Vorgaben anpassen.

ITEMS bindet auf jeder Seite ein spezielles Stylesheet ein, das Sie auf eine von Ihnen bereitgestellte Version auf einem Ihrer Server umleiten können, womit Sie mit beliebigen CSS-Anweisungen die Oberfläche von ITEMS anpassen können. Dazu müssen Sie den Pfad css/items-customizations.css unterhalb vom Context Root, unter dem ITEMS läuft, auf die von Ihnen gewünschte URL umleiten.

Sofern Sie Apache httpd als Reverse Proxy einsetzen und als Context Root /items/ verwenden, können Sie dazu in der Site-Konfiguration folgendes angeben:

  Redirect /items/css/items-customizations.css https://www.server/items/items-customizations.css
  ProxyPass /items/css/items-customizations.css !

Die URL in obigem Beispiel können Sie nach Belieben Ihren lokalen Vorgaben anpassen.

Um dann beispielsweise beim Ausdruck jeder Seite einen Briefkopf auszugeben, der als PNG-Datei unter https://www.server/items/header.png liegt, können Sie folgendes CSS in diese Datei einfügen:

  @media print {
    header:before {
      content: url("https://www.server/items/header.png");
      display: inline-block;
      width: 100%;
      padding-top: 20px;
      text-align: center;
    }
  }

• Sie können einen Zweig im Verzeichnis erstellen, der nur die gewünschten Personen enthält. Anschließend geben Sie den Pfad für diesen Zweig in der Konfiguration des entsprechenden Clusters an:
  1. Administration → Management-Dienst → Oberflächen-Cluster
  2. Gewünschten Cluster auswählen
  3. Unter "Anmeldekonfiguration" die Zeile "Anmeldung über externen Anmeldeservice" bearbeiten
  4. In der Zeile mit jndi.java.naming.provider.url den Pfad entsprechend eintragen, z.B. "ldap://localhost/ou=restricted,ou=persons,dc=hostname"
• Wenn Sie ein com.sun.security.auth.module.LDAPLoginModule oder ein de.devbrain.bw.app.jaas.LDAPLoginModule verwenden, können Sie als userFilter einen LDAP-Suchausdruck angeben, der die Suchergebnisse entsprechend beschränkt.
  Um beispielsweise nur Mitglieder der LDAP-Gruppe cn=items,ou=roles,dc=mydomain,dc=de zur Anmeldung zuzulassen, wird etwa aus

  (&(objectClass=organizationalPerson)(sn={0}))

  nun

  (&(objectClass=organizationalPerson)(sn={0})(memberof=cn=items,ou=roles,dc=mydomain,dc=de))
  Um das einzustellen, gehen Sie genauso wie oben vor.

Aus Sicht der Hardware:

Wenn Sie ITEMS auf einem virtuellen Server betreiben, kann bei Ausfall des Hosts der Guest automatisch auf einen anderen Host umziehen.

Die Anbindung der Hosts an das SAN sollte redundant erfolgen, und wenn das SAN wiederum über redundante Server mit Spiegelung betrieben wird, ist auch hier die gewünschte Redundanz erreicht.

Ebenso sollte natürlich die Stromversorgung mittels USV abgesichert sein, und die Anbindung der Hosts an das LAN sollte natürlich auch redundant erfolgen.

Aus Sicht der Software:

Sie sollten mehrere LDAP-Server für Authentifizierung und Verzeichnisdienste bereitstellen, die alle unter demselben Hostnamen konfiguriert sind. Eine Umschaltung erfolgt dann automatisch, wenn einer der Server ausfällt.

Üblicherweise wird Ihr DNS-Cluster genauso konfiguriert sein, dass an mehreren Standorten mehrere DNS-Server unter demselben Hostnamen erreichbar sind. Auch hier erfolgt die Umschaltung dann automatisch.

Wenn Sie mehrere SMTP-Server zur Verfügung stellen, sollten Sie diese dem ITEMS-Server bekannt machen. Wird als MTA auf dem ITEMS-Server beispielsweise Postfix verwendet, dann sollten Sie sowohl relayhost als auch smtp_fallback_relay setzen.

Falls Sie eine eigene CA betreiben und damit die Zertifikate von z.B. einem LDAP- oder Kerberos-Server signieren, auf den ITEMS zugreifen soll, muss das Zertifikat der CA im Container verfügbar sein, da ansonsten keine Authentifizierung des jeweiligen Servers möglich ist.

Dazu gibt es zwei Möglichkeiten:

1. Wollen Sie zusätzliche Zertifikate im PEM-Format einbinden, können Sie diese mit Endung .crt im Verzeichnis /certificates im Container zur Verfügung stellen und müssen USE_SYSTEM_CA_CERTS setzen, z.B. --volume /etc/ssl/certs:/certificates --env USE_SYSTEM_CA_CERTS=1. Damit fügen Sie alle Zertifikate in /etc/ssl/certs zum systemweiten CA-Store hinzu, aus dem dann der Java-Keystore generiert wird, den ITEMS verwendet.
2. Sie können wie bisher auch den gesamten Java-Keystore ersetzen, indem Sie die Datei /opt/java/openjdk/lib/security/cacerts durch einen entsprechenden Mount ersetzen, z.B. --volume /etc/ssl/certs/java/cacerts:/opt/java/openjdk/lib/security/cacerts.

Um zu überprüfen, welche CA-Zertifikate für z.B. das ITEMS-Backend verfügbar sind: sudo docker container exec items-backend keytool -list -cacerts

Alle Protokollmeldungen werden von den jeweiligen Containern auf stdout bzw. stderr ausgegeben, wo sie entsprechend der Docker-Konfiguration gespeichert werden.

In der Standard-Konfiguration von Docker können die Meldungen mittels docker logs ausgegeben werden, also für das Backend mit

  docker logs items-backend

und für die Web-Application mit

  docker logs items-webapp

sofern Sie die empfohlenen Container-Namen verwenden; anderenfalls müssen Sie in den beiden obigen Zeilen den jeweils von Ihnen verwendeten Container-Namen einsetzen.

Entweder wurde das Backend mehrfach gestartet oder während einem Datenbank-Upgrade beendet. Stellen Sie sicher, dass Sie nur eine einzige Instanz des Backends pro Datenbank starten.

Sollten die Meldungen trotzdem ausgegeben werden, müssen Sie die Sperre manuell löschen. Dazu beenden Sie den Backend-Container und geben als root foldendes ein:

  su postgres -c psql items3
  delete from databasechangeloglock;
  \q

Anschließend kann das Backend wieder wie gewohnt gestartet werden.

Haben Sie ITEMS so konfiguriert, dass ein externer Anmeldeservice verwendet wird, erscheint diese Meldung nach Eingabe eines Benutzernamens und Kennworts, wenn sich Datum und Uhrzeit des Servers, auf dem das ITEMS-Backend läuft, und des Servers, auf dem der Anmeldeservice läuft, zu stark unterscheiden.

• Bitte prüfen Sie Datum und Uhrzeit auf beiden Servern (geben Sie man 1 date am Prompt ein).
• Bitte verwenden Sie ein Programm zur Synchronisation der Uhrzeit, z.B. ntpdate.

Bitte prüfen Sie zunächst, ob es sich um ungewöhnlich lange laufende Abfragen handelt, oder um ungewöhnlich viele Zugriffe.

Dazu starten Sie psql mit einem Superuser-Account, z.B. folgendermaßen:

  su postgres
  PAGER="less -S" psql items3

Anschließend können Sie sich die gerade laufenden Abfragen anzeigen lassen, indem Sie folgendes eingeben:

  SELECT pid, query_start, query
  FROM pg_stat_activity
  WHERE query != '';

In der Spalte query_start wird der Startzeitpunkt der Abfrage angezeigt. Liegt dieser länger als wenige Minuten zurück, so ist das vermutlich der Auslöser. Bitte leiten Sie die Ausgabe in der Spalte query an Factor3 weiter, möglichst unter Angabe, was genau auf der Oberfläche gemacht wurde, um diese Abfrage auszulösen.

Anschließend können Sie die Abfrage beenden, indem Sie folgendes eingeben:

  SELECT pg_cancel_backend(pid);

wobei Sie pid durch den Wert in selbiger Spalte in der vorher ausgegebenen Tabelle ersetzen müssen.

Um alle Abfragen zu beenden, die länger als 30 Minuten laufen, können Sie folgendes eingeben - beachten Sie aber bitte, dass sämtliche Abfragen beendet werden, ohne irgendeine Prüfung!

  SELECT pg_cancel_backend(pid)
  FROM pg_stat_activity
  WHERE query != '' AND
    query_start <= current_timestamp - interval '30 minutes';

Sollte keine lange laufende Abfrage zu finden sein, so werden vermutlich ungewöhnlich viele Zugriffe an den ITEMS-Server abgesetzt. Am einfachsten können Sie dies prüfen, indem Sie die Datei /var/log/apache2/access.log auswerten.

Prinzipiell kann es zwei Ursachen für eine ungewöhnlich hohe CPU-Last geben:

1. ein Thread, der mit einer langen Berechnung beschäftigt ist oder gar in einer Endlosschleife läuft,
2. oder viele gleichzeitige Zugriffe, die einen unoptimierten Code-Pfad durchlaufen.

Selbstverständlich sollte dies im Betrieb nicht auftreten, und Probleme dieser Art werden von uns umgehend beseitigt, sobald wir die genaue Ursache kennen. Dazu sind wir aber auf Ihre Mithilfe angewiesen.

Um zunächst festzustellen, welche Threads gerade mit welchem Code beschäftigt sind, loggen Sie sich auf dem Server (z.B. mittels ssh) ein, und führen Sie als root folgendes aus, sofern das Backend betroffen ist:

  docker exec items-backend /bin/sh -c 'kill -QUIT 1'
  docker logs items-backend

Wenn die Web-Application betroffen ist, ersetzen Sie bitte in beiden obigen Zeilen items-backend durch items-webapp. In jedem Fall übermitteln Sie bitte die Ausgabe der obigen Befehle an uns.

Wenn Sie Fehlermeldungen von ITEMS bekommen (z.B. als Email oder im Fehler-Protokoll), die "hostname:389" (z.B. localhost:389) beinhalten, handelt es sich um Probleme mit dem LDAP-Server. Die tatsächlichen Fehlermeldungen des LDAP-Servers finden Sie in /var/log/syslog bzw. in /var/log/messages (SuSE-Linux).

Wenn Sie OpenLDAP als LDAP-Server verwenden, können Sie diesen neu starten. Dazu melden Sie sich als Benutzer root auf dem Server an, auf dem OpenLDAP läuft, und geben folgendes ein:

• Übliche Linux-Distributionen: /etc/init.d/slapd restart
• SuSE-Linux: /etc/init.d/ldap restart

Grundsätzlich können Sie alle Dienste in beliebiger Reihenfolge starten - die ITEMS-Oberfläche erkennt selbständig, sobald ein ITEMS-Backend zur Verfügung steht, und das ITEMS-Backend stellt selbständig Verbindungen zur Datenbank her, sobald dies möglich ist.

Damit ITEMS aber sofort einsatzbereit ist, sollten die Datenbank zuerst verfügbar sein, gefolgt vom Backend, woraufhin auch die Web-Application gestartet werden kann.

Wollen Sie zum Beispiel die Datenbank von einem Produktivsystem auf Ihr Testsystem übernehmen, können Sie das Skript copy-database verwenden, das in der begleitenden Distribution zum Backend zur Verfügung steht.

Dazu verbinden Sie sich zuerst mit dem System, auf das die Datenbank übernommen werden soll. Beachten Sie bitte, dass die Datenbank auf diesem System, sofern vorhanden, unwiederbringlich gelöscht wird!

Stellen Sie sicher, dass Sie sich mit dem Produktivsystem mittels ssh verbinden können, indem Sie ssh HOST eingeben, wobei Sie HOST durch den Hostnamen des Systems ersetzen, von dem Sie die Datenbank kopieren möchten. Sollte das funktionieren, beenden Sie diese Verbindung wieder mit der Eingabe von exit.

Anschließend können Sie die Datenbank von diesem System übernehmen, indem Sie ./copy-database HOST eingeben. Ersetzen Sie HOST wieder wie zuvor.