Umami mit Docker in­stal­lie­ren: Schritt-für-Schritt-Anleitung

Mit Umami betreiben Sie eine da­ten­schutz­ori­en­tier­te Web­ana­ly­se auf Ihrem eigenen Server und behalten die Kontrolle über die erhobenen Ana­ly­se­da­ten. Diese Anleitung zeigt Schritt für Schritt, wie Sie Umami mithilfe von Docker, Post­greS­QL und einer ver­schlüs­sel­ten HTTPS-Ver­bin­dung auf einem VPS in­stal­lie­ren.

Schritt 1: Passenden Server für Umami auswählen

Für die selbst gehostete Version von Umami benötigen Sie einen vir­tu­el­len privaten Server, kurz VPS. Dabei handelt es sich um einen dauerhaft mit dem Internet ver­bun­de­nen Computer, den Sie über eine Kom­man­do­zei­le verwalten. Für Umami selbst müssen Sie keine kos­ten­pflich­ti­ge Soft­ware­li­zenz ab­schlie­ßen. Das Projekt steht unter der MIT-Lizenz. Kosten entstehen daher vor allem für den VPS, eine optionale Domain und ge­ge­be­nen­falls zu­sätz­li­che Backups.

Die benötigte Ser­ver­leis­tung hängt davon ab, wie viele Websites Sie erfassen, wie stark diese besucht werden und wie lange Sie die Ana­ly­se­da­ten speichern möchten. Die folgende Übersicht ori­en­tiert sich an aktuell ver­füg­ba­ren VPS-Leis­tungs­stu­fen. Die Angaben sind als leicht ver­ständ­li­che Aus­gangs­punk­te und nicht als feste Ka­pa­zi­täts­gren­zen zu verstehen.

Für die meisten kleinen Un­ter­neh­men ist die Variante mit 4 vCores, 4 GB RAM und 120 GB NVMe-Speicher ein sinn­vol­ler Aus­gangs­punkt. Ein Upgrade auf eine größere Ser­ver­stu­fe ist später möglich, falls Spei­cher­ver­brauch oder Aus­las­tung deutlich ansteigen.

Zu­sätz­lich benötigen Sie:

• ein 64-Bit-Linux-System,
• einen User mit Ad­mi­nis­tra­tor­rech­ten,
• eine öf­fent­li­che IPv4-Adresse,
• eine Domain oder Subdomain wie analytics.example.de,
• einen Computer mit Terminal be­zie­hungs­wei­se SSH-Programm,
• Zugriff auf die DNS-Ein­stel­lun­gen Ihrer Domain.

Schritt 2: VPS mit Ubuntu be­reit­stel­len und Netz­werk­zu­gän­ge festlegen

Erstellen Sie im Ver­wal­tungs­be­reich Ihres Hosting-Anbieters einen neuen VPS. Wählen Sie als Be­triebs­sys­tem Ubuntu 24.04 LTS oder 26.04 LTS in der 64-Bit-Version. Diese Versionen werden offiziell von Docker un­ter­stützt und sind für eine pro­duk­ti­ve In­stal­la­ti­on gut geeignet.

Wenn der Anbieter die Anmeldung mit einem SSH-Schlüssel er­mög­licht, sollten Sie diese Variante einem reinen Pass­wort­zu­gang vorziehen. Der öf­fent­li­che Teil des Schlüs­sels wird beim Server hin­ter­legt. Der private Schlüssel bleibt aus­schließ­lich auf Ihrem Computer und darf nicht wei­ter­ge­ge­ben werden.

Öffnen Sie in der Firewall des Hosting-Anbieters nur die tat­säch­lich be­nö­tig­ten ein­ge­hen­den Ver­bin­dun­gen:

Close

Die später intern ver­wen­de­ten Ports 3000 für Umami und 5432 für Post­greS­QL dürfen nicht öf­fent­lich frei­ge­ge­ben werden. Beide Dienste kom­mu­ni­zie­ren aus­schließ­lich innerhalb des Docker-Netzwerks. Notieren Sie nach der Be­reit­stel­lung die öf­fent­li­che IP-Adresse und den Namen des ad­mi­nis­tra­ti­ven Users.

Schritt 3: Über SSH mit dem Server verbinden

Öffnen Sie auf Ihrem Computer ein Terminal. Unter macOS und Linux ist bereits ein SSH-Programm vorhanden. Unter aktuellen Windows-Versionen können Sie SSH in der Power­Shell oder im Windows Terminal verwenden.

