Firefly III auf einem Managed VPS hosten: Ihre Finanzen auf Ihrem Server

Was Firefly III kann

Firefly III ist ein Manager für persönliche Finanzen, gemacht für das Selbsthosting. Er erfasst Ihre Ausgaben und Einnahmen, mit Budgets, Kategorien und Tags, damit Sie sehen, wohin Ihr Geld fließt. Sein README beschreibt ihn als vollständig selbst gehostet und abgeschottet: Er nimmt zu keinem externen Server Kontakt auf, solange Sie es ihm nicht ausdrücklich sagen.

• Die Buchhaltung: doppelte Buchführung, Bestandskonten, Verbindlichkeiten und jede gewünschte Währung.
• Die Automatisierung: wiederkehrende Buchungen und Regeln, die Sie schreiben, um jede Buchung einzuordnen.
• Der Überblick: Budgets, Sparschweine für ein Sparziel, Einnahmen- und Ausgabenberichte, Diagramme.
• Die Sicherheit: Zwei-Faktor-Authentifizierung für jedes Konto.
• Die Offenheit: eine REST-JSON-API, die fast die ganze Anwendung abdeckt, dazu Webhooks.

Eine Instanz nimmt so viele Nutzer auf, wie Sie möchten, jeder mit einer Finanzverwaltung, die vollständig von den anderen getrennt ist. Die Dokumentation beschreibt ein Modell, um eine einzige Verwaltung gemeinsam zu nutzen, das derzeit entwickelt wird.

Was die AGPL-Lizenz erlaubt

Firefly III wird unter der GNU Affero General Public License, Version 3 oder, nach Ihrer Wahl, jeder späteren Version, veröffentlicht: Das ist der SPDX-Bezeichner AGPL-3.0-or-later in seiner Datei composer.json. Der Text gewährt eine uneingeschränkte Erlaubnis, das unveränderte Programm auszuführen. Sie können also das vom Projekt veröffentlichte Image für sich, Ihre Familie oder Ihr Unternehmen nutzen, ohne eine Lizenz zu kaufen.

Artikel 13 fügt eine Bedingung hinzu, die der AGPL eigen ist: Wenn Sie das Programm ändern, muss Ihre Version allen, die sie aus der Ferne über das Netzwerk nutzen, die Möglichkeit bieten, ihren Quellcode kostenlos zu erhalten. Der Data Importer steht unter derselben Lizenz.

Die Installation mit Docker Compose

Die Dokumentation nennt Docker Compose den einfachsten Weg, Firefly III zu installieren. Legen Sie auf einem Server, auf dem Docker installiert ist, einen Ordner an und laden Sie die drei offiziellen Dateien im Rohformat hinein: Ihre Einrückung zählt, und die Dokumentation bittet darum, sie nicht aus dem Browser zu kopieren.

mkdir firefly-iii && cd firefly-iii
curl -o docker-compose.yml https://raw.githubusercontent.com/firefly-iii/docker/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/firefly-iii/firefly-iii/main/.env.example
curl -o .db.env https://raw.githubusercontent.com/firefly-iii/docker/main/database.env

• docker-compose.yml beschreibt drei Dienste: app, die Anwendung, db, eine MariaDB-Datenbank, und cron, die geplante Aufgabe.
• .env enthält die Einstellungen von Firefly III, darunter den Verschlüsselungsschlüssel und den Zugang zur Datenbank.
• .db.env enthält die Einstellungen der Datenbank. Behalten Sie beide Namen bei: Die Compose-Datei verweist über env_file auf sie.

Die Einstellungen, die vor dem ersten Start zu ändern sind

Erzeugen Sie mit dem Befehl aus der Datei .env zwei Zeichenketten mit 32 Zeichen: eine für den Schlüssel, eine für das Datenbankpasswort.

head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32 && echo

SITE_OWNER=you@example.com
APP_KEY=
DB_PASSWORD=
APP_URL=https://finances.example.com

MYSQL_PASSWORD=

• APP_KEY verschlüsselt Ihre Sitzungen. Er ist genau 32 Zeichen lang, ohne Sonderzeichen wie =, #, < oder >, und die Datei bittet darum, ihn sehr sicher aufzubewahren.
• DB_PASSWORD in .env und MYSQL_PASSWORD in .db.env erhalten denselben Wert.
• SITE_OWNER: Ihre Adresse, die Nutzern ohne Administratorrechte bei manchen Fehlern angezeigt wird.
• APP_URL: die öffentliche Adresse Ihrer Instanz. Die Datei erklärt, dass sie dazu dient, bestimmte Anfragen zu prüfen und die Links in den E-Mails zu bilden.
• TZ: Ihre Zeitzone, im Format der tz-Datenbank, wie das Beispiel in der Datei zeigt.

