Firefly III hosten op een Managed VPS: uw financiën op uw eigen server

Wat Firefly III doet

Firefly III is een beheerder voor persoonlijke financiën, gebouwd voor self-hosting. Het houdt uw uitgaven en inkomsten bij, met budgetten, categorieën en tags, zodat u ziet waar uw geld naartoe gaat. De README beschrijft het als volledig zelf gehost en afgeschermd: het neemt geen contact op met een externe server tot u het daar uitdrukkelijk om vraagt.

• De boekhouding: dubbel boekhouden, activarekeningen, schulden en elke valuta die u wilt.
• De automatisering: terugkerende transacties, en regels die u schrijft om elke transactie in te delen.
• De opvolging: budgetten, spaarpotjes om voor een doel te sparen, rapporten over inkomsten en uitgaven, grafieken.
• De beveiliging: tweestapsverificatie voor elk account.
• De openheid: een REST JSON API die vrijwel de hele applicatie dekt, plus webhooks.

Eén instantie biedt plaats aan zoveel gebruikers als u wilt, elk met een financiële administratie die volledig van de andere gescheiden is. De documentatie beschrijft een model om één administratie te delen, dat momenteel in ontwikkeling is.

Wat de AGPL-licentie toestaat

Firefly III wordt gepubliceerd onder de GNU Affero General Public License, versie 3 of, naar uw keuze, elke latere versie: dat is de SPDX-identificatie AGPL-3.0-or-later in zijn bestand composer.json. De tekst kent een onbeperkte toestemming toe om het ongewijzigde programma te draaien. U kunt de image die het project publiceert dus gebruiken voor uzelf, uw gezin of uw bedrijf, zonder een licentie te kopen.

Artikel 13 voegt een voorwaarde toe die eigen is aan de AGPL: als u het programma wijzigt, moet uw versie iedereen die het op afstand, via het netwerk, gebruikt de mogelijkheid bieden de broncode gratis te verkrijgen. De Data Importer valt onder dezelfde licentie.

De installatie met Docker Compose

De documentatie noemt Docker Compose de eenvoudigste manier om Firefly III te installeren. Maak op een server waar Docker is geïnstalleerd een map aan en download daarin de drie officiële bestanden, in ruwe vorm: hun witruimte telt, en de documentatie vraagt ze niet vanuit de browser te kopiëren.

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 beschrijft drie diensten: app, de applicatie, db, een MariaDB-database, en cron, de geplande taak.
• .env bevat de instellingen van Firefly III, waaronder de versleutelingssleutel en de toegang tot de database.
• .db.env bevat de instellingen van de database. Behoud beide namen: het Compose-bestand verwijst ernaar via env_file.

De instellingen die u vóór de eerste start wijzigt

Genereer twee tekenreeksen van 32 tekens met de opdracht uit het bestand .env: één voor de sleutel, één voor het databasewachtwoord.

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 versleutelt uw sessies. Ze telt precies 32 tekens, zonder speciale tekens zoals =, #, < of >, en het bestand vraagt haar zeer goed te beveiligen.
• DB_PASSWORD in .env en MYSQL_PASSWORD in .db.env krijgen dezelfde waarde.
• SITE_OWNER: uw adres, dat in bepaalde foutmeldingen wordt getoond aan gebruikers die geen beheerder zijn.
• APP_URL: het openbare adres van uw instantie. Het bestand legt uit dat het dient om bepaalde verzoeken te valideren en om de links in e-mails op te bouwen.
• TZ: uw tijdzone, in de notatie van de tz-database, zoals het voorbeeld in het bestand laat zien.

Kies het databasewachtwoord vóór de eerste start. De database slaat het op in haar volume zodra ze wordt aangemaakt: wijzigt u het daarna, dan klopt het niet meer, en de Docker-FAQ biedt maar één uitweg, namelijk de containers en volumes verwijderen en opnieuw beginnen.

Een lokaal gepubliceerde poort

Het officiële bestand publiceert de applicatie op poort 80 van elk adres van de server. Om haar via HTTPS aan te bieden achter een reverse proxy op dezelfde machine, wijzigt u deze ene regel in de dienst app:

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

