Zum Inhalt springen
vaultigen
Kostenlos starten

Erste Schritte

Installation mit Docker Compose

Vaultigen mit Docker Compose auf Ihrem eigenen Linux-Server installieren, der empfohlene Weg.

Dies ist der empfohlene Weg, Vaultigen zu betreiben. Sie laden zwei Konfigurationsdateien herunter, tragen Ihre Einstellungen ein und führen die Einrichtung in einem Container aus. Docker liefert die Anwendung, die PostgreSQL-Datenbank, die Hintergrunddienste und automatisches HTTPS. Sie brauchen kein PHP, Composer, Node.js und keinen Datenbankserver auf dem Host. Planen Sie etwa 30 Minuten ein, einschließlich des ersten Backups.

Sie möchten SQLite, MySQL oder MariaDB oder gar keine Container verwenden? Nutzen Sie die manuelle Installation. Beide Wege betreiben dieselbe Anwendung mit denselben Funktionen.

Bevor Sie beginnen: Legen Sie fest, wo Sie die Schlüssel der Installation aufbewahren. Die Einrichtung erzeugt Schlüsseldateien, und ihr Verlust macht Ihre Daten dauerhaft unlesbar. Halten Sie einen sicheren Ort außerhalb dieses Servers bereit und eine zweite Person, die darauf zugreifen kann.

1. Server vorbereiten

Sie brauchen:

  • Einen 64-Bit-x86-Linux-Server (AMD64) mit Docker Engine und dem Docker-Compose-Plugin. Folgen Sie der Installationsanleitung von Docker für Ihre Distribution. Siehe Voraussetzungen.
  • Einen Hostnamen wie vault.example.com, dessen DNS-Eintrag auf den Server zeigt (auch den IPv6-Eintrag, falls Sie einen veröffentlichen).
  • Die Ports 80 und 443, aus dem Internet erreichbar. Vaultigen bezieht und erneuert darüber sein HTTPS-Zertifikat. Belegt bereits eine andere Website oder ein Reverse Proxy diese Ports, lesen Sie vor der Einrichtung Bestehender Reverse Proxy.
  • Ein SMTP-Konto für Einladungen, Anmeldecodes und Benachrichtigungen.
  • Einen Ort außerhalb dieses Servers für Backups und die Schlüsselkopie.

Melden Sie sich per SSH mit einem Konto an, das Docker verwenden darf, und prüfen Sie:

docker version
docker compose version

Docker muss eine Client- und eine Server-Version anzeigen. Beheben Sie Berechtigungs- oder Verbindungsfehler, bevor Sie weitermachen. Halten Sie die Serveruhr synchron (NTP); Authenticator-Codes hängen davon ab.

2. Konfiguration herunterladen

Legen Sie ein dauerhaftes Verzeichnis an und laden Sie die Compose-Datei und die Konfigurationsvorlage der gewünschten Version herunter (hier 1.0.0; alle Versionen stehen im Changelog):

umask 077
mkdir -p ~/vaultigen && cd ~/vaultigen
VERSION=1.0.0
curl -fLO https://raw.githubusercontent.com/vaultigen/vaultigen/v$VERSION/scripts/docker/compose.yaml
curl -fL https://raw.githubusercontent.com/vaultigen/vaultigen/v$VERSION/scripts/docker/env.example -o .env
sed -i "s/^DB_PASSWORD=.*/DB_PASSWORD=$(openssl rand -hex 32)/" .env

Das Verzeichnis enthält jetzt compose.yaml und .env, und .env enthält ein zufälliges, 64 Zeichen langes Datenbankpasswort. Sie brauchen keinen Quellcode, kein Installationsskript und kein Registry-Konto. Woher Dateien und Images stammen, steht unter Download.

Führen Sie alle weiteren Befehle in ~/vaultigen aus. Alles, was die Installation speichert, liegt in diesem einen Verzeichnis; /opt/vaultigen funktioniert genauso.

3. Einstellungen eintragen

nano .env

Setzen Sie mindestens:

VAULTIGEN_IMAGE_TAG=1.0.0
VAULTIGEN_DOMAIN=vault.example.com
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME='[email protected]'
MAIL_PASSWORD='ihr-smtp-passwort'
MAIL_FROM_ADDRESS=[email protected]
MAIL_FROM_NAME='Vaultigen'
  • VAULTIGEN_IMAGE_TAG wählt die genaue Version für alle Anwendungsdienste. Die Vorlage enthält bereits die Version, aus der Sie sie heruntergeladen haben. Das Veröffentlichungsdatum im Image, das für die Lizenz zählt, ändert sie nie.
  • Für implizites TLS auf Port 465 setzen Sie zusätzlich MAIL_SCHEME=smtps und MAIL_PORT=465.
  • Lassen Sie das erzeugte DB_PASSWORD stehen und ändern Sie es nach der Installation nie. Die Einrichtung lehnt den Platzhalter change-me und alles unter 24 Zeichen ab.
  • Werte werden wörtlich gelesen, nie von einer Shell. Setzen Sie Werte mit $, #, Leerzeichen oder Anführungszeichen in einfache Anführungszeichen und maskieren Sie einen Apostroph als \'. Lesen Sie die Datei nicht mit source ein.

