Den Stack betreiben

Nach der Installation mit almirant install decken die Befehle ps, logs, upgrade und down alles ab, was du zur Wartung der Instanz benötigst.

Alle gehen davon aus, dass der Stack unter ~/.almirant/stack/ liegt. Falls du ihn mit einem anderen --dir installiert hast, übergebe für die folgenden Befehle dasselbe --dir.

Status anzeigen

almirant ps

Zeigt den Status aller Container an (entspricht docker compose ps mit docker-compose.prod.yml). postgres, redis, backend, frontend und runner sollten den Status Up (healthy) haben. Wenn einer als Exited oder Restarting erscheint, sieh in seine Logs.

Logs lesen

Alle Logs in Echtzeit verfolgen:

almirant logs -f

Auf einen Service beschränken (schneller, wenn du nach etwas Bestimmtem suchst):

almirant logs -f backend frontend

Nur die letzten N Zeilen:

almirant logs --tail 200 backend

Nützliche Services:

Service	Zweck
`backend`	API-, Authentifizierungs- und Geschäftslogikfehler
`frontend`	SSR-Renderingfehler, unvollständige Builds, unerwartete 404-Fehler
`db-init`	Schema-Bootstrap und Seeds — läuft nur beim Start
`postgres`	Verbindungsfehler, Abstürze
`runner`	Jobs von KI-Agenten
`web-bridge`	Echtzeitkommunikation mit dem Frontend

Auf die neueste Version aktualisieren

almirant upgrade

Das Upgrade führt nacheinander drei Schritte aus:

git pull im Stack-Verzeichnis.
Abgleich von .env.production mit .env.production.example. Falls das Upgrade neue erforderliche Variablen einführt (z. B. ein erzeugtes Geheimnis oder einen abgeleiteten Pfad), werden sie automatisch hinzugefügt, ohne deine bestehenden Werte zu ändern. Vor jeder Änderung wird neben der Datei ein Backup .env.production.bak.<unix-timestamp> erstellt.
docker compose up -d --build --force-recreate: Images neu bauen und Container neu starten. Die Datenvolumes bleiben erhalten.

Vor dem Anwenden prüfen

Um zu sehen, was sich ändern würde, ohne etwas zu verändern:

almirant upgrade --check-env

Listet die Variablen auf, die zu .env.production hinzugefügt wurden, sowie die Herkunft jedes Werts (generated, derived, default, empty). Docker wird nicht ausgeführt und die Datei wird nicht geschrieben.

Den Env-Abgleich überspringen

Wenn du .env.production mit eigenen Werkzeugen verwaltest (Ansible, versiegelte Secrets usw.) und das CLI die Datei nicht ändern soll:

almirant upgrade --no-env-sync

In diesem Fall bist du dafür verantwortlich, .env.production mit dem Schema konsistent zu halten. Falls eine erforderliche Variable fehlt, schlägt docker compose up mit required variable X is missing a value fehl.

Einen fehlerhaften Sync wiederherstellen

Jedes almirant upgrade, das .env.production ändert, hinterlässt ein Backup mit Zeitstempel:

ls -la ~/.almirant/stack/.env.production.bak.*
cp ~/.almirant/stack/.env.production.bak.<ts> ~/.almirant/stack/.env.production

Backups werden nicht automatisch rotiert. Sie belegen wenig Speicherplatz und dokumentieren jede Änderung.

Nur bestimmte Teile aktualisieren

Wenn du weißt, dass sich nur das Frontend geändert hat, beschränke das Upgrade, um Zeit zu sparen:

almirant upgrade frontend

Du kannst mehrere Services übergeben: almirant upgrade frontend backend.

Auf eine bestimmte Version aktualisieren

almirant upgrade --branch v1.3.0

Einen Remote-Rechner per SSH aktualisieren

Wenn der Stack auf einem anderen Server liegt und du ihn von deinem Laptop aktualisieren möchtest:

almirant upgrade --host [email protected]

Das CLI verbindet sich per SSH und führt scripts/update-remote.sh auf dem Zielrechner aus. Auf diesem muss das Repository bereits unter ~/.almirant/stack/ geklont sein. Der Abgleich von .env.production läuft ebenfalls auf dem Remote-Host. Wenn der Stack neue erforderliche Variablen erhalten hat, wird der Remote-Host bei deinem ersten nachfolgenden Upgrade daher wie der lokale Host automatisch synchronisiert.

Click-to-Update im Dashboard