Bij de eerste start maakt de container de database zelf aan en migreert hij haar. Is de installatie klaar, dan bedankt Firefly III u in het logboek voor de installatie: ga dan verder met de reverse proxy.

• De tag latest volgt de laatste stabiele versie. Een tag zoals version-6.7.9 legt een versie vast; het project verwijdert oude tags na ongeveer zes maanden.
• De architecturen: de images worden gebouwd voor linux/amd64 en linux/arm64.
• De volumes: firefly_iii_upload bewaart de bijlagen, firefly_iii_db de database.

De documentatie noemt geen cijfer voor het geheugen; de Docker-FAQ stelt PHP_MEMORY_LIMIT=512M of meer voor als PHP te weinig geheugen heeft. De grootte hangt af van het aantal gebruikers, het volume aan transacties en de data importer. Beschrijf op een managed VPS uw gebruik aan ons, dan raden wij u de passende grootte aan.

HTTPS en de reverse proxy

Firefly III biedt de applicatie aan via HTTP op poort 8080 binnen de container, en HTTPS zit op de reverse proxy die ervoor staat. De applicatie leest de header X-Forwarded-Proto om te weten dat de bezoeker via HTTPS binnenkwam, op voorwaarde dat ze de proxy vertrouwt:

TRUSTED_PROXIES=*

De Docker-FAQ is daar duidelijk over: zonder TRUSTED_PROXIES=* blijven de links op http, werken formulieren en grafieken niet meer en falen de CSP-beveiligingsheaders. Met de poort gepubliceerd op 127.0.0.1 bereikt alleen de proxy van de server zelf de applicatie. Maak de container opnieuw aan na elke wijziging van het bestand .env:

docker compose up -d --force-recreate app

Met Caddy

Caddy verkrijgt zelf het Let's Encrypt-certificaat, en zijn directive reverse_proxy zet standaard de headers X-Forwarded-For, X-Forwarded-Proto en X-Forwarded-Host:

finances.example.com {
  reverse_proxy 127.0.0.1:8080
}

Met Nginx en Certbot

Dit blok volgt de headers uit de installatie-FAQ, en de buffers die ze voorstelt tegen 502-fouten wanneer de applicatie een token in een lange header teruggeeft. Het luistert op poort 80, zodat Certbot HTTPS kan plaatsen:

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 plaatst daarna het certificaat en zorgt voor de vernieuwing ervan:

sudo certbot --nginx

• Een eigen domeinnaam: bied Firefly III aan onder een eigen naam, zoals finances.example.com. De FAQ wijst erop dat Laravel een kaal IPv6-adres in de URL niet kan verwerken.
• 431-fouten: de FAQ voert ze terug op een te lage limiet voor de headergrootte op de proxy, waardoor bepaalde handelingen mislukken, zoals het aanmelden.

Het eerste account en de registraties

De eerste gebruiker die zich registreert, wordt de eigenaar van de instantie. Uit veiligheidsoverwegingen sluiten de registraties daarna vanzelf: de meeste mensen installeren Firefly III alleen voor zichzelf.

1. Open uw HTTPS-adres zodra de proxy antwoordt, en maak uw account aan: het krijgt de rol van eigenaar.
2. Schakel de tweestapsverificatie in via uw profiel, en bewaar de acht herstelcodes die het toont.
3. Wilt u de instantie voor anderen openstellen, ga dan naar /settings, open de configuratieopties van Firefly III, vink de optie uit die de registraties uitschakelt en sla op.

• De tweestapsverificatie steunt op de klok: de FAQ zegt dat een tijdsverschil tussen de telefoon en de server haar laat mislukken.
• Aanmelden via uw identiteitsprovider: met AUTHENTICATION_GUARD=remote_user_guard vertrouwt Firefly III een authenticatieproxy die ervoor staat, zoals Authelia of Authentik, en die de gebruiker in een header doorgeeft.
• De toegangstokens: OAuth-clients en persoonlijke API-tokens worden vanuit het profiel aangemaakt.

De cronjob

Verschillende functies werken alleen met een geplande taak: de automatische budgetten, de terugkerende transacties, de waarschuwingen voor abonnementen en de actuele wisselkoersen. De Docker-image draait zelf geen cron; het officiële bestand voegt daarvoor een kleine dienst cron toe, die de applicatie elke dag om 3 uur 's nachts aanroept.