Legen Sie das Datenbankpasswort vor dem ersten Start fest. Die Datenbank speichert es in ihrem Volume, sobald sie angelegt ist: Ändern Sie es danach, passt es nicht mehr, und die Docker-FAQ nennt nur einen Ausweg, nämlich Container und Volumes zu löschen und von vorn zu beginnen.

Ein lokal veröffentlichter Port

Die offizielle Datei veröffentlicht die Anwendung auf Port 80 aller Adressen des Servers. Um sie hinter einem Reverse Proxy auf derselben Maschine über HTTPS auszuliefern, ändern Sie im Dienst app nur diese eine Zeile:

ports:
  - 127.0.0.1:8080:8080

docker compose -f docker-compose.yml up -d --pull=always
docker compose -f docker-compose.yml logs -f

Beim ersten Start legt der Container die Datenbank selbst an und migriert sie. Ist die Installation fertig, bedankt sich Firefly III im Protokoll für die Installation: Gehen Sie weiter zum Reverse Proxy.

• Das Tag latest folgt der zuletzt veröffentlichten stabilen Version. Ein Tag wie version-6.7.9 legt eine Version fest; das Projekt entfernt alte Tags nach etwa sechs Monaten.
• Die Architekturen: Die Images werden für linux/amd64 und linux/arm64 gebaut.
• Die Volumes: firefly_iii_upload enthält die Anhänge, firefly_iii_db die Datenbank.

Die Dokumentation nennt keinen Wert für den Arbeitsspeicher; ihre Docker-FAQ schlägt PHP_MEMORY_LIMIT=512M oder mehr vor, wenn PHP der Speicher ausgeht. Die Größe hängt von der Zahl der Nutzer, vom Umfang der Buchungen und vom Data Importer ab. Auf einem Managed VPS beschreiben Sie uns Ihren Einsatz, und wir empfehlen Ihnen die passende Größe.

HTTPS und der Reverse Proxy

Firefly III liefert die Anwendung im Container über HTTP auf Port 8080 aus, und HTTPS liegt beim Reverse Proxy davor. Die Anwendung liest den Header X-Forwarded-Proto, um zu wissen, dass der Besucher über HTTPS gekommen ist, sofern sie dem Proxy vertraut:

TRUSTED_PROXIES=*

Die Docker-FAQ ist in diesem Punkt eindeutig: Ohne TRUSTED_PROXIES=* bleiben die Links auf http, Formulare und Diagramme funktionieren nicht mehr, und die CSP-Sicherheitsheader schlagen fehl. Mit dem auf 127.0.0.1 veröffentlichten Port erreicht nur der Proxy des Servers selbst die Anwendung. Erstellen Sie den Container nach jeder Änderung an der Datei .env neu:

docker compose up -d --force-recreate app

Mit Caddy

Caddy bezieht das Zertifikat von Let’s Encrypt selbstständig, und seine Direktive reverse_proxy setzt standardmäßig die Header X-Forwarded-For, X-Forwarded-Proto und X-Forwarded-Host:

finances.example.com {
  reverse_proxy 127.0.0.1:8080
}

Mit Nginx und Certbot

Dieser Block übernimmt die Header aus der Installations-FAQ und die Puffer, die sie gegen 502-Fehler empfiehlt, wenn die Anwendung ein Token in einem langen Header zurückgibt. Er lauscht auf Port 80, damit Certbot HTTPS einrichten kann:

server {
    listen 80;
    listen [::]:80;
    server_name finances.example.com;

    client_max_body_size 64M;
    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 300s;
    }
}

Certbot richtet anschließend das Zertifikat ein und kümmert sich um die Erneuerung:

sudo certbot --nginx

• Ein eigener Domainname: Betreiben Sie Firefly III unter einem eigenen Namen, etwa finances.example.com. Die FAQ weist darauf hin, dass Laravel eine rohe IPv6-Adresse in der URL nicht auswertet.
• 431-Fehler: Die FAQ führt sie auf ein zu kleines Limit für die Headergröße am Proxy zurück, wodurch manche Aktionen fehlschlagen, etwa die Anmeldung.

