Einrichtung von Docker-Containern

Der i-net HelpDesk kann in einem Docker Container verwendet werden. Es gibt einen vorgefertigten Container, der auf einer alpine-Version auf Docker Hub basiert. Der Container bringt nur die Anwendung und die Tools mit, die zum Ausführen der Anwendung benötigt werden.

Hinweis: Der Container stellt keine Standardbenutzer zur Verfügung. Sie müssen sich via Registrieren zunächst anmelden. Siehe unten für fortgeschrittene Anwendungsfälle.

Schnellstart

Führen Sie den folgenden Befehl aus, um einen i-net HelpDesk Docker Container zu starten:

docker run -d -p 8002:8002 --name helpdesk inetsoftware/i-net-helpdesk

Hinweis: Für den Betrieb von i-net HelpDesk ist eine Datenbank erforderlich. Sie können MySQL/MariaDB, Oracle oder MSSQL verwenden. Ein Beispiel für die Verwendung von MySQL in einem parallelen Container finden Sie unten.

Verfügbare Tags

Erstellen einer voreingestellten Konfiguration

Der i-net HelpDesk Docker Container sollte entweder über eine Konfigurations-Eigenschaftsdatei oder über Umgebungsvariablen vorkonfiguriert werden. In beiden Fällen sollte zunächst eine lokale Installation mit der spezifischen Konfiguration erstellt werden. Mit Hilfe des Maintenance-Moduls kann ein Backup der Konfiguration erstellt werden und die darin enthaltene Configuration-Properties-Datei kann als Grundlage verwendet werden.

Hinweis: Um den Container beim Start vollständig einzurichten, müssen mindestens die folgenden Eigenschaften angegeben werden: CONF_listener__port und CONF_licensekey

Hinweis: In privaten Cloud-Umgebungen müssen Sie auch die Eigenschaft CONF_serverURL festlegen. Es wird empfohlen, diese Eigenschaft auch in anderen Umgebungen zu setzen.

Hinzufügen der Konfiguration

Eine Konfigurationsdatei kann mit Hilfe eines Volumes oder einer anderen Methode hinzugefügt werden, die dem Container eine bestimmte Konfiguration hinzufügt. Es kann die Standardkonfigurationsdatei verwendet werden oder eine andere über eine Umgebungsvariable gesetzt werden. Siehe Umgebungseigenschaften-Matrix.

Einrichten der Konfiguration mit Umgebungsvariablen

Um die Namen der Umgebungsvariablen zu erstellen, verwenden Sie die folgende Regel:

  • Präfix CONF__ für die Eigenschaft
  • Ersetzen Sie jeden . (Punkt) durch __ (zwei Unterstriche)

Um die Konfiguration reproduzierbar und aktualisierbar zu machen, sollten Sie eine docker-compose.yml-Datei verwenden.

Beispiel

version: '2.1'

services:

    helpdesk:
        image: 'inetsoftware/i-net-helpdesk:latest'
        restart: 'always'
        ports:
            - 8002:8002

        environment:
            - DEFAULT_PROPFILE=/tmp/defaultConfiguration.properties
            - DEFAULT_CONFIG=User/Default
 
            # Setzen Sie die extern sichtbare Server-Url ="../../../../../entfernen-Sie-den-Kommentar-und-fuegen-Sie-die-korrekte-Url-ein"
            #- CONF_serverURL=https://hostname.company.com:8002/
 
            # Setzen Sie den Lizenzschluessel (entfernen Sie den Kommentar und geben Sie den vollstaendigen Lizenzschluessel ein)
            #- CONF_licensekey=...
 
            # Fuehren Sie die Anwendung auf einem vorher festgelegten Port aus, um die Zuordnung zu erleichtern.
            - CONF_listener__port=8002
 
            # Anpassen einer Option, z. B. der Themenfarben
            - CONF_theme__themecolors={"@base-color":"#123456","@primary-color":"#428bca"}
 
            # Aktivieren der Protokollierung, Weiterleitung des Protokolls an die Container-Log-Datei
            - CONF_log__engine=true
            - CONF_log__file=/dev/stdout
 
            # Standort fuer automatische Backups
            - CONF_BackupLocation=/home/helpdesk/.i-net software/helpdesk_User_Default/backup

Erweiterter Anwendungsfall

Wenn es spezifischere Anforderungen gibt, wie z.B. eine vorausgefüllte Benutzerdatenbank, sollte ein benutzerdefinierter Container erstellt werden

Beispiel: Interner Zugriff mit öffentlichem Konto

Mit dem folgenden Compose-Beispiel können Sie einen Server erstellen, der ohne jegliche Berechtigungseinschränkungen gestartet wird und ohne weitere Authentifizierung über den öffentlichen URL-Kontext verwendet werden kann.

version: '2.1'