Geben Sie folgenden Befehl ein und ersetzen Sie die beiden Platz­hal­ter:

ssh SERVERBENUTZER@SERVER_IP

Bei der ersten Ver­bin­dung erscheint eine Rückfrage zum Fin­ger­ab­druck des Servers. Kon­trol­lie­ren Sie nach Mög­lich­keit, ob der an­ge­zeig­te Fin­ger­ab­druck mit der Angabe Ihres Hosting-Anbieters über­ein­stimmt. Be­stä­ti­gen Sie die Ver­bin­dung an­schlie­ßend mit yes.

Ak­tua­li­sie­ren Sie nach der Anmeldung zunächst die Pa­ket­lis­ten und die bereits in­stal­lier­te Software:

sudo apt update
sudo apt upgrade -y

Der erste Befehl lädt In­for­ma­tio­nen zu ver­füg­ba­ren Paketen. Der zweite Befehl in­stal­liert die Ak­tua­li­sie­run­gen. Falls während der Ak­tua­li­sie­rung ein neuer Sys­tem­kern in­stal­liert wurde, starten Sie den Server neu:

sudo reboot

Die SSH-Ver­bin­dung wird dadurch getrennt. Warten Sie kurz, bis der Server wieder er­reich­bar ist, und melden Sie sich danach erneut mit dem SSH-Befehl an.

Schritt 4: Docker und Docker Compose in­stal­lie­ren

Docker führt An­wen­dun­gen in von­ein­an­der ge­trenn­ten Con­tai­nern aus. Für diese In­stal­la­ti­on werden drei Container verwendet:

• Umami stellt die Web­ober­flä­che und die Ana­ly­se­funk­tio­nen bereit.
• Post­greS­QL speichert die erfassten Daten.
• Caddy nimmt Web­an­fra­gen entgegen und stellt die ver­schlüs­sel­te HTTPS-Ver­bin­dung her.

Docker Compose be­schreibt alle drei Container in einer ge­mein­sa­men Kon­fi­gu­ra­ti­ons­da­tei. Dadurch lässt sich die voll­stän­di­ge In­stal­la­ti­on später mit wenigen Befehlen starten, stoppen und ak­tua­li­sie­ren.

In­stal­lie­ren Sie zunächst die be­nö­tig­ten Hilfs­pro­gram­me:

sudo apt update
sudo apt install -y ca-certificates curl

Legen Sie an­schlie­ßend den Spei­cher­ort für den of­fi­zi­el­len Docker-Schlüssel an:

sudo install -m 0755 -d /etc/apt/keyrings

Laden Sie den Si­gna­tur­schlüs­sel des of­fi­zi­el­len Docker-Pa­ket­ar­chivs herunter:

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
    -o /etc/apt/keyrings/docker.asc

Erlauben Sie dem Pa­ket­ma­na­ger, den Schlüssel zu lesen:

sudo chmod a+r /etc/apt/keyrings/docker.asc

Fügen Sie danach das of­fi­zi­el­le Docker-Pa­ket­ar­chiv hinzu:

sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

Ak­tua­li­sie­ren Sie die Pa­ket­lis­ten erneut:

sudo apt update

In­stal­lie­ren Sie nun Docker Engine, die Kom­man­do­zei­len­werk­zeu­ge und das Docker-Compose-Plug-in:

sudo apt install -y \
    docker-ce \
    docker-ce-cli \
    containerd.io \
    docker-buildx-plugin \
    docker-compose-plugin

Ak­ti­vie­ren und starten Sie Docker:

sudo systemctl enable --now docker

Über­prü­fen Sie die In­stal­la­ti­on mit einem Test­con­tai­ner:

sudo docker run hello-world

Erscheint eine Er­folgs­mel­dung, funk­tio­niert Docker.

Close

Kon­trol­lie­ren Sie zu­sätz­lich Docker Compose:

sudo docker compose version

Close

Schritt 5: Domain oder Subdomain mit dem Server verbinden

Um Umami später über eine leicht merkbare und ver­schlüs­sel­te Adresse auf­zu­ru­fen, sollten Sie eine Subdomain verwenden. Öffnen Sie die DNS-Ver­wal­tung der be­tref­fen­den Domain. Erstellen Sie dort einen A-Record mit folgenden Angaben:

