Zum Hauptinhalt springen

Self-Hosted-Installation

Diese Anleitung führt dich von null zu einer laufenden Almirant-Instanz auf deinem Rechner oder Server.

Geschätzte Dauer: 15-25 Minuten (der größte Teil davon ist beim ersten Mal der Bau der Docker-Images).

Voraussetzungen​

  • Docker 24+ und Docker Compose v2 sind installiert und laufen. Wenn du den Stack auf einem per Terminal als Server verwendeten Mac ausführen möchtest, lies zuerst Docker-Runtime unter macOS.
  • 4 GB RAM und ca. 10 GB freier Speicherplatz.
  • Zugriff auf das Repository almirant-ai/almirant bei GitHub. Solange das Repository privat ist, benötigst du eine funktionierende Git-Authentifizierungsmethode (siehe Schritt 1). Sobald das Repository öffentlich ist, ist dieser Schritt nicht mehr erforderlich.
  • Eine öffentliche URL, über die der Dienst erreichbar sein wird. Das kann sein:
    • http://localhost:8080 für die lokale Nutzung.
    • Eine eigene Domain mit HTTPS.
    • Eine Tailscale-Funnel-URL (https://<host>.<tailnet>.ts.net).
    • Die URL eines Tunnels (Cloudflare Tunnel, ngrok usw.).

Docker-Runtime unter macOS​

Unter macOS läuft Docker in einer Linux-VM. Die "Runtime" ist die App, welche diese VM verwaltet. Es gibt drei Optionen:

RuntimeAm besten fürAbwägung
Docker DesktopEntwicklung auf einem Mac mit geöffneter UIRessourcenintensiv (ca. 500 MB im Leerlauf), erfordert eine aktive GUI-Sitzung
OrbStackEntwicklung auf einem Mac mit geöffneter UISehr schnell, Menüleisten-App — erfordert eine aktive GUI-Sitzung, kostenpflichtig für kommerzielle Nutzung
ColimaHeadless-ServerReines CLI, startet als macOS-Service — übersteht Neustarts ohne GUI-Anmeldung, kostenlos
Wenn du den Mac als Server verwendest (nur SSH-Zugriff)

Docker Desktop und OrbStack sind macOS-Apps, die voraussetzen, dass sich ein Benutzer an der grafischen Sitzung angemeldet hat. Wenn der Mac neu startet und niemand ihn entsperrt, bleibt der Docker-Daemon beendet und deine Instanz startet ebenfalls nicht.

Verwende als Server Colima:

brew install colima docker docker-compose

# Sizing tipico para un Mac de 16 GB / 8 cores
colima start --cpu 4 --memory 6 --disk 40

# Que arranque solo al boot (sin necesidad de login GUI)
colima stop
brew services start colima

Prüfe, ob es antwortet:

docker ps   # debe responder en menos de un segundo

Runtime mit bestehenden Daten wechseln​

Der Wechsel von OrbStack/Desktop zu Colima löscht die Volumes (sie befinden sich in der VM der bisherigen Runtime). Falls du bereits wichtige Daten hast:

  1. Exportiere bei laufender bisheriger Runtime pg_dump für Postgres und einen manuellen Snapshot für Redis, falls du es verwendest.
  2. Halte den Stack an: almirant down.
  3. Installiere und starte Colima.
  4. Wechsle den Kontext: docker context use colima.
  5. Führe erneut almirant install oder almirant upgrade aus, um die neuen Volumes zu erstellen.
  6. Stelle die Dumps wieder her.

Wenn die Instanz neu oder leer ist, gehe direkt zu Schritt 1.

Schritt 1 — Git bei GitHub authentifizieren​

Info

Dieser Schritt entfällt, sobald das Almirant-Repository öffentlich wird. Falls du dies nach dieser Umstellung liest, überspringe ihn.

Der Installer führt git clone https://github.com/almirant-ai/almirant.git aus. Falls das Repository privat ist, fragt Git nach Zugangsdaten. Am einfachsten verwendest du gh:

# Instala gh si no lo tienes
brew install gh           # macOS
sudo apt install gh       # Debian/Ubuntu

# Login interactivo — elige protocolo HTTPS (no SSH)
gh auth login
# GitHub.com → HTTPS → Login with a web browser

# Configura git para usar las credenciales de gh
gh auth setup-git

Prüfe, dass der Credential Helper von gh konfiguriert wurde:

git config --global --get-all credential.https://github.com.helper
# Debe mostrar: !/opt/homebrew/bin/gh auth git-credential   (o similar)

Falls unter macOS beim Klonen Fehler wie failed to get: -25308 auftreten, ist dein Keychain gesperrt (typisch bei SSH-Sitzungen ohne grafische UI). Entsperre ihn:

security unlock-keychain ~/Library/Keychains/login.keychain-db

Schritt 2 — Das CLI installieren​

bun add -g almirant@latest
# o
npm i -g almirant

Schritt 3 — almirant install starten​

Am empfehlenswertesten ist es, --public-url von Anfang an mit der exakten URL zu übergeben, über die du den Dienst aufrufen wirst:

almirant install --public-url https://almirant.miempresa.com
Warum die öffentliche URL wichtig ist

almirant install bettet die öffentliche URL gleichzeitig in vier Variablen ein:

  • NEXT_PUBLIC_SITE_URL (in das Frontend-Bundle kompiliert)
  • BETTER_AUTH_URL
  • BETTER_AUTH_TRUSTED_ORIGINS
  • CORS_ORIGIN

Wenn du später über eine andere URL zugreifst (z. B. hast du http://localhost:8080 angegeben, rufst die Instanz aber über https://mimac.tailnet.ts.net auf), lehnt Better-Auth die Anfrage mit Invalid origin ab und die Registrierung schlägt fehl.

Um die URL danach zu ändern, muss das Frontend neu gebaut werden. Siehe Öffentliche URL ändern.

Der Installer:

  1. Prüft die Voraussetzungen (Docker + Compose v2).
  2. Klont almirant-ai/almirant nach ~/.almirant/stack (oder führt einen Fast-Forward aus, falls es bereits existiert).
  3. Erzeugt .env.production mit zufälligen Geheimnissen, falls die Datei nicht vorhanden ist.
  4. Baut die Docker-Images (Backend, Frontend, Runner, db-init, Shims ...). Beim ersten Mal dauert dies 10-20 Minuten.
  5. Startet den Stack mit docker compose up -d.
  6. Wartet, bis das Frontend den Status healthy hat.
  7. Gibt die abschließende URL und die Day-2-Befehle aus.

Wichtige Flags von install​

FlagWann verwenden
--public-urlWann immer möglich. Vermeidet einen späteren Neubau.
--non-interactiveCI-Skripte oder automatisierte Bereitstellung.
--with-proxyWenn du den integrierten Reverse Proxy (Caddy) verwenden möchtest, statt Ports direkt freizugeben.
--with-discordWenn du die Bridge mit Discord verwenden möchtest.
--branchUm statt main eine bestimmte Version (v1.2.3) festzulegen.
--from-dirAir-Gap-Installationen aus einem bereits auf dem Datenträger vorhandenen Klon.

Die vollständige Liste findest du unter Referenz → install.

Schritt 4 — Onboarding abschließen​

Öffne die URL, die der Installer ausgegeben hat. Beim ersten Besuch wirst du zu /signup geführt.

  • Wenn die Datenbank leer ist (erster sauberer Start), arbeitet das Formular im Modus initial_admin_setup: Der erste registrierte Benutzer wird mit der Rolle admin erstellt und zum Assistenten unter /onboarding weitergeleitet.
  • Wenn bereits Benutzer vorhanden sind (z. B. weil du die Instanz unter Verwendung desselben Postgres-Volumes erneut installiert hast), funktioniert das Formular als normale Registrierung: Der neu erstellte Benutzer ist kein Admin und gelangt zum Dashboard. Falls du einen sauberen ersten Admin erzwingen möchtest, siehe Von vorn beginnen.

Der Assistent unter /onboarding hat drei Schritte, jeweils mit der Schaltfläche "Skip for now":

  1. Admin account — bestätigt, dass der erste Administrator vorhanden ist, und schließt die offene Registrierung.
  2. Public URL (Tailscale) — du kannst die Instanz mit Tailscale Funnel veröffentlichen oder eine eigene externe URL einfügen.
  3. GitHub App — erstellt eine GitHub App mit vorausgefülltem Manifest oder akzeptiert bestehende Zugangsdaten, damit die Agenten PRs öffnen können.

Nach Abschluss ist die App bereit. Der Link zu /onboarding bleibt in der Seitenleiste sichtbar, bis du alle Schritte abgeschlossen hast.

Optionaler Schritt — Postgres mit Tailscale schutzen​

Standardmäßig läuft Postgres in Docker und darf nicht über die öffentliche Schnittstelle des VPS bereitgestellt werden. Falls du dich von deinem Laptop mit TablePlus, DBeaver, DataGrip oder psql verbinden musst, richtest du am sichersten einen privaten Zugang über Tailscale ein.

Die Idee ist folgende:

  • Dein Laptop ist in deinem normalen Tailscale-Tailnet.
  • Almirant erstellt einen separaten Knoten mit dem Standardnamen almirant-db.
  • Dieser Knoten lauscht nur im privaten Tailscale-Netzwerk und leitet Port 5432 an den internen Docker-Postgres weiter.
  • Postgres bleibt weiterhin nicht im Internet veröffentlicht.
Öffne Postgres nicht in der VPS-Firewall

Veröffentliche nicht 5432:5432 und öffne Port 5432 nicht "zum Testen" im Internet. Das funktioniert zwar, ist aber eine schlechte Sicherheitsgrundlage. Die Datenbank darf nur von autorisierten Geräten innerhalb deines Tailnets erreichbar sein.

1. Dein Tailnet vorbereiten​

Installiere zuerst Tailscale auf deinem Laptop und melde dich an. Prüfe im Tailscale-Panel, ob dein Rechner unter Machines angezeigt wird.

Lege anschließend unter Access controls ein Tag für den Datenbankknoten fest:

"tagOwners": {
  "tag:almirant-db": ["autogroup:admin"]
}

Wenn du bereits tagOwners hast, ersetze es nicht vollständig: Füge nur den Eintrag tag:almirant-db hinzu.

2. Beschränken, wer Postgres erreichen darf​

Füge eine Regel hinzu, die deinem Benutzer Zugriff auf den Datenbankknoten nur über TCP 5432 erlaubt:

"grants": [
  {
    "src": ["[email protected]"],
    "dst": ["tag:almirant-db"],
    "ip": ["tcp:5432"]
  }
]

Ersetze [email protected] durch die E-Mail-Adresse, mit der du dich bei Tailscale anmeldest.

Einfach anfangen

Wenn du gerade mit Tailscale beginnst, verwende einen Auth Key. Der Ablauf mit einem OAuth-Client eignet sich besser für fortgeschrittene Automatisierung, führt für die erste Konfiguration aber unnötige Konzepte ein.

3. Einen Auth Key für Almirant erstellen​

In Tailscale Admin:

  1. Gehe zu Keys.
  2. Klicke auf Generate auth key.
  3. Verwende eine Beschreibung wie Almirant DB.
  4. Aktiviere das Tag tag:almirant-db.
  5. Wenn dein Tailnet die Genehmigung von Geräten verlangt, markiere den Schlüssel als pre-approved.
  6. Kopiere den Schlüssel. Er muss mit tskey-auth-... beginnen.

Speichere diesen Schlüssel nicht im Repository und füge ihn nicht in Issues, Logs oder Screenshots ein.

4. Almirant mit dem Tailnet verbinden​

Melde dich in Almirant als Administrator an und gehe zu:

/settings/instance

Unter Private database access:

FeldEmpfohlener Wert
Hostnamealmirant-db
Tagtag:almirant-db
MethodeAuth key
Auth keyDer Tailscale-Schlüssel tskey-auth-...

Klicke auf Connect. Warte während der Bereitstellung, bis der Status zu connected wechselt.

Nach Abschluss zeigt Almirant eine Verbindungszeichenfolge an, die etwa so aussieht:

postgresql://...@almirant-db.<tu-tailnet>.ts.net:5432/...

Verwende diese URL auf deinem Laptop, während du mit Tailscale verbunden bist.

5. Checkliste, wenn keine Verbindung möglich ist​

Prüfe in dieser Reihenfolge:

  1. Dein Laptop ist mit Tailscale verbunden.
  2. In Tailscale Admin wird ein Rechner namens almirant-db angezeigt.
  3. Dieser Rechner hat das Tag tag:almirant-db.
  4. Die Zugriffsregel erlaubt tcp:5432 an tag:almirant-db.
  5. In Almirant lautet der Status von Private database access connected.
  6. Du verwendest die von Almirant angezeigte Verbindungszeichenfolge, nicht die interne DATABASE_URL des Containers.

Wenn MagicDNS den Hostnamen nicht auflöst, verwende vorübergehend die von Almirant angezeigte Tailscale-IP 100.x.y.z.

Schritt 5 — Das CLI mit deiner Instanz verbinden​

Bis hierhin hast du den Stack installiert. Jetzt konfigurierst du das CLI so, dass es auf diese Instanz verweist, damit du in deinen Repositories init und link verwenden kannst. Diesen Schritt führst du einmal pro Rechner aus, auf dem du das CLI verwendest (dein Laptop, eine Entwicklungs-VM, der Server selbst usw.).

5.1 — Die API-URL ermitteln​

Die API-URL ist deine --public-url mit angehängtem /api:

--public-url der InstallationAPI-URL
https://almirant.miempresa.comhttps://almirant.miempresa.com/api
https://<host>.<tailnet>.ts.nethttps://<host>.<tailnet>.ts.net/api
http://localhost:8080http://localhost:8080/api

5.2 — Das CLI authentifizieren​

Auf dem Rechner, auf dem du das CLI verwenden wirst:

# Instala el CLI si aun no lo tienes en esa maquina
bun add -g almirant@latest

# Login contra tu instancia self-hosted
almirant login --api-url https://almirant.miempresa.com/api

Der Browser öffnet sich für deine Instanz, du autorisierst die Sitzung und das CLI erfasst einen API-Schlüssel, den es in ~/.almirant/config.json speichert. Das Konto erhält eine stabile ID und eine lokale Bezeichnung, die du umbenennen kannst.

Von einem anderen Rechner aus

Dieser Schritt ist unabhängig davon, wo der Stack läuft. Falls der Stack auf einem Remote-Server liegt und du das CLI auf deinem Laptop verwenden möchtest, muss dein Laptop lediglich per HTTPS auf die API-URL zugreifen können. Befindet sich die Instanz hinter Tailscale, stelle sicher, dass du im selben Tailnet bist; bei einem Tunnel oder Proxy muss der Port erreichbar sein.

5.3 — Die Konfiguration prüfen​

almirant accounts list
almirant current

Dein Self-Hosted-Konto sollte aufgeführt sein, mit einer API URL, die auf deine Instanz zeigt, und dem API-Schlüssel, der nur durch sein Präfix dargestellt wird.

Wenn du mehrere Konten hast (z. B. arbeitest du auch mit dem SaaS unter almirant.ai), vergib Bezeichnungen und wähle aus, welches aktiv ist:

almirant accounts rename 1 prod-saas
almirant accounts rename 2 local-m1pro
almirant use local-m1pro

Weitere Details findest du unter Mit mehreren Konten arbeiten.

5.4 — Ein Repository verknüpfen​

Wenn das Konto authentifiziert ist, verknüpfst du ein Repository mit einem Projekt deiner Instanz genauso wie im SaaS-Ablauf:

cd mi-repo
almirant link
# Si tienes varias cuentas, elige la self-hosted
# Selecciona un proyecto o crea uno nuevo

Das CLI schreibt .mcp.json mit almirant mcp proxy --project-id ... --account .... Der API-Schlüssel bleibt nicht im Repository, sondern in ~/.almirant/config.json; der Proxy hängt ihn im Speicher an.

Den vollständigen Ablauf Schritt für Schritt (mit Überprüfung aus der IDE) findest du unter Ein Repository verbinden.

Von vorn beginnen​

Wenn etwas schiefgelaufen ist und du mit einer sauberen Datenbank beginnen möchtest (zerstört alle Daten des lokalen Stacks):

almirant down --volumes
almirant install --public-url https://almirant.miempresa.com
Warnung

almirant down --volumes löscht die Postgres- und Redis-Volumes. Verwende dies nur bei Testinstallationen oder wenn du sicher bist, die Daten verlieren zu wollen.

Häufige Fehler bei der ersten Installation​

password authentication failed for user "almirant"​

Dies bedeutet, dass das Postgres-Volume ein altes Passwort aus einer vorherigen Installation enthält, das von dem gerade in .env.production erzeugten abweicht. Postgres liest POSTGRES_PASSWORD aus der Umgebung nur beim ersten Start des Volumes.

Lösung: Lösche die Volumes und installiere erneut (siehe Von vorn beginnen).

Invalid origin bei der Registrierung​

Die URL, über die du zugreifst, ist nicht in BETTER_AUTH_TRUSTED_ORIGINS enthalten.

Lösung: Installiere erneut mit --public-url, die exakt der URL in der Browserleiste entspricht:

almirant install --public-url https://<lo-que-ves-en-tu-navegador>

Wenn du bereits Daten hast, die du nicht verlieren möchtest, kannst du die URL ohne Neuinstallation ändern: siehe Öffentliche URL ändern.

404 nach der Registrierung​

Die häufigste Ursache: Dein Benutzer hat nicht die Rolle admin (die Datenbank enthielt bereits Benutzer aus einem vorherigen Versuch) und die Weiterleitung führt dich zu /board, was fehlschlagen kann, wenn noch keine Projekte erstellt wurden.

Lösung: Beginne von vorn, damit deine erste Registrierung im Modus initial_admin_setup erfolgt.

docker ps hängt / antwortet nicht​

Der Docker-Client wartet auf den Socket des Daemons. Wenn dieser Socket auf eine nicht laufende Runtime verweist, hängt der Client.

Schnelldiagnose:

docker context ls
# Mira que context tiene el `*` y a que socket apunta.

ls -la /var/run/docker.sock 2>&1
ls -la ~/.docker/run/docker.sock 2>&1
ls -la ~/.orbstack/run/docker.sock 2>&1
# El socket del context activo tiene que existir y tener permiso de escritura.

pgrep -lf -i 'OrbStack|Docker Desktop|colima' | head -5
# Tiene que aparecer al menos uno.

Korrekturen je nach Szenario:

  • Docker Desktop oder OrbStack ist installiert, aber die App ist geschlossen → Öffne die App: open -a OrbStack (oder open -a "Docker Desktop"). Warte 30-60 Sekunden und versuche docker ps erneut.
  • App gestartet, aber die VM ist blockiert → Schließe sie und öffne sie erneut; oder verwende colima stop && colima start, falls du Colima nutzt.
  • Du hast die Runtime gewechselt und der Kontext verweist auf die alte → docker context use colima (oder den richtigen Namen).
  • Mac als Server verwendet und du möchtest Neustarts überstehen → Migriere zu Colima als Service (siehe Docker-Runtime unter macOS).

lockfile had changes, but lockfile is frozen während des Builds​

RUN bun install --frozen-lockfile
error: lockfile had changes, but lockfile is frozen

Dies tritt auf, wenn das Stack-Repository einen neuen Bun-Workspace eingeführt hat und ein Dockerfile nicht aktualisiert wurde, um ihn in den Builder-Kontext zu kopieren. Es ist ein Fehler im Stack, nicht in deiner Installation.

Lösung: Führe einen git pull für das Stack-Repository aus, um die neueste Version mit der Korrektur zu erhalten, und versuche es erneut:

cd ~/.almirant/stack
git pull --ff-only origin main
almirant upgrade

Wenn deine Stack-Version älter als die Korrektur ist und du sie nicht aktualisieren kannst, füge vor bun install manuell die Zeile COPY services/<workspace>/package.json ./services/<workspace>/package.json in die betroffenen Dockerfiles ein.

Docker-Fehler mit Keychain unter macOS​

error getting credentials — err: exit status 1, out: keychain cannot be accessed erscheint, wenn du auf einem Mac ohne grafische Sitzung per SSH arbeitest.

Schnelle Lösung:

security unlock-keychain ~/Library/Keychains/login.keychain-db

Dauerhafte Lösung (nur falls du immer per SSH arbeitest):

# Desconecta Docker del keychain
jq 'del(.credsStore, .credHelpers)' ~/.docker/config.json > ~/.docker/config.json.tmp \
  && mv ~/.docker/config.json.tmp ~/.docker/config.json

Nächster Schritt​

Der Stack läuft, ein Administrator wurde erstellt und das Onboarding ist abgeschlossen. Um die Instanz im Alltag zu betreiben (Logs, Upgrades, Backups, URL-Änderungen), gehe zu Den Stack betreiben.