services:

    helpdesk:
        image: 'inetsoftware/i-net-helpdesk:latest'
        restart: 'always'
        ports:
            - 8002:8002

        environment:
            - DEFAULT_CONFIG=User/Default
 
            # Setzen Sie den Lizenzschluessel (entfernen Sie den Kommentar und geben Sie den vollstaendigen Lizenzschluessel ein)
            #- CONF_licensekey=...
 
            # Fuehren Sie die Anwendung auf einem vorher festgelegten Port aus, um die Zuordnung zu erleichtern.
            - CONF_listener_ _port=8002
 
            # Nur das Gastkonto ist aktiv.
            - CONF_authentication__settings=[{"provider"\:"guest"}]

Beispiel: Hinzufügen der PAM-Authentifizierung und eines Standardbenutzers

Das folgende Dockerfile wird einen Benutzer admin mit dem Passwort password in einem neuen Container anlegen.

FROM inetsoftware/i-net-helpdesk
 
# Fuer die Installation zum Benutzer root wechseln
USER root
 
# Tools
RUN apk add --update linux-pam
 
# pam-Berechtigungen fuer alle erteilen
# Benutzer erstellen, mit dem wir uns anmelden koennen
RUN chmod +r /etc/shadow \
    && adduser -D -g "User" admin \
    && echo admin:password | chpasswd \
    && ln -s "/etc/pam.d/base-password" "/etc/pam.d/helpdesk"
 
# Die System-Anmeldung aktivieren. Per Default ist das PAM Plugin deaktiviert.
ENV CONF_authentication__settings="[{'provider':'system'},{'provider':'product','userCanRegister':'true'}]"
ENV CONF_plugins__activated="{}"
 
# Zurueck zum Produktbenutzer wechseln
USER helpdesk

Einhängen / Wiederverwendung einer gegebenen Konfiguration

Sollen die Daten des Containers über Neustarts hinaus persistiert werden, z.B. für neue Containerversionen, sollte ein Volume gemountet werden.

Die Persistenz und Konfiguration befindet sich im Home-Ordner des Produktbenutzers. Um diesen Ordner zu mounten, sollten Sie die folgenden zusätzlichen Optionen verwenden:

-v /folder/to/mount/from:/home/$PRODUCT -e FORCE_IMPORT_CONFIG=0
  • -v /folder/to/mount/from:/home/$PRODUCT - den spezifischen Ordner in den Heimatordner des Produktbenutzers einbinden
  • -e FORCE_IMPORT_CONFIG=0 - angeben, dass die angegebene Konfiguration nicht überschrieben werden soll

Hinweis: Der Produktbenutzer hängt von dem Produkt ab, das Sie verwenden. Er wird durch die Variable $PRODUCT im Container bestimmt. Mögliche Werte sind: reporting, pdfc, cowork und helpdesk.

Hinzufügen zusätzlicher Schriftarten

Im Standardcontainer ist z. B. die Schriftart DejaVu vorinstalliert. Das Hinzufügen zusätzlicher Schriftarten, wie z. B. der lizenzbeschränkten Microsoft-Schriftart Arial, erfordert die Erstellung eines eigenen Containers. Sie können das folgende Dockerfile als Grundlage verwenden.

#############################################################################
# Prepare product
# Note: alpine 3.12 due to issue with newer versions of alpine!
FROM alpine:3.12 as builder
 
RUN apk add --update msttcorefonts-installer \
    && update-ms-fonts
 
FROM inetsoftware/i-net-<PRODUCT>:<TAG>
 
USER "root"
 
# Kopieren von Schriftarten aus dem Intermediate Builder
COPY --from=builder /usr/share/fonts/truetype/msttcorefonts /usr/share/fonts/truetype/msttcorefonts
 
# Update font cache for product user
USER $PRODUCT
RUN fc-cache -fv /usr/share/fonts

Umgebungseigenschaften-Matrix

Property Name Default Value Description
DEFAULT_PROPFILE /tmp/defaultConfiguration.properties Configuration Properties file for initial setup
DEFAULT_CONFIG User/Default Configuration the server will be started with
FORCE_IMPORT_CONFIG 1 Forces the import of the given configuration, overwriting an already existing one. Set to 0 if a configuration is mounted.
DOCKER_ENTRYPOINT_SCRIPT Additional inline-script to run before starting the server
CONF_systempermission__enabled false The system permissions are deactivated by default. That means any user with a login has access to everything in the system. This property should be customized together with the authentication settings.
CONF_authentication__settings [{'provider':'product','userCanRegister':'true'}] The product login is activated by default and allows new users to be created. This should be customized in a production environment.
CONF_plugins__activated {'authentication.pam':false} The PAM authentication plugin is deactivated by default, because you have to create custom container in order to use it. Only optional plugins have to be enabled with the value true using this settings. To deactivate a non-optional plugin, use the value false.
CONF_prop__name Configuration property for server initialization. prop__name was derived from an actual property prop.name which can be taken from a previous backup.
inet_http_port Set a default HTTP port that overrides the one in the configuration. This is intended for shared cloud persistences
inet_https_port Set a default HTTPS port that overrides the one in the configuration. This is intended for shared cloud persistences
inet_persistence URI of the persistence to use. Currently on MongoDB is supported. Will uses the file persistence if not set.

Docker Compose Beispiel