Die Vorlage aktiviert jede Nacht um 02:30 UTC ein geprüftes Backup (VAULTIGEN_BACKUP_SCHEDULE_ENABLED, VAULTIGEN_BACKUP_SCHEDULE, VAULTIGEN_BACKUP_TIMEZONE). Alle übrigen Einstellungen erklärt die Konfigurationsreferenz.

4. Einrichtung ausführen und Vaultigen starten

docker compose run --rm setup
docker compose up -d --wait

Der erste Befehl startet einen einmaligen Einrichtungscontainer aus dem Vaultigen-Image. Er startet die Datenbank, bereitet die Ordner data/ und backups/ vor, erzeugt die Installationsidentität und alle Schlüssel, wendet die Datenbankmigrationen an und fragt nach dem ersten Administrator: E-Mail, Name und ein Passwort mit mindestens 15 Zeichen, das in keinem bekannten Datenleck vorkommt. Er endet mit Setup completed.

Der zweite Befehl startet Webanwendung, Queue-Worker und Scheduler, sobald die Migrationsprüfung erfolgreich war, und wartet, bis sie gesund sind. Der Webdienst bezieht das HTTPS-Zertifikat automatisch.

Schlägt die Einrichtung fehl, beheben Sie das gemeldete Problem und führen Sie denselben Befehl erneut aus. Er setzt eine unvollständige Installation fort und ersetzt nie vorhandene Schlüssel oder einen vorhandenen Administrator. Um die E-Mail auf der Kommandozeile zu übergeben, nennen Sie zuerst die Rolle: docker compose run --rm setup setup [email protected].

5. Anmelden und Installation prüfen

  1. Öffnen Sie https://vault.example.com. Die Anmeldeseite muss über eine vertrauenswürdige HTTPS-Verbindung laden.
  2. Melden Sie sich an, richten Sie eine Authenticator-App ein und bewahren Sie die Wiederherstellungscodes außerhalb von Vaultigen auf.
  3. Öffnen Sie System → Installationsstatus. Queue und Scheduler werden innerhalb von etwa zwei Minuten grün.
  4. Laden Sie eine Adresse ein, die Sie kontrollieren, und prüfen Sie, ob die E-Mail ankommt.

Es gibt keinen Webserver zu installieren, keinen Cronjob und keine Service-Unit zu schreiben.

6. Schlüssel sichern

Ohne die ursprünglichen Schlüssel lassen sich Backups nicht wiederherstellen. Die Einrichtung legt sie in ~/vaultigen/data/keys/ ab. Kopieren Sie den Ordner direkt nach der Einrichtung vom Server weg:

umask 077
sudo tar -czf vaultigen-keys.tar.gz -C ~/vaultigen/data keys
sudo chown "$USER" vaultigen-keys.tar.gz

Die Dateien gehören dem Anwendungsbenutzer des Containers, deshalb braucht das Lesen sudo. Das Archiv enthält den Anwendungsschlüssel, die Installationsidentität, den KEK-Schlüsselbund der Installation und den Backup-Schlüsselbund: Wer es und ein Backup besitzt, kann Ihre Tresore lesen. Bewahren Sie es zusammen mit einer Kopie von .env im verschlüsselten Speicher oder Offline-Wiederherstellungsprozess Ihrer Organisation auf, getrennt von den Backups, und stellen Sie sicher, dass eine zweite Person es abrufen kann. Löschen Sie danach das lokale Archiv. Sichern Sie nach jeder Schlüsselrotation eine neue Kopie. Siehe Schlüsselverwaltung.

7. Erstes Backup erstellen und Wiederherstellung üben

docker compose exec web php artisan vaultigen:backup

Der Befehl endet mit Backup completed und gibt den geprüften Satz aus, zum Beispiel /backups/01234567-89ab-cdef-0123-456789abcdef; auf dem Host ist das ~/vaultigen/backups/01234567-…. Richten Sie danach die nächtliche Kopie vom Server weg ein, wie unter Backups beschrieben, und führen Sie eine Wiederherstellungsübung auf einem separaten Server durch, bevor Sie echte Passwörter speichern.

Wo die Installation liegt