Das erste Konto und die Registrierung

Wer sich als Erster registriert, wird Eigentümer der Instanz. Aus Sicherheitsgründen schließt sich die Registrierung danach von selbst: Die meisten installieren Firefly III nur für sich.

1. Öffnen Sie Ihre HTTPS-Adresse, sobald der Proxy antwortet, und legen Sie Ihr Konto an: Es erhält die Rolle des Eigentümers.
2. Aktivieren Sie in Ihrem Profil die Zwei-Faktor-Authentifizierung und bewahren Sie die acht Backup-Codes auf, die sie anzeigt.
3. Um die Instanz für andere Personen zu öffnen, gehen Sie auf /settings, öffnen die Konfigurationsoptionen von Firefly III, entfernen das Häkchen bei der Option, die die Registrierung deaktiviert, und speichern.

• Die Zwei-Faktor-Authentifizierung hängt von der Uhr ab: Laut FAQ lässt ein Zeitunterschied zwischen Telefon und Server sie scheitern.
• Die Anmeldung über Ihren Identitätsanbieter: Mit AUTHENTICATION_GUARD=remote_user_guard vertraut Firefly III einem vorgeschalteten Authentifizierungs-Proxy wie Authelia oder Authentik, der den Nutzer in einem Header weitergibt.
• Die Zugriffstoken: OAuth-Clients und persönliche API-Token werden im Profil angelegt.

Der Cronjob

Mehrere Funktionen arbeiten nur mit einer geplanten Aufgabe: die automatischen Budgets, die wiederkehrenden Buchungen, die Hinweise zu Abonnements und aktuelle Wechselkurse. Das Docker-Image führt cron nicht selbst aus; die offizielle Datei ergänzt dafür einen kleinen Dienst cron, der die Anwendung jeden Tag um 3 Uhr morgens aufruft.

Er authentifiziert sich mit einem statischen Token. Erzeugen Sie mit demselben Befehl eine dritte Zeichenkette und tragen Sie sie in .env ein:

STATIC_CRON_TOKEN=

Dieses Token ist genau 32 Zeichen lang: Der Code der Version 6.7.9 akzeptiert keine andere Länge. Hier der Dienst, wie ihn die offizielle Datei deklariert; das doppelte $$ ist gewollt und verweist auf die Zeilen TZ und STATIC_CRON_TOKEN der Datei .env:

cron:
  image: alpine
  restart: always
  container_name: firefly_iii_cron
  env_file: .env
  init: true
  command: ["sh", "-c", "apk add tzdata && \
    (ln -s /usr/share/zoneinfo/$$TZ /etc/localtime || true) && \
    echo \"0 3 * * * wget -qO- http://app:8080/api/v1/cron/$$STATIC_CRON_TOKEN;echo\" \
    | crontab - && \
    exec crond -f -L /dev/stdout"]
  networks:
    - firefly_iii
  depends_on:
    - app

Eine Aufgabe genügt für alle Nutzer der Instanz. Um zu prüfen, ob sie gelaufen ist, lesen Sie das Protokoll des Containers: Jede Aufgabe meldet sich in JSON zurück, mit job_fired und job_succeeded.

docker logs firefly_iii_cron

Um sie von Hand zu starten, bittet die Docker-FAQ darum, den Benutzer www-data statt root zu verwenden: Die FAQ bringt diese Falle mit Berechtigungsfehlern bei den Protokolldateien in Verbindung:

docker exec --user www-data firefly_iii_core /usr/local/bin/php /var/www/html/artisan firefly-iii:cron --force

MariaDB, PostgreSQL oder SQLite

Die offizielle Datei liefert MariaDB mit, mit dem Image mariadb:lts. Firefly III unterstützt auch PostgreSQL und SQLite, ausgewählt mit DB_CONNECTION in .env:

DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432

Für PostgreSQL lässt die Dokumentation den Dienst db außerdem auf das Image postgres zeigen, das PostgreSQL 18 installiert, und bindet sein Volume auf /var/lib/postgresql ein. In .db.env werden die Variablen MYSQL_* zu POSTGRES_USER, POSTGRES_DB und POSTGRES_PASSWORD.

Treffen Sie diese Wahl, bevor Sie Ihre ersten Buchungen erfassen. Laut FAQ bleibt ein Wechsel von einer Datenbank zur anderen möglich, ohne dass Firefly III ihn selbst unterstützt, und der Export der Anwendung nimmt nicht alle Daten mit.

