Heroku-ish Apphosting via Dokku

Dokku ist eine Software mit deren Hilfe man schnell von Code zu einer laufenden Webanwendung kommt.

Benutzung (Admins)

Man kann generell auf zwei Arten mit Dokku interagieren. Via SSH und lokal via sudo. Manche Befehle lassen sich aus Sicherheitsgründen nur lokal ausführen. Desweiteren wird über das Plugin dokku-acl eingeschränkt, wer welche Befehle via SSH ausführen kann (siehe ACLs). Für das Ausführen von Befehlen via SSH wird folgendes Hilfs-Alias verwendet: 

alias dokku='ssh dokku@dokku.informatik.uni-bremen.de --'

Über die lokale Gruppe dokku wird gesteuert, wer sich mit seinem UNIX-Account auf dem Server anmelden und lokal dokku via sudo ausführen darf.

Im Folgenden werden die wichtigsten Aktionen kurz erklärt:

Account anlegen

Für die Erstellung eines Benutzer-Accounts wird ein Accountname und ein SSH-Public-Key benötigt. 

ssh dokku
echo "$PUB_KEY" | sudo dokku ssh-keys:add $USER

Anwendung anlegen

dokku apps:create $APP

Anderen Benutzern Rechte auf eine Anwendung geben

ssh dokku
sudo dokku acl:add $APP $USER

Datenbank anlegen (Optional)

Dokku hat ein Konzept von Diensten, i.d.R. Datenbanken, die persistente Daten für Anwendungen aufbewahren. Dienste werden separat angelegt und müssen danach mit der jeweiligen Anwendung verlinkt werden. Wenn eine Anwendung keine Datenbank benötigt kann dieser Schritt übersprungen werden.

Derzeit ist nur ein Dienst-Plugin für PostgreSQL installiert. Siehe die Liste von Plugins in der Dokku-Dokumentation für weitere Optionen. 

dokku postgres:create $DB
dokku postgres:link $DB $APP

Zugriff auf gelinkte Postgres-Datenbanken

Siehe link the postgres service to the app und promote service as DATABASE_URL in in der Dokumentation des Postgres-Plugins.

Anderen Benutzern Rechte auf eine Datenbank geben

ssh dokku
sudo dokku acl:add-service postgres $DB $USER

Persistente Daten

Dokku verpackt Anwendungen in Docker-Container, welche keine persistenten Verzeichnisse haben. Das bedeutet, dass Dateien die von einer Anwendung im lokalen Dateisystem gespeichert werden nach einem Neustart der Anwendung verfallen. Falls persistente lokale Dateien benötigt werden, können Verzeichnisse des Host-Systems in die Container gemountet werden. 

dokku storage:ensure-directory $DIRNAME
dokku storage:mount $APP /var/lib/dokku/data/storage/$DIRNAME:$MOUNTPATH

Dabei ist /var/lib/dokku/data/storage/$DIRNAME der lokale Pfad auf dem dokku-Server und $MOUNTPATH der Mountpoint innerhalb des Containers.

Ein Beispiel hierfür, um ein Verzeichnis aus dem NFS in den Container zu mounten kann folgendermaßen aussehen: 

dokku storage:ensure-directory $DIRNAME
dokku storage:mount $APP /home/dml.uni-bremen.de/docroot/apps/$DIRNAME:/app/storage

Im Container ist dann in /storage das Verzeichnis aus dem NFS gemountet. /app/ stellt im Container selbst die root-Ebene / dar. Das gemountete NFS-Verzeichnis muss die erforderlichen Berechtigungen haben, damit dokku hier auch lesen und schreiben darf. Da Dokku im NFS jedoch nicht bekannt ist, müssen hier die Rechte für andere User angepasst werden. Es empfiehlt sich zwei Unterverzeichnisse anzulegen. Ein Verzeichnis bspw. /data, um persistente Daten dem Container zur Verfügung zu stellen, mit den Rechten 775 und ein weiteres Verzeichnis bspw. /export, mit den Rechten 773, in das Dokku schreiben darf.