Ort Inhalt
compose.yaml Dienstdefinitionen. Bleibt bei Updates normalerweise unverändert.
.env Image-Version, Domain, Datenbankpasswort, Mail- und Backup-Einstellungen. Bewahren Sie eine Kopie außerhalb des Servers auf.
data/postgres/ Die PostgreSQL-Datenbank. Durch die Backup-Sätze geschützt.
data/storage/ Verschlüsselte Anhänge, aufbewahrte Importdateien und Laufzeitdateien. Die Backup-Sätze enthalten, was die Wiederherstellung braucht.
data/keys/ app.key, installation.json, kek.json, backup.json. Nie Teil eines Backup-Satzes; durch Ihre Schlüsselkopie geschützt.
data/caddy/ Zustand des HTTPS-Zertifikats. Für die Wiederherstellung nicht nötig; ein neues Zertifikat wird automatisch bezogen.
backups/ Abgeschlossene, geprüfte, verschlüsselte Backup-Sätze, ein Ordner pro Satz.

Die Ordner unter data/ und backups/ gehören den Container-Benutzern; Lesen vom Host aus braucht sudo. Ändern Sie weder Besitzer noch Berechtigungen. Stoppen, Neuerstellen oder Aktualisieren der Container löscht sie nie.

Befehle für den Alltag

docker compose ps                                      # Zustand und Gesundheit aller Dienste
docker compose logs --tail=100 web worker scheduler    # aktuelle Ausgaben der Anwendung
docker compose up -d --wait                            # Änderungen an .env übernehmen
docker compose stop                                    # stoppen, alle Daten bleiben erhalten

docker compose ps zeigt database, web, worker und scheduler als laufend und gesund. Der Dienst migrate läuft bei jedem Start, prüft Schlüssel und Migrationen und beendet sich; docker compose ps -a zeigt ihn als beendet mit Code 0.

Nach Änderungen an .env führen Sie docker compose up -d --wait aus: Compose erstellt die betroffenen Container neu, damit sie die neuen Werte lesen. Ein einfaches restart übernimmt geänderte Einstellungen nicht. Laufende Dienste starten nach einem Neustart des Servers automatisch wieder. Zum Wechsel der Version folgen Sie Aktualisieren.

Konsolenbefehle der Anwendung führen Sie im Web-Container aus, zum Beispiel docker compose exec web php artisan vaultigen:backup:verify /backups/<id>.

Bestehender Reverse Proxy

Läuft auf dem Server bereits ein Reverse Proxy auf den Ports 80 und 443, lassen Sie ihn HTTPS terminieren und an Vaultigen weiterleiten. Laden Sie vor der Einrichtung die Ergänzungsdatei herunter (sie braucht Docker Compose 2.24.4 oder neuer) und wählen Sie sie in .env aus (dieselbe Version wie compose.yaml):

curl -fLO https://raw.githubusercontent.com/vaultigen/vaultigen/v1.0.0/scripts/docker/compose.proxy.yaml
echo 'COMPOSE_FILE=compose.yaml:compose.proxy.yaml' >> .env

Vaultigen bedient dann nur unverschlüsseltes HTTP auf 127.0.0.1:8080 und bezieht kein Zertifikat. Richten Sie den Proxy auf diese Adresse und leiten Sie Host, X-Forwarded-For und X-Forwarded-Proto weiter. Lassen Sie VAULTIGEN_DOMAIN auf dem öffentlichen Hostnamen. Compose liest COMPOSE_FILE selbst, alle anderen Befehle auf dieser Website bleiben gleich. Bewahren Sie die Ergänzungsdatei mit Ihrer Wiederherstellungskopie von .env auf.

Ein Proxy auf demselben Host wird automatisch vertraut: Die Ergänzung gibt Vaultigen ein festes privates Netz (172.31.250.0/24) und vertraut nur dessen Gateway, über das Docker den Loopback-Port weiterleitet.

  • Kollidiert dieses Netz mit einem bestehenden, setzen Sie VAULTIGEN_NETWORK_SUBNET, VAULTIGEN_NETWORK_GATEWAY, VAULTIGEN_NETWORK_RANGE und VAULTIGEN_WEB_ADDRESS auf einen anderen privaten Bereich.
  • Ein Proxy in einem anderen Container oder auf einem anderen Host braucht VAULTIGEN_TRUSTED_PROXIES mit seiner Adresse und einen Netzwerkweg zum Webdienst.
  • Mit rootless Podman statt Docker kommt die Verbindung von der eigenen Adresse des Web-Containers; setzen Sie VAULTIGEN_TRUSTED_PROXIES=172.31.250.10.

Die öffentliche HTTPS-Adresse muss Vaultigen dann über Ihren Proxy öffnen, und Vaultigen darf die Ports 80 und 443 nicht belegen.

Weiter: Erste Schritte.

Einen Fehler gefunden? Schreiben Sie uns an [email protected].