Verfügt Ihr Server zu­sätz­lich über eine korrekt kon­fi­gu­rier­te öf­fent­li­che IPv6-Adresse, können Sie ergänzend einen AAAA-Record anlegen. Die Änderung kann abhängig vom bis­he­ri­gen TTL-Wert einige Zeit benötigen. Prüfen Sie auf dem Server, ob die Domain bereits auf die richtige IP-Adresse verweist:

getent hosts analytics.example.de

Ersetzen Sie analytics.example.de durch Ihre tat­säch­li­che Subdomain. Die Ausgabe sollte die IP-Adresse Ihres Servers enthalten.

Caddy kann ein öf­fent­lich an­er­kann­tes TLS-Zer­ti­fi­kat au­to­ma­tisch aus­stel­len, wenn der DNS-Eintrag auf den Server zeigt und die Ports 80 sowie 443 von außen er­reich­bar sind. Caddy erneuert das Zer­ti­fi­kat später ebenfalls au­to­ma­tisch und leitet un­ver­schlüs­sel­te HTTP-Aufrufe auf HTTPS um.

Schritt 6: Ver­zeich­nis und sichere Zu­gangs­da­ten für Umami erstellen

Legen Sie ein eigenes Ver­zeich­nis für die In­stal­la­ti­on an:

sudo mkdir -p /opt/umami
sudo chown "$USER":"$USER" /opt/umami
cd /opt/umami

In diesem Ver­zeich­nis werden die Docker-Kon­fi­gu­ra­ti­on, die HTTPS-Kon­fi­gu­ra­ti­on und die geheimen Zu­gangs­da­ten ge­spei­chert. In­stal­lie­ren Sie das Werkzeug OpenSSL, falls es noch nicht vorhanden ist:

sudo apt install -y openssl

Erzeugen Sie an­schlie­ßend ein zu­fäl­li­ges sicheres Da­ten­bank­pass­wort, einen geheimen An­wen­dungs­schlüs­sel sowie einen separaten Schlüssel für die optionale Zwei-Faktor-Au­then­ti­fi­zie­rung:

DB_PASSWORD=$(openssl rand -hex 24)
UMAMI_SECRET=$(openssl rand -hex 32)
TWO_FACTOR_KEY=$(openssl rand -hex 32)

Speichern Sie diese drei Werte in einer Datei namens .env:

printf "POSTGRES_PASSWORD=%s\nAPP_SECRET=%s\nTWO_FACTOR_ENCRYPTION_KEY=%s\n" \
"$DB_PASSWORD" "$UMAMI_SECRET" "$TWO_FACTOR_KEY" > .env

Entfernen Sie die tem­po­rä­ren Variablen danach aus der aktuellen Ter­mi­nal­sit­zung:

unset DB_PASSWORD UMAMI_SECRET TWO_FACTOR_KEY

Be­schrän­ken Sie den Zugriff auf die Datei:

chmod 600 .env

Ver­öf­fent­li­chen Sie die .env-Datei niemals. Das APP_SECRET schützt unter anderem die von Umami ver­wen­de­ten An­mel­de­to­ken.

Schritt 7: Docker-Compose-Datei für Umami erstellen

Erstellen Sie im Ver­zeich­nis /opt/umami eine neue Datei:

nano compose.yml

Fügen Sie den folgenden Inhalt ein:

services:
    db:
        image: postgres:15-alpine
        restart: unless-stopped
        environment:
            POSTGRES_DB: umami
            POSTGRES_USER: umami
            POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
        volumes:
            - umami_db_data:/var/lib/postgresql/data
        healthcheck:
            test:
                - CMD-SHELL
                - pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}
            interval: 5s
            timeout: 5s
            retries: 10
    umami:
        image: ghcr.io/umami-software/umami:latest
        restart: unless-stopped
        init: true
        environment:
            DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD}@db:5432/umami
            APP_SECRET: ${APP_SECRET}
            TWO_FACTOR_ENCRYPTION_KEY: ${TWO_FACTOR_ENCRYPTION_KEY}
        depends_on:
            db:
                condition: service_healthy
        expose:
            - "3000"
        healthcheck:
            test:
                - CMD-SHELL
                - curl -f http://localhost:3000/api/heartbeat || exit 1
            interval: 10s
            timeout: 5s
            retries: 10
    caddy:
        image: caddy:2-alpine
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
            - "443:443/udp"
        volumes:
            - ./Caddyfile:/etc/caddy/Caddyfile:ro
            - caddy_data:/data
            - caddy_config:/config
        depends_on:
            umami:
                condition: service_healthy
