Actual Budget auf dem eigenen VPS selbst hosten

Was Sie erstellen

Actual Budget ist eine selbst gehostete Anwendung für die Umschlagbudgetierung. Sie ist meist die Antwort, wenn Sie nach einer selbst hostbaren Alternative zu YNAB suchen. Der Server besteht aus einem Container, einem Daten-Volume und einem HTTPS-Namen. Alles, was ein normales Budget benötigt, läuft problemlos auf dem kleinsten mietbaren VPS. Der Server speichert hauptsächlich Dateien und synchronisiert sie.

Die Architektur sollten Sie verstehen, bevor Sie Befehle eingeben. Das Budget selbst ist eine SQLite-Datenbank. Sie befindet sich in Ihrem Browser und in jeder mobilen App. Der Server, den Sie gleich installieren, ist ein Synchronisierungsendpunkt. Er speichert die Kontoliste, die Budgetdateien und das Änderungsprotokoll. Dieses ermöglicht es einem Telefon und einem Laptop, denselben Stand zu behalten. Deshalb funktioniert die App weiterhin, wenn der Server nicht erreichbar ist. Deshalb geht Ihr Budget nicht verloren, wenn der Server ausfällt, solange mindestens ein Client noch eine Kopie besitzt.

Warum der Server HTTPS benötigt

Actual verlangt HTTPS, und das ist keine Formalität. Browser stellen die Web Crypto API, die Actual für die Ende-zu-Ende-Verschlüsselung verwendet, nur in dem bereit, was die Spezifikation als sicheren Kontext bezeichnet. Ein sicherer Kontext ist https:// oder http://localhost. Wenn Sie die Anwendung in einem Browser auf einem anderen Computer unter http://203.0.113.10:5006 laden, sind diese Funktionen nicht verfügbar, weil der Browser sie der Seite nicht bereitgestellt hat. Die offiziellen mobilen Builds lehnen außerdem eine reine http://-Server-URL ab.

Daher gibt es zwei praktikable Konfigurationen. Sie setzen ein gültiges Zertifikat für einen echten Namen vor den Container. Das ist die Vorgehensweise in diesem Leitfaden. Oder Sie geben dem Server mit ACTUAL_HTTPS_KEY und ACTUAL_HTTPS_CERT ein selbstsigniertes Zertifikat, wie es die Projektdokumentation beschreibt, und akzeptieren auf jedem Gerät eine Browserwarnung. Ein kostenloses Zertifikat von Let's Encrypt ist in fünf Minuten eingerichtet. Verwenden Sie daher die erste Option.

Actual Budget mit Docker Compose installieren

Installieren Sie zuerst Docker, wenn der Server neu aufgesetzt ist. Falls die Syntax von Compose-Dateien für Sie neu ist, behandelt der Leitfaden Docker-Compose-Grundlagen für einen VPS die unten verwendeten Felder.

sudo install -d -m 755 /opt/actual
sudo install -d -m 700 /opt/actual/data

Schreiben Sie /opt/actual/docker-compose.yml:

services:
  actual:
    image: actualbudget/actual-server:latest
    container_name: actual
    restart: unless-stopped
    ports:
      - '127.0.0.1:5006:5006'
    volumes:
      - ./data:/data

Drei Details in dieser Datei sind wichtig.

Das Image ist actualbudget/actual-server:latest. Das Projekt veröffentlicht es auf Docker Hub und spiegelt es unter ghcr.io/actualbudget/actual. Für Geräte mit geringer Leistung gibt es den Tag latest-alpine.

Der Container schreibt alle Daten unter /data. Darin befinden sich server-files, das account.sqlite mit Ihren Anmelde- und Sitzungstoken enthält, sowie user-files, das die Budgetdateien selbst enthält. Binden Sie diesen Pfad ein. Andernfalls löscht der nächste docker compose pull Ihr Budget. Mit ACTUAL_DATA_DIR können Sie den Pfad ändern. Der Standardwert ist jedoch geeignet.

Der Port wird nur auf 127.0.0.1 veröffentlicht. Ein einfaches 5006:5006 veröffentlicht ihn auf allen Schnittstellen. Docker schreibt seine eigenen Regeln vor ufw, sodass die Anwendung auch bei einer Firewall mit vollständiger Ablehnung aus dem Internet erreichbar wäre. Dieser unerwartete Effekt wird unter warum von Docker veröffentlichte Ports ufw umgehen erklärt. Durch die Bindung an die Loopback-Schnittstelle kann nur der Reverse-Proxy auf demselben Server darauf zugreifen.

