Docker-Installation (Unix)#

Dieses Handbuch beschreibt, wie Allegra auf Unix-basierten Systemen mit Docker Compose installiert und ausgeführt wird.

Mit Docker Compose verwenden Sie eine Konfigurationsdatei, bekannt als Compose-Datei, um die Services, die Allegra braucht, zu konfigurieren. Die Allegra-Anwendung verwendet zwei Container für die Services: einen für die Datenbank sowie einen für die Anwendung selbst. Jeder Container braucht mindestens ein Image. In unserem Fall ist es das Allegra-Image mit einem Servlet-Container (einer Art Webserver) sowie ein Image für den standardmäßigen PostgreSQL-Datenbank-Server.

Achtung

Diese Installationsanleitung beinhaltet nicht alle Maßnahmen, die erforderlich werden, wenn die Anwendung zum Internet hin geöffnet werden soll.

Vorbereitung#

Stellen Sie vor der Installation sicher, dass Folgendes vorhanden ist:

Unix-basiertes System (Docker OS-Unterstützung)
Docker Engine und Docker Compose sind installiert und laufen (Docker installieren)
Ausreichend Speicherplatz (mindestens 20 GB)
Verfügbarer Netzwerkport (Standard 8080 oder selbst konfiguriert)
Benutzerkonto mit Berechtigung zur Ausführung von Docker-Befehlen (sudo oder Mitglied der docker-Gruppe)

Bemerkung

Alle Allegra-Daten – Konfiguration, Anhänge und Protokolle – werden außerhalb der Docker-Container in dem persistenten Host-Ordner gespeichert, den Sie bei der Konfiguration als ALLEGRA_HOME_DIR festlegen und der im Container unter /home/allegra eingebunden ist.

Installationsschritte#

Führen Sie die folgenden Schritte aus, um Allegra mit Docker Compose zu installieren und zu starten.

Erstellen Sie das Allegra-Home-Verzeichnis

Erstellen Sie auf Ihrem Host-System (dem Rechner, auf dem der Docker Container läuft) ein Verzeichnis, in dem Allegra seine Daten speichert. Dieses Verzeichnis wird in dieser Anleitung als ALLEGRA_HOME bezeichnet.
```
sudo mkdir -p /home/ubuntu/allegra-home
sudo chmod 750 /home/ubuntu/allegra-home
sudo chown -R 999:999 /home/ubuntu/allegra-home
```
Bemerkung

ls zeigt die Gruppe möglicherweise als systemd-journal statt 999 an (auf vielen Ubuntu-Hosts ist die GID 999 dieser Gruppe zugeordnet). Das ist rein kosmetisch — Allegra verwendet die numerische ID, behalten Sie daher 999:999 bei.
Laden Sie das Allegra-Docker-Paket herunter

Laden Sie das neueste vorgepackte Allegra-Docker-Bundle von der Allegra-Downloadseite herunter in Ihr aktuelles Arbeitsverzeichnis oder irgendwo anders, wo Sie Schreibrechte besitzen und von wo aus Sie das Container-System später starten wollen.
```
wget https://alltena.com/downloads/allegra/latest-dist/allegra-docker.zip
```
Entpacken Sie das Archiv
```
unzip allegra-docker.zip
cd allegra-docker
```
Das entpackte Archiv enthält folgende Dateien:
- docker-compose.yml
- env (Vorlage für Umgebungsvariablen)
- application.properties (Spring-Boot-Konfiguration, in den Container eingebunden)
- README.md
Konfigurieren Sie die Umgebungsvariablen

Öffnen Sie die Datei env in einem Texteditor und passen Sie die Einstellungen an Ihre Umgebung an. Insbesondere muss ALLEGRA_HOME_DIR auf den absoluten Pfad Ihres Allegra-Home-Verzeichnisses (ALLEGRA_HOME) aus Schritt 1 gesetzt werden, und DB_PASSWORD sollte auf ein starkes Datenbank-Passwort gesetzt werden.

Beispielkonfiguration:
```
CONTEXT=demo
TZ=Europe/Berlin
ALLEGRA_HOME_DIR=/home/ubuntu/allegra-home  # Pfad zu Ihrem ALLEGRA_HOME-Verzeichnis
HTTP_PORT=8080
JAVA_OPTS=-Djava.awt.headless=true -Xmx2048m -Xms1024m
DB_USER=allegra
DB_PASSWORD=tissi189
```
Bemerkung

Verwenden Sie das Verzeichnis ALLEGRA_HOME_DIR ausschließlich für Allegra. Lassen Sie es niemals auf das Home-Verzeichnis eines Benutzers oder einen gemeinsam genutzten Ordner zeigen: Auf Hosts mit SELinux setzt Docker die Labels dieses Verzeichnisses und seines gesamten Inhalts neu.
Benennen Sie die Datei in .env um

Docker Compose liest Umgebungsvariablen automatisch aus einer Datei namens .env in dem Ordner, in dem auch die Datei docker-compose.yml liegt.
```
mv env .env
```
Starten Sie Allegra

Starten Sie Allegra im Hintergrund mit Docker Compose:
```
sudo docker compose up -d
```
Dieser Befehl führt Folgendes aus:
- Lädt das in der mitgelieferten docker-compose.yml angegebene Allegra-Image
- Bindet das Host-Verzeichnis /home/ubuntu/allegra-home als persistentes Speicherverzeichnis ein
- Mapped den Host-Port HTTP_PORT auf denselben Port im Container
- Startet Allegra automatisch (restart: always)
Zugriff auf Allegra

