Hier finden Sie Antworten auf Fragen und Probleme, die bei der Installation und während dem Betrieb von ITEMS auftreten können.
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
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.
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.
Variable | Bedeutung |
---|---|
JAVA_OPTS |
Voreinstellung:
Standard-Java-Optionen, die an |
Datenbank-Einstellungen |
|
javax_persistence_jdbc_driver |
Voreinstellung: Klassenname des zu verwendenden JDBC-Treibers. |
javax_persistence_jdbc_url |
Voreinstellung: URL für die Verbindung zur Datenbank. |
javax_persistence_jdbc_user |
Voreinstellung: Benutzername für die Datenbank. |
javax_persistence_jdbc_password |
Voreinstellung: Passwort für die Datenbank. |
eclipselink_connection__pool_default_max |
Voreinstellung: Maximale Anzahl an Datenbankverbindungen im Verbindungspool. Dieser Wert sollte geringer sein als die maximale Anzahl an Verbindungen, die der Datenbank-Server zulässt, falls auch andere Benutzer bzw. Fremdsysteme gleichzeitig mit ITEMS auf die Datenbank zugreifen. |
RMI-Einstellungen |
|
listenAddress |
Voreinstellung:
Die Adresse der Schnittstelle, an die die RMI-Registry und die
Anwendung selbst gebunden werden, oder |
listenRegistryPort |
Voreinstellung: Der Port, an den die RMI-Registry gebunden wird. |
listenApplicationPort |
Voreinstellung:
Der Port, an den die Anwendung gebunden wird. Ist dieser Wert nicht
oder auf |
publishApplicationAddress |
Voreinstellung: keine Jedes Frontend (wie z.B. die Web-Applikation) wird angewiesen, sich an diese Adresse zu verbinden, sobald ein Objekt in der RMI-Registry aufgelöst wurde. Wenn kein Wert gesetzt ist, verwendet das Frontend die Adresse, die es auch für Verbindungen zur RMI-Registry verwendet. |
publishApplicationPort |
Voreinstellung: keine Jedes Frontend (wie z.B. die Web-Applikation) wird angewiesen, sich an diesen Port zu verbinden, sobald ein Objekt in der RMI-Registry aufgelöst wurde. Wenn kein Wert gesetzt ist, wird der von Java RMI vorgegebe Port verwendet. |
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.
Variable | Bedeutung |
---|---|
CATALINA_OPTS |
Voreinstellung:
Standard-Java-Optionen, die an |
RMI-Einstellungen, um das Backend zu erreichen |
|
registryAddress |
Voreinstellung:
Die Adresse, unter der die RMI-Registry des Backends erreichbar ist;
siehe Umgebungsvariable |
registryPort |
Voreinstellung:
Die Adresse, unter der die RMI-Registry des Backends erreichbar ist;
siehe Umgebungsvariable |
RMI-Einstellungen für die Web-ApplicationDie Web-Application kann asynchrone Events vom Backend empfangen und agiert dann als RMI-Server. Die folgenden Einstellungen legen die Parameter für diese Funktionalität fest. |
|
listenAddress |
Voreinstellung:
Die Adresse der Schnittstelle, an die die RMI-Registry und die
Anwendung selbst gebunden werden, oder |
listenRegistryPort |
Voreinstellung: Der Port, an den die RMI-Registry gebunden wird. |
listenApplicationPort |
Voreinstellung:
Der Port, an den die Anwendung gebunden wird. Ist dieser Wert nicht
oder auf |
publishApplicationAddress |
Voreinstellung: keine Das Backend wird angewiesen, sich an diese Adresse zu verbinden, sobald ein Objekt in der RMI-Registry aufgelöst wurde. Wenn kein Wert gesetzt ist, wird die von Java RMI vorgegebe Adresse verwendet. |
publishApplicationPort |
Voreinstellung: keine Das Backend wird angewiesen, sich an diesen Port zu verbinden, sobald ein Objekt in der RMI-Registry aufgelöst wurde. Wenn kein Wert gesetzt ist, wird der von Java RMI vorgegebe Port verwendet. |
Ü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.
listen_addresses
in
postgresql.conf
), und
pg_hba.conf
).
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;
}
}
Administration
→
Management-Dienst
→
Oberflächen-Cluster
jndi.java.naming.provider.url
den Pfad
entsprechend eintragen, z.B.
"ldap://localhost/ou=restricted,ou=persons,dc=hostname"
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.
cn=items,ou=roles,dc=mydomain,dc=de
zur Anmeldung zuzulassen,
wird etwa aus
(&(objectClass=organizationalPerson)(sn={0}))
(&(objectClass=organizationalPerson)(sn={0})(memberof=cn=items,ou=roles,dc=mydomain,dc=de))
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.
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:
.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./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.
man 1 date
am Prompt ein).
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:
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:
/etc/init.d/slapd restart
/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.