Installation
Die Installation des MV-Tools ist recht einfach, besonders wenn Ihr Server die AMD64- oder die ARM64-Architektur verwendet. In diesem Fall können Sie das Docker-Image direkt von Docker Hub herunterladen. Wenn Ihr System jedoch eine andere Architektur verwendet, wenden Sie sich bitte an die Condify GmbH.
docker pull hutschen/mv-tool:latest
Erstellen der Konfigurationsdatei
Bevor Sie das MV-Tool in einem Docker-Container ausführen können, ist eine
Konfiguration erforderlich. Dazu wird eine Konfigurationsdatei benötigt. Für die
minimale Konfiguration können Sie den folgenden Inhalt in eine Datei namens
config.yml
schreiben:
jira:
url: http://localhost:2990/jira
database:
url: sqlite:///mvtool.db
Bemerkung
Ersetzen Sie bitte http://localhost:2990/jira
durch die URL Ihrer
JIRA-Instanz.
Falls Sie über keine JIRA-Instanz verfügen, können Sie das MV-Tool auch ohne
JIRA-Integration verwenden. In diesem Fall können Sie den Abschnitt jira
aus
der Konfigurationsdatei entfernen und stattdessen eine
Verbindung zu einem LDAP-Verzeichnisdienst herstellen.
Verbindung zu JIRA herstellen
Um eine Verbindung zu JIRA herzustellen, geben Sie die URL Ihrer JIRA-Instanz in
der Datei config.yml
ein.
Bemerkung
Es kann nötig sein, /jira
an das Ende der URL anzuhängen. Falls Probleme
bei der initialen Verbindung auftreten, versuchen Sie es mit dem Anhängen
von /jira
an die URL.
HTTPS/SSL
Wenn Ihre JIRA-Instanz ein selbstsigniertes Zertifikat verwendet und Sie eine
HTTPS-Verbindung zu JIRA verwenden möchten, dann müssen Sie in der
Konfigurationsdatei config.yml
zusätzlich zur URL auch die Option
verify_ssl
hinzufügen. Diese Option muss im jira
-Abschnitt der Datei
hinzugefügt und auf false
gesetzt werden.
Verbindung zu LDAP herstellen
Wenn Ihnen keine JIRA-Instanz zur Verfügung steht oder Sie zusätzlich Nutzern, die JIRA nicht verwenden, den Zugriff auf das MV-Tool ermöglichen möchten, können Sie eine Verbindung zu einem LDAP-Verzeichnisdienst herstellen.
Bei der Anmeldung eines Nutzers am MV-Tool wird das MV-Tool zunächst versuchen, den Nutzer gegenüber dem LDAP-Verzeichnisdienst zu authentifizieren. Falls dies nicht erfolgreich ist, versucht das MV-Tool, den Nutzer gegenüber JIRA zu authentifizieren, sofern eine Anbindung an JIRA konfiguriert ist.
Die folgenden Konfigurationsparameter können in der config.yml
-Datei
angegeben werden, um eine Verbindung zu einem LDAP-Server herzustellen:
ldap:
protocol: ldap
port: 389
host: localhost
account_dn: uid=search,cn=users,dc=example,dc=com
account_password: password
base_dn: dc=example,dc=com
user_filter: (objectClass=person)
attributes:
login: uid
firstname: givenName
lastname: sn
email: mail
attributes_encoding: utf-8
Die folgende Tabelle erklärt die einzelnen Konfigurationsparameter im Detail:
Parameter |
Beschreibung |
Erforderlich |
---|---|---|
|
Das Protokoll für die Verbindung mit dem LDAP-Server. Dieses kann entweder
|
|
|
Der Hostname oder die IP-Adresse des LDAP-Servers. |
Ja |
|
Der Port des LDAP-Servers. Wenn nicht angegeben, wird der Port automatisch
auf |
|
|
Die Überprüfung des SSL-Zertifikats des Servers. Dieser Parameter ist nur
relevant, wenn |
|
|
Der Distinguished Name (DN) des Kontos, das für die Bindung an den LDAP-Server verwendet wird. Dieser Parameter wird nur benötigt, wenn der LDAP-Server eine Authentifizierung erfordert, um Suchanfragen nach Nutzern auszuführen. |
|
|
Das Passwort des Kontos, das für Suchanfragen verwendet wird. Dies ist nur
erforderlich, wenn |
Bedingt |
|
Der Base Distinguished Name, von dem aus die LDAP-Suche beginnt. |
Ja |
|
Der Filter zum Einschränken der Benutzersuche im LDAP-Verzeichnis. |
|
|
Siehe Mapping von LDAP-Attributen für weitere Informationen. |
Ja |
|
Die Zeichenkodierung der Werte der LDAP-Attribute. Standardmäßig |
Mapping von LDAP-Attributen
Die attributes
-Konfiguration wird verwendet, damit das MV-Tool Nutzerdaten
aus dem LDAP-Verzeichnis abfragen kann. Die folgende Tabelle zeigt die möglichen
Attribute und deren Bedeutung:
Parameter |
Beschreibung |
Erforderlich |
---|---|---|
|
LDAP-Attribut für den Benutzerlogin (z.B. |
Ja |
|
LDAP-Attribut für den Vornamen des Benutzers. |
|
|
LDAP-Attribut für den Nachnamen des Benutzers. |
|
|
LDAP-Attribut für die E-Mail-Adresse des Benutzers. |
Siehe auch
Für eine allgemeine Einführung in die Konfiguration von LDAP-Anbindungen und die Authentifizierung von Benutzern wird der Blog-Beitrag „LDAP Anbindung am Beispiel von Redmine“ empfohlen.
Datenbankverbindung herstellen
Das MV-Tool unterstützt SQLite und PostgreSQL als Datenbanken. Für den
produktiven Einsatz wird PostgreSQL empfohlen. In der config.yml
-Datei geben
Sie die URL zu Ihrer Datenbank ein.
SQLite
Die folgende Konfiguration zeigt, wie eine Verbindung zu einer SQLite-Datenbank hergestellt wird:
database:
url: sqlite:///mvtool.db
Die Datenbankdatei mvtool.db
wird automatisch erstellt, wenn sie nicht
vorhanden ist.
Siehe auch
Das MV-Tool verwendet SQLAlchemy für die Datenbankverbindung. Daher muss die Datenbank-URL dem SQLAlchemy-Format entsprechen. Zusätzliche Informationen zur SQLite-Datenbank-URL finden Sie in der SQLAlchemy Dokumentation.
PostgreSQL
Die folgende Konfiguration zeigt, wie eine Verbindung zu einer PostgreSQL-Datenbank hergestellt wird:
database:
url: postgresql+psycopg2://user:password@localhost:5432/mvtool
Siehe auch
Für Verbindungen zu PostgreSQL-Datenbanken wird der Treiber psycopg2 verwendet. Zusätzliche Informationen zur PostgreSQL-Datenbank-URL finden Sie in der SQLAlchemy Dokumentation.
Logging
Bemerkung
Die Logging-Konfiguration ist optional. Wenn Sie keine Logging-Konfiguration benötigen, können Sie diesen Abschnitt überspringen oder direkt zum Abschnitt Start des Docker-Containers springen.
Das Logging dient zur Identifizierung möglicher Fehler im MV-Tool, die in
zukünftigen Versionen behoben werden können. Sie können die Logs entweder direkt
über den Befehl docker logs
abrufen oder Sie speichern diese in einer Datei
innerhalb des Docker-Containers.
Einstellen des Log-Levels
Der Log-Level bestimmt, welche Arten von Meldungen protokolliert werden. Es
stehen die Werte debug
, info
, warning
, error
und critical
zur Verfügung. Wenn Sie den Log-Level auf error
setzen, werden zum Beispiel
alle Meldungen mit dem Log-Level error
und critical
protokolliert. Das
voreingestellte Log-Level ist error
.
uvicorn:
log_level: error
Verwenden einer Log-Datei
Wenn Sie möchten können Sie die Log-Nachrichten in eine Datei schreiben. Dazu
müssen Sie den log_filename
Parameter in der config.yml
-Datei
hinzufügen.
uvicorn:
log_level: error
log_filename: mvtool.log
Der Log-Dateiname (zum Beispiel mvtool.log
) legt den Namen der Datei fest,
in die die Log-Nachrichten geschrieben werden. Die Datei wird innerhalb des
Docker-Containers unter dem Pfad /usr/src/api/
erzeugt und die Log-Einträge
werden an eine bestehende Datei angehängt.
Um Zugriff auf die Log-Datei auch außerhalb des Containers zu erhalten, muss ein Bind-Mount zwischen dem Host-System und dem Docker-Container erstellt werden.
Erstellen Sie zunächst eine leere Log-Datei auf dem Host-System und binden Sie
diese beim Start des Docker-Containers mittels des -v
Parameters des
docker container create
Befehls ein. Achten Sie darauf, dass der Pfad zur
Log-Datei auf dem Host-System und der Pfad im Docker-Container übereinstimmen
und dass der Docker-Container Schreibrechte auf die Datei hat.
touch mvtool.log
docker container create --name mv-tool -p 4200:8000 -v mvtool.log:/usr/src/api/mvtool.log hutschen/mv-tool
Secret für Authentifizierungs-Token
Bemerkung
Die Definition eines eigenen Secrets ist optional. Wenn Sie dies nicht wünschen, können Sie diesen Abschnitt überspringen oder direkt zum Abschnitt Start des Docker-Containers springen.
Das MV-Tool nutzt Authentifizierungs-Token zur sicheren Speicherung von Nutzersitzungen im Browser des Nutzers. Um diese Token zu erstellen, wird ein Secret benötigt, welches das MV-Tool standardmäßig bei jedem Start neu generiert. Dies führt allerdings dazu, dass alle bestehenden Nutzersitzungen bei einem Neustart des MV-Tools ungültig werden.
Um diese Ungültigkeit zu verhindern, können Sie ein festes, eigenes Secret einsetzen, welches sich bei Neustarts des MV-Tools nicht ändert.
Um ein eigenes Secret in der config.yml
-Datei zu verwenden, geben Sie dieses
im Abschnitt auth
wie folgt an:
auth:
secret: "my-secret"
Sie können ein solches Secret mit folgendem Befehl generieren, falls openssl
auf Ihrem System installiert ist:
openssl rand -hex 32
Falls openssl
nicht auf Ihrem System installiert ist, können Sie auch einen
beliebigen Passwort-Generator verwenden. Wichtig ist nur, dass das Secret eine
Mindestlänge von 32 Byte hat und zufällig generiert wurde.
Start des Docker-Containers
Nach der Konfiguration können Sie den Docker-Container starten. Dabei kopieren Sie die Konfigurationsdatei vor dem Start in den Container. Das folgende Kommando startet den Docker-Container:
docker container create --name mv-tool -p 4200:8000 hutschen/mv-tool
docker container cp config.yml mv-tool:/usr/src/api/config.yml
docker container start mv-tool
Der Docker-Container ist dann unter http://localhost:4200 erreichbar.