Ab der Stack-Version mit dem Sidecar updater sehen Administratoren im Dashboard ein Banner "Update now", wenn main vor dem laufenden Build liegt. Es ist eine Alternative zum CLI für Administratoren ohne Shell-Zugriff auf den Stack-Rechner.

Funktionsweise

Das Backend erkennt eine neue Version, indem es seinen Build-SHA mit main vergleicht. Anschließend stellt es Administratoren eine Schaltfläche bereit. Beim Anklicken:

Das Backend sendet eine POST-Anfrage an das Sidecar updater (es befindet sich im internen Compose-Netzwerk und ist nicht öffentlich erreichbar).
Das Sidecar führt git pull --ff-only origin main + docker compose build + up -d --force-recreate für alle Services außer dem Updater selbst aus.
Die UI zeigt den Fortschritt und bleibt bei "Restarting…", bis das neue Backend auf Healthchecks antwortet.

Das Sidecar wird vom Recreate ausgenommen, damit es den von ihm selbst ausgelösten Neubau überlebt.

Wann die Schaltfläche angezeigt wird

Der Nutzer hat die Rolle admin.
Das Sidecar updater läuft und ist vom Backend aus erreichbar (die Variablen UPDATER_INTERNAL_URL und UPDATER_INTERNAL_TOKEN sind konfiguriert — almirant upgrade erzeugt sie automatisch, wenn sie fehlen).
In main liegen Commits vor dem aktuellen Build-SHA.

Ist das Sidecar nicht erreichbar, sehen Administratoren stattdessen die Schaltfläche "Copy command", die den fertig einsetzbaren Befehl almirant upgrade bereitstellt.

Click-to-Update deaktivieren

Zwei Möglichkeiten, nur das CLI zu verwenden:

# A) Quitar el sidecar del compose
cd ~/.almirant/stack
# editar docker-compose.prod.yml y comentar el bloque `updater:`
docker compose -f docker-compose.prod.yml --env-file .env.production up -d
# El backend cae al fallback "Copy command" automaticamente.

# B) Mantener el sidecar pero invalidar el token
sed -i '' 's|^UPDATER_INTERNAL_TOKEN=.*|UPDATER_INTERNAL_TOKEN=|' ~/.almirant/stack/.env.production
docker compose -f docker-compose.prod.yml --env-file .env.production up -d --force-recreate backend

Einschränkungen

Es wählt keine Services aus — es baut immer alles neu, was nicht in der Ausschlussliste steht.
Es führt kein Rollback durch, wenn der Neubau den Stack in einen ungesunden Zustand versetzt. Für mehr Kontrolle verwende almirant upgrade <servicio> in der Shell.
Falls eine Migration des neuen Builds fehlschlägt, beendet sich db-init mit einem von null verschiedenen Exit-Code, das Backend startet nicht und du musst dies mit almirant logs db-init untersuchen.

Verwende in diesen Fällen das CLI als Fallback:

almirant upgrade --host [email protected]

Den Stack anhalten

Ohne Datenverlust (der Normalfall — du kannst ihn mit almirant upgrade oder einer neuen install-Ausführung wieder starten):

almirant down

Lokale Images löschen (um bei der nächsten Installation einen sauberen Neubau zu erzwingen):

almirant down --rmi local

Alles einschließlich Datenvolumes löschen (destruktiv):

almirant down --volumes

Warnung

--volumes löscht die Postgres- und Redis-Daten irreversibel. Erstelle vorher ein Backup, wenn du Arbeit nicht verlieren möchtest. Die Backup-Strategie findest du unter docs/self-hosting/backups.md im Quell-Repository.

Öffentliche URL ändern

Dies ist die empfindlichste Änderung, da NEXT_PUBLIC_SITE_URL in das Frontend-Bundle kompiliert wird. Nur .env.production zu ändern reicht nicht aus.

Option A — sauber neu installieren (einfacher, destruktiv)

Falls es sich um einen Test-Stack handelt und dir Datenverlust nichts ausmacht:

almirant down --volumes
almirant install --public-url https://nueva-url.example.com

Option B — Env bearbeiten und neu bauen (Daten bleiben erhalten)

cd ~/.almirant/stack

# 1. Edita las 4 variables relevantes en .env.production
sed -i '' \
  -e 's|^NEXT_PUBLIC_SITE_URL=.*|NEXT_PUBLIC_SITE_URL=https://nueva-url.example.com|' \
  -e 's|^BETTER_AUTH_URL=.*|BETTER_AUTH_URL=https://nueva-url.example.com|' \
  -e 's|^BETTER_AUTH_TRUSTED_ORIGINS=.*|BETTER_AUTH_TRUSTED_ORIGINS=https://nueva-url.example.com|' \
  -e 's|^CORS_ORIGIN=.*|CORS_ORIGIN=https://nueva-url.example.com|' \
  .env.production