Die authenticeert zich met een statisch token. Genereer met dezelfde opdracht een derde tekenreeks, en plaats die in .env:

STATIC_CRON_TOKEN=

Dit token telt precies 32 tekens: de code van versie 6.7.9 aanvaardt geen andere lengte. Hier is de dienst zoals het officiële bestand hem declareert; de dubbele $$ is gewild en verwijst naar de regels TZ en STATIC_CRON_TOKEN van het bestand .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

Eén taak volstaat voor alle gebruikers van de instantie. Wilt u controleren of ze is uitgevoerd, lees dan het logboek van de container: elke taak rapporteert in JSON, met job_fired en job_succeeded.

docker logs firefly_iii_cron

Om haar met de hand te starten, vraagt de Docker-FAQ de gebruiker www-data te gebruiken in plaats van root: de FAQ koppelt deze valkuil aan rechtenfouten op de logbestanden:

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

MariaDB, PostgreSQL of SQLite

Het officiële bestand levert MariaDB mee, met de image mariadb:lts. Firefly III ondersteunt ook PostgreSQL en SQLite, te kiezen met DB_CONNECTION in .env:

DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432

Voor PostgreSQL laat de documentatie de dienst db ook naar de image postgres wijzen, die PostgreSQL 18 installeert, en koppelt ze zijn volume op /var/lib/postgresql. In .db.env worden de variabelen MYSQL_* dan POSTGRES_USER, POSTGRES_DB en POSTGRES_PASSWORD.

Maak deze keuze voordat u uw eerste transacties invoert. De FAQ zegt dat overstappen van de ene database naar de andere mogelijk blijft, zonder dat Firefly III dat zelf ondersteunt, en dat de export van de applicatie niet alle gegevens meeneemt.

De Data Importer

De Firefly III Data Importer is een apart hulpmiddel, met een eigen installatie en eigen updates; versie 2.3.5 verscheen op 23 september 2026. Het importeert CSV- en CAMT.053-bestanden, en kan ook transacties bij uw banken ophalen via externe gegevensleveranciers, elk met hun eigen voorwaarden.

De officiële Docker-repository levert hem in een tweede bestand, docker-compose-importer.yml, dat dezelfde diensten behoudt en importer toevoegt. Zijn instellingen komen in een bestand .importer.env, overgenomen uit de .env.example van de importer. Bied hem aan onder een eigen domeinnaam, met een lokaal gepubliceerde poort en een tweede proxyblok: de FAQ vraagt hem niet in een submap te plaatsen.

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

• FIREFLY_III_URL: het interne adres van de applicatie, dat de importer via het Docker-netwerk bereikt.
• VANITY_URL: het openbare adres van Firefly III, dat uw gebruikers kennen.
• De OAuth-client: maak in uw profiel van Firefly III een client aan waarvan de callback-URL het adres van de importer is, gevolgd door /callback, en vink “Confidential” uit. De importer vraagt daarna het ID van die client.
• Meerdere gebruikers: laat FIREFLY_III_ACCESS_TOKEN leeg en behoud FIREFLY_III_URL; elke gebruiker meldt zich dan met zijn eigen account aan bij de importer.

E-mails: de SMTP-configuratie

Standaard schrijft MAIL_MAILER=log de berichten naar de logboeken in plaats van ze te versturen. Om meldingen te ontvangen, zoals de waarschuwingen voor abonnementen, stelt u het verzenden in .env in. De documentatie vraagt MAIL_FROM en SITE_OWNER altijd te wijzigen, anders gaat er nooit een e-mail de deur uit.

Op een Simafri-VPS loopt het verzenden via een geauthenticeerde SMTP-relay, op poort 587: het adres van een e-mailaccount dat u al hebt, of 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 aanvaardt null, ssl, starttls of tls, naargelang uw provider; de code van versie 6.7.9 valt terug op tls wanneer de waarde leeg is.
• De test: de pagina /settings/notifications verstuurt een test-e-mail, zodra de container opnieuw is aangemaakt.
• Andere kanalen: de meldingen kunnen ook naar Slack gaan, en naar Discord of Mattermost via hun webhook-URL gevolgd door /slack.