Um einen Docker-Container mit einer MySQL-Datenbank unter Verwendung von Docker Compose zu bündeln, kann das folgende Skript docker-compose.yml als Ausgangspunkt verwendet werden:

version: '2.1'

services:

    helpdesk:
        image: 'inetsoftware/i-net-helpdesk:latest'
        restart: 'always'
        ports:
            - 8002:8002
        links:
            # Verbinden Sie sich mit der vorbereiteten MySQL-Datenbank
            - 'mysql'
        command:
            # Mit dem folgenden wait-for.sh-Befehl kann der Dienst darauf warten, dass ein externer Dienst verfuegbar wird
            - sh
            - wait-for.sh
            - mysql:3306
            - --
            # Nachdem der MySQL Server gestartet wurde, starten Sie den eigentlichen i-net HelpDesk Server
            - sh
            - ./startServer.sh
            - -Dclearreports.config=User/Default
            - -Dsetupautoexecution=true

        environment:
            - DEFAULT_CONFIG=User/Default
 
            # Setzen Sie die extern sichtbare Server-Url ="../../../../../entfernen-Sie-den-Kommentar-und-fuegen-Sie-die-korrekte-Url-ein"
            #- CONF_serverURL=https://hostname.company.com:9443/
 
            # Setzen Sie den Lizenzschluessel (entfernen Sie den Kommentar und geben Sie den vollstaendigen Lizenzschluessel ein)
            #- CONF_licensekey=...
 
            # Fuehren Sie die Anwendung auf einem vorher festgelegten Port aus, um die Zuordnung zu erleichtern.
            - CONF_listener__port=8002
 
            # Einrichten der Verbindung zur MySQL-Datenbank
            - CONF_dbsConfigs=[{"status":"Unknown","dbName":"HDS","url":"jdbc:mysql://mysql:3306/inetHDOfficial?useSSL=false&allowPublicKeyRetrieval=true","user":"root","encodedPassword":"AU1KQVA=","host":"mysql","port":"3306","sid":"","catalog":"inetHDOfficial","driver":"mysql"}]

    mysql:
        image: 'mysql:8'
        restart: 'always'
        environment:
            - MYSQL_ROOT_PASSWORD=inet
            - MYSQL_DATABASE=inetHDOfficial
            - MYSQL_USER=inetHDOfficial
            - MYSQL_PASSWORD=inet
        volumes:
            - "/var/lib/mysql"

Hinweis: Abhängig von der jeweiligen Umgebung müssen möglicherweise noch weitere Optionen eingestellt werden. Bitte werfen Sie einen Blick auf die Umgebungseigenschaften-Matrix.

Installieren zusätzlicher Plugins

Zusätzliche Plugins können dem Docker-Container entweder während eines benutzerdefinierten Dockerfile-Builds oder "on the fly" während des Container-Starts hinzugefügt werden. In beiden Fällen können Sie den Befehl install-plugin des Containers verwenden:

/usr/share/product $ install-plugin --help
Usage install all Plugins: /bin/install-plugin -p <product> -v <version>
Usage install defined plugins: /bin/install-plugin -p <product> -v <version> <list of plugins to install>
Usage install BETA Plugins: /bin/install-plugin -p <product> -v <version> -b <list of plugins to install>
Usage install additional persistence: /bin/install-plugin -s <type>

Hinweis: Plugin-Namen können z.B. von der URL des Plugin-Speichers abgeleitet werden, insbesondere von der Pfadkomponente nach /pid: https://store.inetsoftware.de/pid/webapi.corewebapi.core

Hinweis: Für jeden Persistenz-Typ gibt es unterschiedliche Container. Die MongoDB-Persistenz wird im Standardcontainer installiert, der kein zusätzliches Tag hat. Verfügbare Persistenzen sind: mongodb, cosmosdb, dynamodb.

Dockerfile Beispiel

In einem Dockerfile können Sie die folgenden Zeilen hinzufügen, um ein Plugin zu installieren:

# Add Web API plugin 
RUN install-plugin web.api

Docker Compose Beispiel

In einer docker-compose.yml können Sie das folgende Setup verwenden, um ein Plugin zu installieren:

version: '2.1'
services:
    service:
        command: >
            sh -c "
            install-plugin web.api &&
            ./startServer.sh -Dclearreports.config=User/Default -Dsetupautoexecution=true
            "

Hinweis: Der ursprüngliche startServer.sh-Befehl kann mit docker inspect bei einem bereits laufenden Container ermittelt werden.

Hinweis: Das Beispiel ist unvollständig und erfordert die Definition des spezifischen Containers.

Neustart des Dienstes

In Situationen, in denen der Dienst nicht mehr reagiert, der Container aber noch erreichbar ist, kann der Unterprozess des Servers beendet und neu gestartet werden, ohne den gesamten Container neu zu starten. In diesem Fall muss der Benutzer den Container über die Shell betreten und den folgenden Befehl ausführen:

ps xo pid,command | grep exitcode | grep -v grep | awk '{print $1}' | xargs -r kill -TERM