Der Data Importer

Der Firefly III Data Importer ist ein eigenständiges Werkzeug, mit eigener Installation und eigenen Updates; seine Version 2.3.5 ist am 23. September 2026 erschienen. Er importiert CSV- und CAMT.053-Dateien und kann Buchungen auch über externe Datenanbieter bei Ihren Banken abrufen, jeder mit seinen eigenen Bedingungen.

Das offizielle Docker-Repository liefert ihn in einer zweiten Datei, docker-compose-importer.yml, die dieselben Dienste behält und importer ergänzt. Seine Einstellungen kommen in eine Datei .importer.env, die aus der .env.example des Importers hervorgeht. Betreiben Sie ihn unter einem eigenen Domainnamen, mit einem lokal veröffentlichten Port und einem zweiten Proxy-Block: Die FAQ bittet darum, ihn nicht in einem Unterverzeichnis abzulegen.

FIREFLY_III_URL=http://app:8080
VANITY_URL=https://finances.example.com
TRUSTED_PROXIES=*

• FIREFLY_III_URL: die interne Adresse der Anwendung, die der Importer über das Docker-Netzwerk erreicht.
• VANITY_URL: die öffentliche Adresse von Firefly III, die Ihre Nutzer kennen.
• Der OAuth-Client: Legen Sie in Ihrem Firefly-III-Profil einen Client an, dessen Callback-URL die Adresse des Importers gefolgt von /callback ist, und entfernen Sie das Häkchen bei „Confidential“. Der Importer fragt dann nach seiner Client-ID.
• Mehrere Nutzer: Lassen Sie FIREFLY_III_ACCESS_TOKEN leer und behalten Sie FIREFLY_III_URL; jeder Nutzer meldet sich dann mit seinem eigenen Konto am Importer an.

Die E-Mails: die SMTP-Konfiguration

Standardmäßig schreibt MAIL_MAILER=log die Nachrichten in die Protokolle, statt sie zu versenden. Um Benachrichtigungen zu erhalten, etwa die Hinweise zu Abonnements, richten Sie den Versand in .env ein. Die Dokumentation bittet darum, MAIL_FROM und SITE_OWNER immer zu ändern, sonst geht keine E-Mail hinaus.

Auf einem Simafri-VPS läuft der Versand über ein authentifiziertes SMTP-Relay auf Port 587: die Adresse eines Postfachs, das Sie bereits haben, oder Simafri Suite.

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_FROM=finances@example.com
MAIL_USERNAME=finances@example.com
MAIL_PASSWORD=account_password
MAIL_ENCRYPTION=tls

• MAIL_ENCRYPTION akzeptiert je nach Anbieter null, ssl, starttls oder tls; der Code der Version 6.7.9 greift auf tls zurück, wenn der Wert leer ist.
• Der Test: Die Seite /settings/notifications sendet eine Test-E-Mail, sobald der Container neu erstellt ist.
• Weitere Kanäle: Benachrichtigungen können auch an Slack gehen, und an Discord oder Mattermost über deren Webhook-URL gefolgt von /slack.

Die Backups

Firefly III hat keine eingebaute Backup-Routine: Die Dokumentation empfiehlt die Werkzeuge des Systems und weist darauf hin, dass die Exportfunktion der Anwendung kein Backup ist. Mit Docker ist das zu sichern:

Die Datenbank, bei laufendem Dienst

Mit MariaDB exportiert mariadb-dump die Datenbank, ohne den Dienst anzuhalten; seine Option --single-transaction liefert eine konsistente Kopie der InnoDB-Tabellen, ohne sie zu sperren. Im Ordner der Compose-Datei ausgeführt, liest der Befehl die Zugangsdaten aus der Umgebung des Containers:

docker exec firefly_iii_db sh -c 'mariadb-dump --single-transaction -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' > firefly-$(date +%F).sql

Mit PostgreSQL läuft dasselbe über pg_dump:

docker exec firefly_iii_db sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' > firefly-$(date +%F).sql

Planen Sie diesen Export auf dem Server mindestens einmal täglich und räumen Sie die Dateien auf, die sich ansammeln.

Die Volumes, bei gestopptem Dienst

Die Dokumentation archiviert jedes Volume mit einem Wegwerf-Container. Docker Compose stellt den Volume-Namen den Projektnamen voran, standardmäßig den Namen des Ordners: Prüfen Sie die genauen Namen, bevor Sie das Archiv anlegen.