De back-ups

Firefly III heeft geen ingebouwde back-uproutine: de documentatie beveelt de eigen hulpmiddelen van het systeem aan, en wijst erop dat de exportfunctie van de applicatie geen back-up is. Met Docker bewaart u het volgende:

De database, terwijl de dienst draait

Met MariaDB exporteert mariadb-dump de database zonder de dienst te stoppen; de optie --single-transaction geeft een consistente kopie van de InnoDB-tabellen zonder ze te vergrendelen. Uitgevoerd vanuit de map van het Compose-bestand, leest de opdracht de toegangsgegevens uit de omgeving van de container:

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

Met PostgreSQL loopt hetzelfde principe via pg_dump:

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

Plan deze export op de server minstens één keer per dag in, en ruim de bestanden, die zich opstapelen, regelmatig op.

De volumes, met de dienst gestopt

De documentatie archiveert elk volume met een wegwerpcontainer. Docker Compose zet de projectnaam voor de namen van de volumes, en standaard is dat de naam van de map: controleer de exacte namen voordat u het archief start.

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

Een verkeerd gespelde volumenaam geeft geen foutmelding: Docker maakt onder die naam een leeg volume aan en archiveert het, wat de vorige back-up overschrijft. De documentatie vraagt vóór elk archief te controleren of het volume bestaat.

Bewaar een kopie van .env en van deze archieven buiten de server, versleuteld, want ze bevat de sleutel en de toegangsgegevens van de database. Staan deze bestanden op de schijf van de server, dan vallen ze ook onder de nachtelijke back-ups.

Terugzetten

De documentatie zet een volume terug met de omgekeerde opdracht, met de dienst gestopt; het volume met de bijlagen zet u op dezelfde manier terug:

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

Een SQL-export laadt u terug in de draaiende database:

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

Zet ook .env met zijn APP_KEY terug, start daarna opnieuw en open uw rekeningen. De documentatie herhaalt het na elke methode: het eerste wat u met een back-up doet, is haar terugzetten, om te controleren of ze werkt.

Updates en migraties

Firefly III werkt zichzelf bij, zelfs vanaf versies zo oud als 4.7, en migreert zijn database wanneer de container start. De documentatie waarschuwt dat sommige updates gegevens verwijderen of opschonen, en vraagt vóór elke update een back-up van de database en de volumes, zeker bij een overstap tussen hoofdversies. Vanuit de map van het Compose-bestand:

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

• Het tempo: van 6.7.0 op 14 september 2026 tot 6.7.9 op 11 oktober 2026 verschenen tien versies in vier weken. Volg de release-opmerkingen: sinds 6.7.8 vat een venster in de applicatie de belangrijkste wijzigingen van de geïnstalleerde versie samen.
• Versie 6.7.0 bracht een nieuwe interface; haar engine voor regelexpressies staat standaard uit en wordt weer ingeschakeld in /settings.
• Het Compose-bestand: downloadt u het opnieuw, controleer dan de databaseversie die het declareert. De documentatie waarschuwt dat een nieuwe hoofdversie van MariaDB het volume van de oude mogelijk niet overneemt.
• Een migratie die niet is gelukt: sinds 6.4.19 verwijdert php artisan correction:rollback-single-migration de laatste migratie-invoer zonder de gegevens aan te raken, waarna php artisan migrate haar opnieuw uitvoert, binnen de container.
• Ondertekende releases: het project ondertekent zijn releases, wat u met zijn PGP-sleutel kunt controleren.

De importer wordt op dezelfde manier bijgewerkt, met docker compose rm -f tussen het stoppen en het ophalen van de images, volgens zijn documentatie.

Wie doet wat op een managed VPS

Self-hosting vraagt dat u naast de applicatie ook de server beheert. Op een managed VPS neemt ons team de server voor zijn rekening en houdt het uw instantie proactief in de gaten; Firefly III blijft uw software, met zijn instellingen en uw financiële gegevens.

Wilt u liever dat ons team in de applicatie zelf ingrijpt, dan wordt die dienstverlening per uur of tegen een vast bedrag gefactureerd, met een offerte voordat het werk begint.