volumes:
    umami_db_data:
    caddy_data:
    caddy_config:

Close

Der Abschnitt volumes sorgt dafür, dass die Datenbank nicht zusammen mit dem Container gelöscht wird. Ein Container kann dadurch ak­tua­li­siert oder neu erstellt werden, ohne dass die ge­spei­cher­ten Ana­ly­se­da­ten verloren gehen.

Die Einträge unter expose machen Port 3000 nur innerhalb des Docker-Netzes er­reich­bar. Die Datenbank besitzt überhaupt keine öf­fent­li­che Port­frei­ga­be. Ent­schei­dend ist, dass der Umami-Dienst keinen Eintrag unter ports besitzt. Port 3000 kann daher nicht direkt über die öf­fent­li­che IP-Adresse des VPS auf­ge­ru­fen werden. Von außen sind lediglich die für Caddy vor­ge­se­he­nen Ports 80 und 443 er­reich­bar.

Schritt 8: HTTPS-Proxy mit Caddy kon­fi­gu­rie­ren

Erstellen Sie die Caddy-Kon­fi­gu­ra­ti­on:

nano Caddyfile

Fügen Sie folgenden Inhalt ein und ersetzen Sie die Bei­spiel­do­main:

analytics.example.de {
    encode zstd gzip
    reverse_proxy umami:3000
}

Close

Speichern und schließen Sie die Datei wieder. Der Eintrag reverse_proxy umami:3000 bedeutet, dass Caddy ein­ge­hen­de Anfragen an den Umami-Container wei­ter­lei­tet. Die Be­zeich­nung umami ent­spricht dem Ser­vice­na­men aus der Compose-Datei. Docker löst diesen Namen au­to­ma­tisch innerhalb des ge­mein­sa­men Netzwerks auf.

Sobald Caddy mit einer öf­fent­li­chen Domain gestartet wird, versucht es au­to­ma­tisch, ein gültiges TLS-Zer­ti­fi­kat aus­zu­stel­len. Dafür müssen der DNS-Eintrag stimmen und die Ports 80 sowie 443 er­reich­bar sein.

Kon­trol­lie­ren Sie, ob alle be­nö­tig­ten Dateien vorhanden sind:

ls -la

Die Ausgabe sollte min­des­tens folgende Dateien enthalten:

• .env
• Caddyfile
• compose.yml

Close

Schritt 9: Umami-Container starten und In­stal­la­ti­on prüfen

Lassen Sie Docker Compose zunächst über­prü­fen, ob die Kon­fi­gu­ra­ti­on gültig ist:

sudo docker compose config -q

Der Befehl prüft die Compose-Kon­fi­gu­ra­ti­on auf Fehler, ohne die auf­ge­lös­ten Kon­fi­gu­ra­ti­ons­wer­te im Terminal aus­zu­ge­ben. Laden Sie an­schlie­ßend die be­nö­tig­ten Container-Images herunter:

sudo docker compose pull

Starten Sie die voll­stän­di­ge In­stal­la­ti­on im Hin­ter­grund:

sudo docker compose up -d

Docker erstellt nun das ge­mein­sa­me Netzwerk, das Post­greS­QL-Volume und die drei Container. Prüfen Sie an­schlie­ßend den Status:

sudo docker compose ps

Nach der Start­pha­se sollten der Datenbank- und der Umami-Container als healthy angezeigt werden. Der Caddy-Container sollte den Status Up besitzen.

Öffnen Sie danach Ihre Umami-Adresse im Browser:

https://analytics.example.de

Beim ersten Start kann die Aus­stel­lung des Zer­ti­fi­kats einen kurzen Moment dauern. Danach sollte die Umami-An­mel­de­sei­te über eine ver­schlüs­sel­te HTTPS-Ver­bin­dung er­schei­nen.

Close

Schritt 10: Zum ersten Mal bei Umami anmelden

Die of­fi­zi­el­le Docker-In­stal­la­ti­on erstellt stan­dard­mä­ßig folgendes Ad­mi­nis­tra­tor­kon­to:

• Be­nut­zer­na­me: admin
• Passwort: umami

Close