docker volume ls
docker compose stop
docker run --rm -v "firefly-iii_firefly_iii_db:/tmp" -v "$HOME/backups/firefly:/backup" \
    ubuntu tar -czvf /backup/firefly_db.tar /tmp
docker run --rm -v "firefly-iii_firefly_iii_upload:/tmp" -v "$HOME/backups/firefly:/backup" \
    ubuntu tar -czvf /backup/firefly_upload.tar /tmp
docker compose start

Ein falsch geschriebener Volume-Name löst keinen Fehler aus: Docker legt unter diesem Namen ein leeres Volume an und archiviert es, was das vorherige Backup überschreibt. Die Dokumentation bittet darum, vor jedem Archiv zu prüfen, dass das Volume existiert.

Bewahren Sie eine Kopie von .env und dieser Archive außerhalb des Servers auf, verschlüsselt, denn sie enthält den Schlüssel und die Zugangsdaten der Datenbank. Auf der Festplatte des Servers abgelegt, fließen diese Dateien auch in dessen nächtliche Backups ein.

Wiederherstellen

Die Dokumentation stellt ein Volume mit dem umgekehrten Befehl wieder her, bei gestopptem Dienst; das Volume der Anhänge wird auf dieselbe Weise wiederhergestellt:

docker run --rm -v "firefly-iii_firefly_iii_db:/recover" -v "$HOME/backups/firefly:/backup" \
    ubuntu tar -xvf /backup/firefly_db.tar -C /recover --strip 1

Ein SQL-Export wird in die laufende Datenbank zurückgespielt:

docker exec -i firefly_iii_db sh -c 'mariadb -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < firefly-YYYY-MM-DD.sql

Stellen Sie auch .env mit seinem APP_KEY wieder her, starten Sie dann neu und öffnen Sie Ihre Konten. Die Dokumentation wiederholt es nach jeder Methode: Das Erste, was man mit einem Backup tut, ist, es wiederherzustellen, um zu prüfen, dass es funktioniert.

Die Updates und Migrationen

Firefly III aktualisiert sich selbst, sogar von Versionen bis zurück zu 4.7, und migriert seine Datenbank beim Start des Containers. Die Dokumentation warnt, dass manche Updates Daten entfernen oder bereinigen, und verlangt vor jedem ein Backup der Datenbank und der Volumes, vor allem zwischen Hauptversionen. Im Ordner der Compose-Datei:

docker compose stop
docker compose pull
docker compose -f docker-compose.yml up -d --remove-orphans

• Das Tempo: Von 6.7.0 am 14. September 2026 bis 6.7.9 am 11. Oktober 2026 sind in vier Wochen zehn Versionen erschienen. Verfolgen Sie die Release Notes: Seit 6.7.8 fasst ein Fenster in der Anwendung die wichtigsten Änderungen der installierten Version zusammen.
• Die Version 6.7.0 brachte eine neue Oberfläche; ihre Engine für Regelausdrücke ist standardmäßig ausgeschaltet und wird in /settings wieder eingeschaltet.
• Die Compose-Datei: Wenn Sie sie erneut herunterladen, prüfen Sie die Datenbankversion, die sie deklariert. Die Dokumentation warnt, dass eine neue Hauptversion von MariaDB das Volume der alten möglicherweise nicht übernimmt.
• Eine Migration, die nicht gegriffen hat: Seit 6.4.19 entfernt php artisan correction:rollback-single-migration den letzten Migrationseintrag, ohne die Daten anzurühren, und php artisan migrate führt sie dann im Container erneut aus.
• Signierte Versionen: Das Projekt signiert seine Versionen, was Sie mit seinem PGP-Schlüssel prüfen können.

Der Importer wird laut seiner Dokumentation auf dieselbe Weise aktualisiert, mit docker compose rm -f zwischen dem Stoppen und dem Herunterladen der Images.

Wer was tut auf einem Managed VPS

Beim Selbsthosting müssen Sie neben der Anwendung auch den Server betreuen. Auf einem Managed VPS übernehmen unsere Teams den Server und betreuen Ihre Instanz proaktiv; Firefly III bleibt Ihre Software, mit ihren Einstellungen und Ihren Finanzdaten.

Wenn unsere Teams lieber in der Anwendung selbst eingreifen sollen, wird diese Leistung nach Stunden oder pauschal abgerechnet, mit einem Kostenvoranschlag vor dem Eingriff.