# 2. Rebuild obligatorio de frontend + backend
docker compose -f docker-compose.prod.yml --env-file .env.production \
  up -d --build --force-recreate frontend backend

Einen Origin ohne Neubau hinzufügen

Wenn Better-Auth nur einen zusätzlichen Origin akzeptieren soll (z. B. gleichzeitig http://localhost:8080 und deine Tailscale-URL), kannst du mehrere durch Kommas getrennte Origins in BETTER_AUTH_TRUSTED_ORIGINS und CORS_ORIGIN angeben und nur das Backend ohne Neubau neu starten:

# .env.production
BETTER_AUTH_TRUSTED_ORIGINS=http://localhost:8080,https://mimac.tailnet.ts.net
CORS_ORIGIN=http://localhost:8080,https://mimac.tailnet.ts.net

cd ~/.almirant/stack
docker compose -f docker-compose.prod.yml --env-file .env.production \
  up -d --force-recreate backend

Beachte: Das Frontend ruft weiterhin den in das Bundle eingebetteten Wert von NEXT_PUBLIC_SITE_URL auf. Falls dieser Wert nicht mit der URL übereinstimmt, über die du zugreifst, schlagen einige Aufrufe fehl, auch wenn CORS und Origin die Anfrage akzeptieren. Für eine dauerhafte Änderung befolge die vollständige Option B.

Backup und Wiederherstellung

Die Daten der Instanz befinden sich im Volume almirant-prod_postgres_prod_data. So erstellst du bei laufender Instanz ein Backup:

docker compose -f ~/.almirant/stack/docker-compose.prod.yml --env-file ~/.almirant/stack/.env.production \
  exec postgres pg_dump -U almirant -d almirant > backup-$(date +%Y%m%d).sql

Weitere robuste Backup-Strategien, einschließlich Rotation und Versand an S3, findest du in der Dokumentation des Quell-Repositorys (docs/self-hosting/backups.md).

Geheimnisse ändern

Wenn ein Geheimnis kompromittiert wurde (z. B. BETTER_AUTH_SECRET oder ENCRYPTION_KEY):

Bearbeite den Wert in ~/.almirant/stack/.env.production.
Starte die betroffenen Services neu:

cd ~/.almirant/stack
docker compose -f docker-compose.prod.yml --env-file .env.production \
  up -d --force-recreate backend

Warnung

Das Rotieren von ENCRYPTION_KEY macht alle zuvor verschlüsselten Werte ungültig (gespeicherte OAuth-Tokens, externe Integrationen usw.). Diese Tokens musst du erneut erzeugen.

Was tun, wenn der Stack nicht startet?

Diagnosereihenfolge:

# 1. Ver que servicio esta caido
almirant ps

# 2. Logs del servicio problema
almirant logs --tail 200 <servicio>

# 3. Si es db-init (bootstrap de base de datos), es casi siempre:
#    - password authentication failed → reinstalar limpio
#    - Ver guia self-hosted → "Errores comunes"

# 4. Si es frontend, a menudo es build corrupto — fuerza rebuild sin cache:
cd ~/.almirant/stack
docker compose -f docker-compose.prod.yml --env-file .env.production \
  build --no-cache frontend
docker compose -f docker-compose.prod.yml --env-file .env.production \
  up -d --force-recreate frontend

Status anzeigen​

Logs lesen​

Auf die neueste Version aktualisieren​

Vor dem Anwenden prüfen​

Den Env-Abgleich überspringen​

Einen fehlerhaften Sync wiederherstellen​

Nur bestimmte Teile aktualisieren​

Auf eine bestimmte Version aktualisieren​

Einen Remote-Rechner per SSH aktualisieren​

Click-to-Update im Dashboard​

Funktionsweise​

Wann die Schaltfläche angezeigt wird​

Click-to-Update deaktivieren​

Einschränkungen​

Den Stack anhalten​

Öffentliche URL ändern​

Option A — sauber neu installieren (einfacher, destruktiv)​

Option B — Env bearbeiten und neu bauen (Daten bleiben erhalten)​

Backup und Wiederherstellung​

Geheimnisse ändern​

Was tun, wenn der Stack nicht startet?​