Persistente Daten exportieren

Persistente Daten können von Accounts mit Rechten auf die jeweilige Anwendung als tgz-Archiv exportiert werden. 

dokku storage:export $APP > /path/to/archive.tgz

Benutzung (Endbenutzer)

Wie auch Admins, können Endbenutzer via SSH Dokku-Befehle ausführen, für die sie die entsprechenden Rechte haben (siehe ACLs). Das oben gelistete Hilfs-Alias ist also auch hier Voraussetzung, um die folgenden Kommandos ausführen zu können. Das Hilfsalias wird nicht von allen Shells unterstützt. Unter Windows eignet sich die Git-Shell. Der Alias gilt nur für die Laufzeit der Shell und muss nach Beendigung dieser erneut eingerichtet werden. 

alias dokku='ssh dokku@dokku.informatik.uni-bremen.de --'

App aus Git-Repository installieren

Nachdem eine Person Zugang zu einer Anwendung bekommen hat, kann diese mit ihrem SSH-Public-Key ihren Code direkt via git auf den Dokku-Server pushen. Bei jedem Push wird die Anwendung mit dem aktualisierten Code neu gebaut. Falls dies nicht gewünscht ist, kann eine Anwendung via dokku apps:lock $APP bzw. dokku apps:unlock $APP ge- und entsperrt werden. 

git remote add dokku dokku@dokku:$APP
git push dokku main

Anforderungen an den Code

Der Build-Prozess von Dokku erkennt automatisch die verwendete Programmiersprache und baut ein Docker-Image aus dem Code in das alle Abhängigkeiten installiert werden.

Zusätzlich muss eine Datei mit Namen Procfile in das Wurzelverzeichnis des Quelltextes abgelegt werden, das den Heroku-Procfile Spezifikationen entspricht. Kurz zusammengefasst definiert das Procfile wie die Anwendung zu starten ist. Für eine Streamlit-Anwendung könnte Procfile z.B. wie folgt aussehen: 

web: streamlit run --server.port $PORT --server.address 0.0.0.0 --browser.serverAddress appnane.apps.informatik.uni-bremen.de --server.runOnSave=false --server.allowRunOnSave=false --server.fileWatcherType=none --browser.gatherUsageStats=false --global.developmentMode=false app.py

Wichtig ist, dass die Anwendung auf dem Port lauscht, der in der Umgebungsvariable $PORT definiert ist (i.d.R. 5000) und nicht nur auf localhost.

Domain(s)

Die Standard-Domain einer Anwendung ist $APP.apps.informatik.uni-bremen.de. Es werden automatisch via Letsencrypt TLS-Zertifikate bezogen.

Die Domain einer Anwendung kann via dokku domains:* Befehle geändert werden. Voraussetzung dafür ist, dass der jeweilige Domainname auf den Dokku-Server zeigt.

Die aktuellen URLs, unter der eine Anwendung erreichbar ist, können via dokku urls $APP angezeigt werden.

Starten, Stoppen, Neustarten, Neubauen einer Anwendung

Mit den Befehlen unter dokku ps:* kann mit dem laufenden Container einer Anwendung interagiert werden. Diese Befehle können via SSH von jedem Account mit Zugriffsrechten auf die jeweilige Anwendung ausgeführt werden. 

ps:rebuild $APP
ps:restart $APP
ps:start $APP
ps:stop $APP

Ausrollen von Anwendungen via Gitlab-CI

Wenn man eine Anwendung in Gitlab verwalten und dessen CI/CD-Funktion nutzen möchte, um Änderungen an Dokku zu übertragen, geht das wie folgt:

ACLs

Siehe ~dokku/.dokkurc/acl für die tatsächliche Liste der ACLs.

Das ACL-Plugin staffelt Berechtigungen wie folgt:

Derzeit gelten die folgenden ACLs:

Zentrale Administration/Dokku (zuletzt geändert am 2024-09-23 12:03:24 durch harms)