Self-Hosting-Leitfaden

Dieser Leitfaden führt dich durch die Bereitstellung von Budgero auf deiner eigenen Infrastruktur. Egal ob du Docker-Container oder native Binärdateien bevorzugst – in wenigen Minuten läuft dein voll funktionsfähiger Budget-Server.

Bereitstellungsoptionen

Selbstgehostetes Budgero kann auf drei Arten bereitgestellt werden:

• Docker - Empfohlen für die meisten Nutzer. Ein einzelner Befehl, funktioniert auf jeder Plattform mit Docker.
• Native Binärdatei - Direkte Installation auf macOS, Linux oder Windows. Ideal für minimale Setups oder wenn Docker nicht verfügbar ist.
• Docker Compose - Am besten für Produktionsbereitstellungen mit persistentem Speicher und einfachen Updates.

Schnellstart mit Docker

docker run -d \  --name budgero \  -p 127.0.0.1:3001:3001 \  -v budgero_data:/data \  budgero/budgero

Prüfe beim ersten Start die Logs auf deine Admin-Zugangsdaten:

docker logs budgero

  Admin account created:
    Username: admin
    Password: <randomly-generated-password>

  ⚠️  Save this password now - it will NOT be shown again.

• App: http://localhost:3001
• Admin-Oberfläche: http://localhost:3001/admin

Verwende einen Reverse Proxy (Caddy/nginx), wenn du externen Zugriff mit HTTPS benötigst.

Der Schnellstart-Befehl bindet an 127.0.0.1, sodass er sofort einsatzbereit ist. Wenn du auf Budgero von einer anderen Origin aus zugreifst — einer LAN-IP, einem Hostnamen oder einer Domain hinter einem Reverse Proxy — musst du zusätzlich WEBSOCKET_ALLOWED_ORIGINS setzen (siehe WebSocket-Origins), sonst wird die Echtzeit-Synchronisierung keine Verbindung herstellen.

Budgero speichert alle Self-Hosting-Daten unter /data:

• Metadaten-DB: /data/budgero.db
• Verschlüsselte Budget-Blobs: /data/budget_spaces/

Docker Compose

services:  budgero:    image: budgero/budgero:latest    ports:      - "127.0.0.1:3001:3001"    # environment:    #   # Required if you access Budgero from anywhere other than localhost:    #   - WEBSOCKET_ALLOWED_ORIGINS=http://192.168.1.50:3001    volumes:      - budgero_data:/data    restart: unless-stoppedvolumes:  budgero_data:

docker compose up -ddocker compose logs budgero  # get admin credentials on first run

Mit Caddy für HTTPS

services:  budgero:    image: budgero/budgero:latest    expose:      - "3001"    environment:      - WEBSOCKET_ALLOWED_ORIGINS=https://budget.yourdomain.com    volumes:      - budgero_data:/data    restart: unless-stopped  caddy:    image: caddy:2-alpine    ports:      - "80:80"      - "443:443"    volumes:      - ./Caddyfile:/etc/caddy/Caddyfile:ro      - caddy_data:/data    restart: unless-stoppedvolumes:  budgero_data:  caddy_data:

# Caddyfile
budget.yourdomain.com {
    reverse_proxy budgero:3001
}

Installation als native Binärdatei

macOS und Linux

curl -fsSL https://budgero.app/install.sh | bash

Windows (PowerShell)

irm https://budgero.app/install.ps1 | iex

Nach der Installation startest du den Server:

budgero serve

Der Server läuft standardmäßig auf Port 3001. Deine Datenbank wird in ./data/budgero.db gespeichert.

WebSocket-Ursprünge (erforderlich für Zugriff außerhalb von localhost)

Budgero synchronisiert dein Budget in Echtzeit über einen WebSocket, und der Server akzeptiert nur WebSocket-Verbindungen von bekannten Ursprüngen. Standardmäßig sind nur localhost / 127.0.0.1-Ursprünge erlaubt. Wenn du Budgero von einer anderen Adresse öffnest — etwa einer LAN-IP wie http://192.168.1.50:3001 oder https://budget.yourdomain.com hinter einem Reverse-Proxy — wird die Sync-Verbindung abgelehnt und die App kann dein Budget nicht laden.

Setze WEBSOCKET_ALLOWED_ORIGINS auf den oder die genauen Ursprünge, die du im Browser verwendest, durch Kommas getrennt:

# Single origin (reverse proxy with HTTPS)WEBSOCKET_ALLOWED_ORIGINS=https://budget.yourdomain.com# Multiple origins (domain + direct LAN access)WEBSOCKET_ALLOWED_ORIGINS=https://budget.yourdomain.com,http://192.168.1.50:3001