Öffnen Sie nach kurzer Startzeit einen Browser und rufen Sie auf:

http://<host>:${HTTP_PORT}/${CONTEXT}

wobei <host> localhost ist, wenn Sie direkt auf dem Server surfen, oder die IP-Adresse bzw. der Hostname des Servers, wenn Sie von einem anderen Rechner zugreifen, und ${CONTEXT} der in Ihrer .env-Datei festgelegte Kontext ist (Standard demo).

Mit den Standardeinstellungen ist Allegra unter http://localhost:8080/demo erreichbar (z. B. http://192.168.1.10:8080/demo von einem anderen Rechner).

Standard-Anmeldedaten:
- Benutzername: admin
- Passwort: tissi
Warnung

Ändern Sie aus Sicherheitsgründen das Standard-Administratorpasswort unmittelbar nach der ersten Anmeldung. Verwenden Sie ein starkes Passwort und bewahren Sie es sicher auf.

Betrieb#

Zur Verwaltung des Containers:

docker compose ps        # Status prüfen
docker compose logs -f   # Live-Logs anzeigen
docker compose stop      # Allegra stoppen
docker compose start     # Allegra starten
docker compose down      # Container stoppen und entfernen

Allegra aktualisieren#

Um Allegra auf eine neuere Version zu aktualisieren, öffnen Sie die Datei docker-compose.yml und passen den Image-Tag an, zum Beispiel:

image: alltena/allegra:<version>  # Die aktuelle Version finden Sie in unseren Release Notes

Anschließend laden Sie das neue Image herunter und starten den Container neu:

docker compose pull
docker compose up -d

Bemerkung

Stammt Ihre docker-compose.yml aus einem älteren Allegra-Docker-Paket, verwenden Sie die docker-compose.yml des aktuellen Pakets (siehe Schritt 2) und übernehmen Sie Ihre Einstellungen. Älteren Dateien fehlt das Suffix :z an den volumes-Zeilen, das Hosts mit SELinux benötigen.

Bemerkung

Upgrade von Allegra 8.x: Vom alten Image erzeugte Dateien können einem anderen Benutzer gehören. Allegra bricht dann beim Start mit einer AccessDeniedException ab. Setzen Sie die Besitzrechte für alle Inhalte von ALLEGRA_HOME außer dem Datenbankordner auf 999:999:

cd /home/ubuntu/allegra-home
sudo chown 999:999 .
sudo find . -mindepth 1 -maxdepth 1 ! -name dbdata -exec chown -R 999:999 {} +

Ersetzen Sie dbdata durch den Namen Ihres Datenbankordners, falls dieser abweicht (z. B. mysql).

Fehlerbehebung#

Eingebundene Dateien können nicht gelesen werden (SELinux)#

Auf Hosts mit SELinux (RHEL und Derivate wie Rocky oder Alma Linux, Fedora, Fedora CoreOS) können die Container nur dann auf die eingebundenen Dateien zugreifen, wenn jede volumes-Zeile in docker-compose.yml mit :z endet. Die docker-compose.yml des aktuellen Allegra-Docker-Pakets enthält dieses Suffix bereits. Fehlt es, tritt eines der folgenden Symptome auf:

Der Container db startet nicht. docker compose logs db zeigt Permission denied.
Der Container allegra bricht mit ERROR: data directory '/home/allegra' is not writable ab (siehe docker compose logs allegra), obwohl das Verzeichnis 999:999 gehört.
Allegra bricht mit Allegra home /home/ubuntu/allegra does not exist and can't be created ab. Dieser Pfad ist der eingebaute Standardwert: Allegra konnte Ihre application.properties nicht lesen.

Ob Docker SELinux verwendet, prüfen Sie mit:

docker info --format '{{.SecurityOptions}}'

Enthält die Ausgabe name=selinux, lassen Sie sich die SELinux-Labels der eingebundenen Dateien anzeigen. Führen Sie den Befehl in dem Ordner aus, der docker-compose.yml enthält:

ls -dZ <ALLEGRA_HOME_DIR> application.properties

Dateien, auf die die Container zugreifen können, haben den Typ container_file_t. Jeder andere Typ, z. B. user_home_t, bedeutet, dass :z fehlt. Ergänzen Sie :z in den volumes-Zeilen wie in der docker-compose.yml des aktuellen Allegra-Docker-Pakets und erstellen Sie die Container neu:

docker compose down
docker compose up -d

docker compose restart reicht nicht aus, da dieser Befehl Änderungen an docker-compose.yml nicht übernimmt.

Deinstallation#

Zum Entfernen von Allegra und allen Daten:

Warnung

Dadurch werden alle Allegra-Daten gelöscht, die in Ihrem ALLEGRA_HOME gespeichert sind.

docker compose down
docker rmi alltena/allegra:<version>
docker rmi postgres:18
sudo rm -rf /home/ubuntu/allegra-home

Nach erfolgreicher Installation sollten Sie Ihre Instanz absichern, indem Sie das Administratorpasswort ändern und HTTPS über einen Reverse Proxy konfigurieren (siehe Nginx-Proxy-Beispiel oder Apache-Proxy-Beispiel).