Diese Stan­dard­zu­gangs­da­ten sind öf­fent­lich bekannt und müssen daher un­mit­tel­bar geändert werden. Melden Sie sich an und öffnen Sie an­schlie­ßend über das Be­nut­zer­me­nü die Ein­stel­lun­gen be­zie­hungs­wei­se das Profil. Ändern Sie dort das Kennwort des Ad­mi­nis­tra­tor­kon­tos und verwenden Sie dazu ein langes, sicheres Passwort, das Sie nicht für andere Dienste einsetzen.

Close

Optional können Sie zu­sätz­lich die Zwei-Faktor-Au­then­ti­fi­zie­rung ak­ti­vie­ren. Öffnen Sie dazu die Ein­stel­lun­gen und wechseln Sie zu „Security“. Dort lässt sich 2FA mit einer Au­then­ti­ca­tor-App ein­rich­ten. Bewahren Sie die an­schlie­ßend erzeugten Backup-Codes sicher auf.

Kon­trol­lie­ren Sie außerdem, ob die in Umami an­ge­zeig­te Zeitzone zu Ihrem Standort passt. Eine korrekte Zeitzone ist wichtig, damit Ta­ges­wer­te und zeitliche Aus­wer­tun­gen richtig dar­ge­stellt werden.

Schritt 11: Erste Website in Umami hin­zu­fü­gen

Öffnen Sie in Umami den Bereich Websites und wählen Sie die Funktion zum Hin­zu­fü­gen einer neuen Website. Tragen Sie einen ver­ständ­li­chen Namen und die Domain der zu ana­ly­sie­ren­den Website ein. Geben Sie die Domain ohne Pfad ein. Nutzen Sie die Schreib­wei­se, unter der die Website tat­säch­lich er­reich­bar ist.

Close

Speichern Sie die Website. Öffnen Sie danach die Be­ar­bei­tungs­an­sicht und suchen Sie den Abschnitt Tracking code. Umami erzeugt dort au­to­ma­tisch einen in­di­vi­du­el­len Code mit einer Website-ID, den Sie einfach kopieren können.

Close

Seit Umami 3.1 lassen sich zu­sätz­lich Core Web Vitals erfassen. Dafür ergänzen Sie im Code data-performance="true":

<script
    defer
    src="https://analytics.example.de/script.js"
    data-website-id="IHRE-WEBSITE-ID"
    data-domains="example.de,www.example.de"
    data-performance="true"
></script>

Damit kann Umami unter anderem LCP, INP, CLS, FCP und TTFB auswerten.

Damit ist die Umami-In­stal­la­ti­on voll­stän­dig ein­ge­rich­tet. Die Anwendung läuft in ge­trenn­ten Docker-Con­tai­nern, die Post­greS­QL-Datenbank ist nicht öf­fent­lich er­reich­bar und Caddy stellt au­to­ma­tisch eine ver­schlüs­sel­te HTTPS-Ver­bin­dung bereit.

Schritt 12: Backup und Wie­der­her­stel­lung

Ein Docker-Volume ersetzt kein Backup. Sichern Sie die Post­greS­QL-Datenbank daher re­gel­mä­ßig und bewahren Sie die Sicherung außerhalb des VPS auf:

sudo docker compose exec -T db \
    pg_dump -U umami -d umami -Fc > umami-backup.dump

Dieser Befehl sichert nur die Datenbank. Bewahren Sie zu­sätz­lich compose.yml, Caddyfile und die geheimen Werte aus .env sicher auf. Diese Dateien werden für eine voll­stän­di­ge Wie­der­her­stel­lung der In­stal­la­ti­on benötigt.

Prüfen Sie die Wie­der­her­stel­lung zunächst in einer Test­in­stal­la­ti­on. Wenn Sie eine be­stehen­de In­stal­la­ti­on wie­der­her­stel­len, halten Sie Umami vorher an:

sudo docker compose stop umami

Der folgende Befehl löscht die im Backup ent­hal­te­nen Da­ten­bank­ob­jek­te in der Ziel­da­ten­bank und stellt sie aus der Sicherung wieder her. Daten, die seit dem Backup hin­zu­ge­kom­men sind, gehen dabei verloren:

sudo docker compose exec -T db \
    pg_restore -U umami -d umami --clean --if-exists --no-owner \
    < umami-backup.dump

Starten Sie Umami an­schlie­ßend erneut:

sudo docker compose start umami

Die Si­che­rungs­da­tei umami-backup.dump liegt bei diesen Befehlen im aktuellen Ver­zeich­nis. Denken Sie daher daran, die genannten Befehle im In­stal­la­ti­ons­ver­zeich­nis /opt/umami aus­zu­füh­ren.