Jeder Eintrag muss genau mit dem Ursprung des Browsers übereinstimmen: Schema, Host und Port (sofern nicht Standard). Wildcards werden nicht unterstützt. Falls der Eintrag fehlt oder nicht übereinstimmt, protokolliert der Server WebSocket connection rejected due to CORS mit dem erkannten Ursprung und der Liste der erlaubten Ursprünge — kopiere den abgelehnten Ursprung aus dieser Protokollzeile unverändert.

Umgebungsvariablen

Update-Prüfung

Wenn jemand die App öffnet, prüft der Server, ob eine neuere Budgero-Version existiert — höchstens alle 12 Stunden, dazwischen gecacht. Die Anfrage an budgero.app übermittelt genau drei Werte: die Version deiner Installation, deren Build-SHA und den String selfhost. Keine Instanz-ID, keine Nutzerdaten, keine Cookies. Wir fassen diese zu täglichen Versionszählern zusammen, um ungefähr zu wissen, wie viele Installationen existieren und welche Versionen genutzt werden — pro Instanz wird nichts gespeichert.

Setze UPDATE_CHECK_DISABLED=true, um die Prüfung komplett zu deaktivieren; die App tätigt dann keine unaufgeforderten ausgehenden Anfragen. Air-gapped-Installationen brauchen keine Konfiguration — eine fehlgeschlagene Prüfung wird still gecacht und die App verhält sich einfach so, als wäre sie aktuell.

Admin-Einrichtung beim ersten Start

Beim ersten Start (wenn noch keine Nutzer existieren), erstellt Budgero automatisch ein Admin-Konto mit einem zufälligen Passwort und gibt es einmalig aus:

• Docker: docker logs budgero
• Vordergrund: Gibt direkt in dein Terminal aus
• Daemon-Modus: Siehe data/logs/<name>.log

Währungsumrechnung

Die Multi-Währungsumrechnung funktioniert sofort — kein API-Schlüssel, keine Anmeldung. Die Kurse stammen aus dem offenen exchange-api-Datensatz (~350 Währungen inklusive Krypto, täglich aktualisiert) über das öffentliche jsDelivr-CDN, und dein Server cacht sie lokal, sodass wiederholte Anfragen nie deinen Rechner verlassen.