Starten Sie den Container:

cd /opt/actual
docker compose up --detach
docker compose logs -f actual

Das Protokoll stabilisiert sich, sobald der Server meldet, dass er auf Port 5006 lauscht. Prüfen Sie den Dienst lokal, bevor Sie DNS konfigurieren:

curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5006/

Ein 200 bedeutet, dass die Anwendung Daten ausliefert. curl: (7) Failed to connect bedeutet, dass der Container nicht läuft. Mit docker compose ps sehen Sie, dass er beendet wurde. Die häufigste Ursache ist ein Berechtigungsproblem auf dem eingebundenen Volume. Im Protokoll ist es als Zeile vom Typ EACCES sichtbar.

Ein Zertifikat und einen echten Namen vorschalten

Verweisen Sie einen A-Record auf den VPS, budget.example.com, und warten Sie, bis der DNS-Eintrag aufgelöst wird. Installieren Sie anschließend nginx und stellen Sie das Zertifikat aus. Der Leitfaden Certbot unter Ubuntu 24.04 mit nginx beschreibt die Ausstellung und den Erneuerungs-Timer vollständig.

Der Proxy-Block:

server {
    listen 443 ssl;
    http2 on;
    server_name budget.example.com;

    ssl_certificate     /etc/letsencrypt/live/budget.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/budget.example.com/privkey.pem;

    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:5006;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

client_max_body_size ist die Zeile, die häufig vergessen wird. Die Budgetdatei wird bei einer vollständigen Synchronisierung vollständig hochgeladen. Nginx verwendet standardmäßig einen Request-Body von 1 MB. Sobald die Datei größer wird, schlägt die Synchronisierung fehl. Im nginx-Access-Log erscheint dann 413 Request Entity Too Large, während die Anwendung nur einen allgemeinen Synchronisierungsfehler anzeigt. Der Server hat eigene, separate Grenzwerte: ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB ist standardmäßig auf 20 gesetzt und ACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB auf 50. Setzen Sie daher das nginx-Limit über den für Sie geltenden Wert.

Neu laden und testen:

sudo nginx -t && sudo systemctl reload nginx
curl -fsS -o /dev/null -w '%{http_code}\n' https://budget.example.com/

Erster Start: das Passwort und Ihre erste Budgetdatei

Öffnen Sie https://budget.example.com in einem Browser. Auf dem ersten Bildschirm werden Sie aufgefordert, ein Serverpasswort festzulegen. Dieses eine Passwort schützt den gesamten Server. Erzeugen Sie daher ein langes, zufälliges Passwort und bewahren Sie es an einem Ort auf, an dem Sie es wiederfinden, zum Beispiel in einem selbst gehosteten Vaultwarden-Passwortmanager. Sie müssen keine Benutzerkonten anlegen. Der Server von Actual ist absichtlich auf ein einziges Passwort ausgelegt. Ein Budget zu teilen bedeutet daher, dieses Passwort zu teilen.

Erstellen Sie anschließend eine Budgetdatei. Actual fragt, ob die Ende-zu-Ende-Verschlüsselung aktiviert werden soll. Bestätigen Sie dies. Dann speichert der Server nur Chiffretext. Das ist die richtige Wahl für Finanzdaten auf einer gemieteten Maschine. Der Nachteil ist erheblich: Das Verschlüsselungspasswort gelangt nie zum Server. Wenn Sie es verlieren, ist die Datei verloren. Es gibt keine Möglichkeit zum Zurücksetzen. Schreiben Sie das Passwort auf, bevor Sie diesen Bildschirm verlassen.

Legen Sie Ihre Anfangssalden anhand der aktuellen Beträge Ihrer Bank fest, statt jahrelange Kontohistorien zu importieren. Die Umschlagbudgetierung arbeitet mit dem Geld, das Sie jetzt haben. Eine leere Historie verursacht Ihnen daher keine Nachteile.

Transaktionen importieren

Hier ist Ehrlichkeit wichtiger als Begeisterung, denn der Import ist der Hauptgrund, warum viele Nutzer bei selbst gehosteter Budgetplanung abspringen.

Die manuelle Eingabe ist die Grundlage und funktioniert immer. Bei einer Umschlagmethode ist sie arguably der eigentliche Zweck, denn durch das Eingeben eines Kaufs achten Sie darauf.

Der Dateiimport erledigt den Großteil. Actual liest CSV, QIF, OFX und QFX, und jede Bank exportiert mindestens eines dieser Formate. Importieren Sie jedes Konto über die Kontoansicht, ordnen Sie die Spalten einmal zu, und Actual merkt sich dieses Layout für das Konto.

Eine automatische Banksynchronisierung ist verfügbar. Sie benötigt einen Dienst eines Drittanbieters, weil der Server nicht selbst mit Banken kommunizieren kann. Actual unterstützt SimpleFIN Bridge für nordamerikanische Banken, Enable Banking für Europa, Akahu für Neuseeland und Pluggy.ai für Brasilien. GoCardless wird weiterhin unterstützt, nimmt aber keine neuen Konten an. Sie registrieren sich selbst beim Anbieter, erzeugen die Zugangsdaten und fügen sie dem Server hinzu. SimpleFIN Bridge kostet im Juli 2026 15 US-Dollar pro Jahr für bis zu 25 Institute. Die anderen Anbieter haben andere Preise.

Bevor Sie sich darauf verlassen, müssen Sie zwei Einschränkungen akzeptieren. Die API-Zugangsdaten liegen auf dem Server und sind nicht durch Ende-zu-Ende-Verschlüsselung geschützt, weil der Server sie verwenden muss. Actual fragt Daten nicht automatisch ab: Die Synchronisierung wird per Schaltfläche gestartet und läuft nicht als Hintergrundaufgabe.

Backups, weil es nur Dateien sind

Alles, was Sie benötigen, befindet sich unter /opt/actual/data. Es gibt keinen Export-Schritt und keinen Datenbank-Dump, den Sie per Skript ausführen müssen.

Die einzige Falle ist SQLite. Wenn Sie account.sqlite kopieren, während der Server darin schreibt, kann die Kopie eine unvollständige Transaktion enthalten. Das stellen Sie möglicherweise erst beim Wiederherstellen fest. Stoppen Sie den Container für die wenigen Sekunden, die das Kopieren dauert:

cd /opt/actual
docker compose stop
restic -r sftp:backup@backup.example.com:/srv/restic backup /opt/actual/data
docker compose start

Planen Sie dies mit dem Ansatz aus restic-Backups auf einem VPS. Dort werden die Einrichtung des Repositorys, die Aufbewahrungsregeln und der Wiederherstellungstest beschrieben. Führen Sie den Wiederherstellungstest durch. Ein Backup, das Sie noch nie wiederhergestellt haben, ist nur eine Vermutung.

Die clientseitigen Backups von Actual sind davon getrennt und ebenfalls wichtig. Der Browser speichert aktuelle Kopien der Budgetdatei. Sie sind über das Dateimenü erreichbar. Damit können Sie den Fall „Ich habe versehentlich eine Kategorie gelöscht“ beheben, ohne den Server anzufassen.

Server aktualisieren

cd /opt/actual
docker compose pull
docker compose up --detach

Compose erstellt den Container aus dem neuen Image neu und bindet dasselbe Volume wieder ein. Die Daten bleiben dadurch erhalten. Aktualisieren Sie auch die Clients. Server- und Anwendungsversionen sollten nahe beieinanderliegen. Ein Client, der deutlich älter als der Server ist, kann die Synchronisierung mit einer Meldung über eine Versionsabweichung verweigern. Erstellen Sie vor einem Sprung auf eine neue Hauptversion ein Backup. Beim ersten Start werden Migrationen ausgeführt. Ein Downgrade ist nicht möglich.

Was fehlschlägt und was Sie sehen

Die App wird geladen, aber die Synchronisierung wird nie abgeschlossen. Prüfen Sie das nginx access log auf 413. Das bedeutet, dass client_max_body_size zu niedrig eingestellt ist. Ein 502 bedeutet dagegen, dass nginx läuft und der Container nicht.

Verschlüsselungsoptionen fehlen, oder die mobile App lehnt die URL ab. Die Seite befindet sich nicht in einem sicheren Kontext. In der Adressleiste wird http:// mit einer IP-Adresse oder einem Hostnamen angezeigt, der nicht localhost ist. Beheben Sie das Zertifikat, statt diese Einschränkung zu umgehen.

Es wird angezeigt, dass die Budgetdatei mit dieser Version nicht kompatibel ist. Die Versionen von Client und Server sind nicht mehr identisch. Aktualisieren Sie beide auf dieselbe Version und laden Sie die Seite neu.

Der Container wird in einer Schleife neu gestartet. Lesen Sie docker compose logs actual. Ein Berechtigungsfehler bei /data bedeutet, dass das eingebundene Verzeichnis für den Benutzer des Containers nicht beschreibbar ist. Ein Fehler wegen einer bereits verwendeten Adresse bedeutet, dass bereits etwas anderes 5006 auf dem Loopback-Interface verwendet.

Der erste Ladevorgang wirkt langsam. Die gesamte Budgetdatei wird beim Öffnen in den Browser heruntergeladen. Das ist eine einzelne große Übertragung, danach erfolgen lokale Lesevorgänge. Das ist kein Problem der Serverdimensionierung. Mehr RAM ändert daran nichts.

FAQ

Benötigt Actual Budget HTTPS, damit es funktioniert?

Ja, in der Praxis. Die Ende-zu-Ende-Verschlüsselung von Actual verwendet die Web Crypto API des Browsers. Browser stellen diese API nur in einem sicheren Kontext bereit, also unter https:// oder http://localhost. Über einfaches HTTP von einem anderen Rechner sind diese Funktionen nicht verfügbar. Die offiziellen mobilen Apps lehnen außerdem eine Server-URL mit einfachem HTTP ab. Verwenden Sie ein Let's-Encrypt-Zertifikat für einen echten Hostnamen. Alternativ können Sie ein selbst signiertes Zertifikat mit ACTUAL_HTTPS_KEY und ACTUAL_HTTPS_CERT verwenden, wenn Sie Actual ausschließlich in einem Desktop-Browser nutzen.

Kann Actual meine Banktransaktionen automatisch importieren?

Nur über einen Drittanbieterdienst, bei dem Sie sich selbst registrieren: SimpleFIN Bridge in Nordamerika, Enable Banking in Europa, Akahu in Neuseeland oder Pluggy.ai in Brasilien. GoCardless wird unterstützt, nimmt jedoch keine neuen Konten an. Diese API-Zugangsdaten liegen auf Ihrem Server und sind nicht durch die Ende-zu-Ende-Verschlüsselung geschützt. Die Synchronisierung erfolgt ebenfalls manuell. Sie drücken eine Schaltfläche, und im Hintergrund wird nichts regelmäßig abgefragt. Für den Import von CSV, QIF, OFX und QFX ist kein Drittanbieter erforderlich.

Was genau muss ich sichern?

Das eingebundene Datenverzeichnis, in diesem Leitfaden /opt/actual/data. Es enthält server-files/account.sqlite mit Anmeldedaten und Sitzungen sowie user-files mit den Budgetdateien. Stoppen Sie den Container vor dem Kopieren. Beim Kopieren einer aktiven SQLite-Datenbank kann ein unvollständiger Schreibvorgang erfasst werden. Auf dem Server enthält nichts anderes Zustandsdaten.

Was passiert, wenn ich das Verschlüsselungspasswort verliere?

Die Datei kann nicht wiederhergestellt werden. Das Passwort erreicht den Server niemals. Genau das ist der Zweck der Ende-zu-Ende-Verschlüsselung. Daher gibt es keine Möglichkeit zum Zurücksetzen und keinen Supportweg. Speichern Sie das Passwort sofort nach dem Erstellen der Datei in einem Passwort-Manager. Bewahren Sie außerdem eine Kopie an einem Ort auf, der nicht von diesem Server abhängt.

Wie viele Serverressourcen benötigt Actual Budget?

Sehr wenige. Der Container stellt statische Ressourcen und Dateien bereit. Die Budgetberechnungen erfolgen im Browser. Ein gemeinsam genutzter vCPU mit 1 GB RAM führt Actual problemlos aus. Das Datenverzeichnis für ein Haushaltsbudget mit mehreren Jahren Historie bleibt im Bereich von einigen Dutzend Megabyte. Die Speicherplatzbelastung entsteht durch Ihre Sicherungen und die anderen Container, nicht durch Actual.