Semaphore UI per Docker installieren¶

Veröffentlicht am 22. August 2026 · Geschätzte Lesezeit: 4 Minuten

Wiederkehrende Serveraufgaben lassen sich mit Semaphore UI über eine Weboberfläche starten, planen und protokollieren. Das Werkzeug führt unter anderem Ansible-Playbooks aus und hält Zugänge verschlüsselt in seiner Datenbank. Für Installation und Grundabsicherung brauchst du etwa 20 Minuten.

Voraussetzungen

Ein Linux-Server mit Docker und Docker Compose
Der Port 3000 ist im Heimnetz frei
OpenSSL und base64 sind installiert
Grundkenntnisse zu SSH und Ansible für spätere Aufgaben

1. Arbeitsordner anlegen¶

Führe den Befehl auf dem Docker-Server aus. Er erstellt den Projektordner und wechselt hinein:

mkdir -p ~/docker/semaphore-ui && cd ~/docker/semaphore-ui

2. Geheimnisse erzeugen¶

Semaphore benötigt ein Passwort für das erste Administratorkonto und einen Schlüssel zum Verschlüsseln gespeicherter Zugangsdaten. Dieser Befehl erzeugt beide Werte zufällig und schreibt sie in .env:

printf 'SEMAPHORE_ADMIN_PASSWORD=%s\nSEMAPHORE_ACCESS_KEY_ENCRYPTION=%s\n' "$(openssl rand -base64 24)" "$(head -c32 /dev/urandom | base64)" > .env

Schütze die Datei vor anderen Benutzern auf dem Server:

chmod 600 .env

Zeige das erzeugte Administratorpasswort einmal an und übernimm es direkt in deinen Passwortmanager:

sed -n 's/^SEMAPHORE_ADMIN_PASSWORD=//p' .env

Verschlüsselungsschlüssel sichern

Ohne SEMAPHORE_ACCESS_KEY_ENCRYPTION können wiederhergestellte Zugangsdaten unbrauchbar werden. Sichere .env verschlüsselt und lege sie niemals in ein öffentliches Repository.

3. Compose-Datei anlegen¶

Lege im Ordner ~/docker/semaphore-ui eine Datei compose.yaml mit diesem Inhalt an:

services:
  semaphore:
    image: semaphoreui/semaphore:latest
    container_name: semaphore-ui
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      SEMAPHORE_DB_DIALECT: sqlite
      SEMAPHORE_DB: /etc/semaphore/semaphore.sqlite
      SEMAPHORE_PLAYBOOK_PATH: /tmp/semaphore
      SEMAPHORE_ADMIN: admin
      SEMAPHORE_ADMIN_NAME: Administrator
      SEMAPHORE_ADMIN_EMAIL: admin@localhost
      SEMAPHORE_ADMIN_PASSWORD: ${SEMAPHORE_ADMIN_PASSWORD}
      SEMAPHORE_ACCESS_KEY_ENCRYPTION: ${SEMAPHORE_ACCESS_KEY_ENCRYPTION}
      TZ: Europe/Berlin
    volumes:
      - semaphore-data:/etc/semaphore

volumes:
  semaphore-data:
    name: semaphore-data

Diese einfache Einzelserver-Installation nutzt die von Semaphore unterstützte SQLite- Datenbank. Das benannte Volume semaphore-data bewahrt Daten und Einstellungen dauerhaft auf.

4. Konfiguration prüfen und starten¶

Prüfe im Projektordner zuerst die Compose-Syntax:

docker compose config --quiet

Starte danach den Container im Hintergrund:

docker compose up -d

Kontrolliere den Zustand:

docker compose ps

Wenn der Container nicht läuft, zeigen die letzten Protokollzeilen meist die Ursache:

docker compose logs --tail=100 semaphore

5. Erste Anmeldung absichern¶

Öffne im Heimnetz http://<server-ip>:3000. Ersetze <server-ip> durch die feste IP-Adresse des Docker-Servers. Melde dich mit dem Benutzernamen admin und dem zuvor gesicherten Passwort an.

Öffne das Benutzerprofil und ersetze admin@localhost durch deine tatsächliche Adresse. Lege für tägliche Arbeiten später einen eigenen Benutzer mit den wirklich benötigten Rechten an.

Kein direkter Internetzugriff

Leite Port 3000 nicht im Router weiter. Semaphore kann SSH-Schlüssel und andere geheime Werte verwalten. Für Fernzugriff brauchst du ein privates VPN oder einen korrekt abgesicherten HTTPS-Reverse-Proxy.

6. Leeres Projekt als Funktionstest anlegen¶

Wähle New Project, vergib den Namen Homelab und speichere das Projekt. Öffne es danach erneut. Die Bereiche für Inventar, Repositories, Schlüssel und Aufgabenvorlagen müssen sichtbar sein. Damit sind Weboberfläche und Datenbank grundsätzlich funktionsfähig.

SSH-Zugänge sparsam berechtigen

Verwende für spätere Ansible-Aufgaben keinen dauerhaften Root-Zugang. Lege auf den Zielsystemen einen eigenen Automationsbenutzer an und erlaube mit sudo nur die wirklich benötigten Befehle. Private Schlüssel gehören in den Semaphore-Schlüsselspeicher, nicht in Playbooks oder Git-Repositories.

7. Backup anlegen¶

Stoppe Semaphore kurz, damit sich die SQLite-Datei während der Sicherung nicht verändert:

docker compose stop semaphore

Lege den Backup-Ordner an:

mkdir -p backup

Sichere den gesamten Inhalt des Volumes in ein datiertes Archiv:

docker run --rm -v semaphore-data:/data:ro -v "$PWD/backup:/backup" alpine sh -c 'tar czf /backup/semaphore-data-$(date +%F).tar.gz -C /data .'

Starte Semaphore anschließend wieder:

docker compose start semaphore

Prüfe, ob das Archiv lesbar ist:

tar tzf backup/semaphore-data-<datum>.tar.gz | head

Ersetze <datum> durch das Datum im Dateinamen. Sichere außerdem .env und compose.yaml verschlüsselt an einem zweiten Ort.

8. Aktualisieren und zurückkehren¶

Erstelle vor dem Update ein Backup. Lade anschließend das neue freigegebene Image und ersetze den Container:

docker compose pull

docker compose up -d

Prüfe Anmeldung und Projektliste. Bei Problemen kannst du in compose.yaml vorübergehend den zuvor verwendeten Versions-Tag aus den offiziellen Releases statt latest eintragen. Lösche das Volume und die .env-Datei dabei nicht.

9. Typische Fehler¶

Port 3000 ist belegt: Prüfe mit sudo ss -ltnp | grep ':3000' und ändere nur die linke Portnummer, zum Beispiel auf 3001:3000.
Anmeldung schlägt fehl: Lies das Administratorpasswort erneut aus .env und prüfe mit docker compose config, ob die Variable eingesetzt wird.
Daten fehlen nach einem Neustart: Kontrolliere, ob weiterhin semaphore-data:/etc/semaphore eingebunden ist.
Zugangsdaten sind nach einer Wiederherstellung unlesbar: Die gesicherte .env mit dem ursprünglichen Verschlüsselungsschlüssel fehlt.

10. Quellen und Videos¶

Fertig¶

Semaphore UI läuft jetzt mit verschlüsseltem Zugangsspeicher und dauerhafter Datenbank im Heimnetz. Melde dich erneut an und öffne das Projekt Homelab. Bleibt es nach einem Container-Neustart erhalten, funktioniert auch die dauerhafte Speicherung.