Wenn du keine Drittanbieter-Aufrufe möchtest, spiegele die statischen JSON-Dateien des Datensatzes (ein täglicher Cronjob, der currencies/*.min.json kopiert, reicht aus) und richte Budgero auf deinen Spiegel:

CURRENCY_API_BASE_URL=https://rates.example.com/{date}/v1

Der {date}-Platzhalter wird durch das Datensatzdatum (YYYY-MM-DD) ersetzt. Wer nur eine Währung nutzt, kann all das ignorieren — Budgero funktioniert auch ohne einwandfrei.

Benutzerverwaltung

Admin-Oberfläche

Greife über /admin auf das Admin-Dashboard zu, um Benutzer zu verwalten, Aktivitäten einzusehen und Einstellungen über eine Web-Oberfläche zu konfigurieren.

CLI

Alternativ kannst du Benutzer über die Kommandozeile verwalten:

# Create a userbudgero admin create-user --username johndoe --name "John" --password "secret"# List all usersbudgero admin list-users# Reset a passwordbudgero admin reset-password --username johndoe --password "new-password"# Block a userbudgero admin block-user --username johndoe

Öffentliche Registrierung deaktivieren

Nutze im Self-Hosting-Adminbereich unter /admin Registrierung → Öffentliche Registrierung erlauben. Der Schalter teilt die CLI-Einstellung und wirkt sofort. Ist DISABLE_REGISTRATION=true gesetzt, bleibt er gesperrt, bis du die Umgebungsvariable entfernst und den Server neu startest.

Schließe die öffentliche Registrierung über die Admin-CLI. Bestehende Nutzer können sich weiterhin anmelden und Admins mit budgero admin create-user Konten erstellen.

budgero admin registration disablebudgero admin registration statusbudgero admin registration enable

Änderungen wirken ohne Serverneustart. Wenn deaktiviert, blendet die Anmeldeseite Registrieren aus, Registrierungslinks führen zur Anmeldung und die Registrierungs-API lehnt neue Konten ab. Eine bereits geöffnete Seite aktualisiert sich beim erneuten Fokussieren oder Neuladen; neue Registrierungsanfragen werden sofort blockiert.

Führe den Befehl mit demselben DB_PATH und Arbeitsverzeichnis wie der Server aus. Die Einstellung wird in <database-path>.registration-disabled gespeichert; nimm diese Datei in Backups auf. Führe den Befehl bei Docker im Servercontainer aus, etwa docker compose exec budgero budgero admin registration disable.

Alternativ setzt du DISABLE_REGISTRATION=true in der Serverumgebung und startest neu. Diese Variable hat Vorrang vor der CLI-Einstellung. Entferne sie und starte neu, bevor du die Registrierung per CLI wieder öffnest.

Als Hintergrunddienst ausführen

Den integrierten Daemon verwenden (alle Plattformen)

budgero daemon start --port 3001 --name production

Laufende Daemons prüfen:

budgero daemon list

Einen Daemon stoppen:

budgero daemon stop production

systemd verwenden (Linux)

/etc/systemd/system/budgero.service erstellen:

[Unit]Description=Budgero Budget ServerAfter=network.target[Service]Type=simpleUser=budgeroWorkingDirectory=/opt/budgeroExecStart=/opt/budgero/budgero serveRestart=alwaysRestartSec=5[Install]WantedBy=multi-user.target

Aktivieren und starten:

sudo systemctl enable budgerosudo systemctl start budgero

Aktualisieren

Docker

docker pull budgero/budgero:latestdocker compose downdocker compose up -d

Native Binärdatei

budgero update

Dabei wird nach der neuesten Version gesucht und die Binärdatei automatisch ersetzt.

Reverse-Proxy-Setup

Für den Produktivbetrieb sollte Budgero für HTTPS hinter einem Reverse-Proxy wie nginx oder Caddy betrieben werden.

Denke daran, WEBSOCKET_ALLOWED_ORIGINS auf dem Budgero-Server auf die öffentliche Origin zu setzen, die der Proxy bedient (z. B. https://budget.yourdomain.com), und stelle sicher, dass der Proxy WebSocket-Upgrades weiterleitet (was bei beiden folgenden Konfigurationen der Fall ist).

Caddy (automatisches HTTPS)

budget.yourdomain.com {
    reverse_proxy localhost:3001
}

nginx

server {    listen 443 ssl http2;    server_name budget.yourdomain.com;    ssl_certificate /path/to/cert.pem;    ssl_certificate_key /path/to/key.pem;    location / {        proxy_pass http://localhost:3001;        proxy_http_version 1.1;        proxy_set_header Upgrade $http_upgrade;        proxy_set_header Connection "upgrade";        proxy_set_header Host $host;        proxy_set_header X-Real-IP $remote_addr;    }}

Fehlerbehebung

App lädt, aber das Budget erscheint nie (Synchronisierung verbindet nicht)

Wenn du dich anmelden kannst, die App aber beim Laden deines Budgets hängen bleibt — oder Geräte die Änderungen des jeweils anderen nicht mehr sehen — wird der Sync-WebSocket fast sicher abgelehnt. Prüfe die Server-Logs auf:

WebSocket connection rejected due to CORS

Die Log-Zeile enthält die Origin, die der Browser gesendet hat, und die Origins, die der Server erlaubt hat. Füge die abgelehnte Origin genau wie protokolliert zu WEBSOCKET_ALLOWED_ORIGINS hinzu (Schema, Host und Port müssen alle übereinstimmen) und starte den Server neu.

Datenbank-Sperrfehler

SQLite kommt nicht gut mit gleichzeitigen Schreibvorgängen zurecht. Wenn du Sperrfehler siehst:

1. Stelle sicher, dass nur eine Budgero-Instanz läuft
2. Prüfe, dass DB_PATH auf ein lokales Dateisystem zeigt (nicht auf eine Netzwerkfreigabe)

Port bereits belegt

Ändere den Port mit PORT=4000 oder --port 4000.

Container startet nicht

Prüfe die Logs mit docker logs budgero. Häufige Probleme:

• Volume-Berechtigungen (stelle sicher, dass der Container in /data schreiben kann)
• Port-Konflikte (ein anderer Dienst nutzt Port 3001)

FAQ

• Muss ich eine Datenbank einrichten? Nein. Budgero nutzt SQLite plus verschlüsselte Blob-Dateien. Hänge einfach /data ein und Budgero erledigt den Rest.
• Kann ich von Budgero Cloud zu Self-Hosting wechseln? Ja. Exportiere deine Daten aus Cloud und importiere sie in deine selbstgehostete Instanz.
• Gibt es eine mobile App? Greife über einen beliebigen Browser auf deine selbstgehostete Instanz zu. Füge sie deinem Startbildschirm hinzu für ein App-ähnliches Erlebnis.
• Wie sichere ich meine Daten? Sichere das gesamte /data Volume (enthält budgero.db und budget_spaces/).