Héberger Firefly III sur un VPS géré : vos finances sur votre serveur

Ce que fait Firefly III

Firefly III est un gestionnaire de finances personnelles conçu pour l'auto-hébergement. Il suit vos dépenses et vos revenus, avec des budgets, des catégories et des étiquettes, pour voir où va votre argent. Son README le décrit entièrement auto-hébergé et isolé : il ne contacte aucun serveur extérieur tant que vous ne le lui demandez pas.

• La tenue des comptes : une comptabilité en partie double, des comptes d'actif, des dettes et toutes les devises que vous voulez.
• L'automatisation : des opérations récurrentes, et des règles que vous écrivez pour classer chaque opération.
• Le suivi : budgets, tirelires pour épargner vers un objectif, rapports de revenus et de dépenses, graphiques.
• La sécurité : double authentification pour chaque compte.
• L'ouverture : une API REST en JSON qui couvre presque toute l'application, avec des webhooks.

Une instance accueille autant d'utilisateurs que vous voulez, chacun avec une administration financière entièrement séparée des autres. La documentation annonce un modèle de partage d'une même administration, en cours de développement.

Ce que permet la licence AGPL

Firefly III est publié sous GNU Affero General Public License, version 3 ou, à votre choix, toute version ultérieure : c'est l'identifiant SPDX AGPL-3.0-or-later de son fichier composer.json. Le texte affirme une permission illimitée de faire tourner le programme non modifié. Vous pouvez donc utiliser l'image publiée par le projet pour vous, votre famille ou votre entreprise, sans licence à acheter.

L'article 13 ajoute une condition propre à l'AGPL : si vous modifiez le programme, votre version doit offrir à tous ceux qui l'utilisent à distance, par le réseau, le moyen d'obtenir gratuitement son code source. L'importateur de données suit la même licence.

L'installation avec Docker Compose

La documentation présente Docker Compose comme la façon la plus simple d'installer Firefly III. Sur un serveur où Docker est installé, créez un dossier et téléchargez-y les trois fichiers officiels, bruts : leurs espaces comptent, et la documentation demande de ne pas les recopier depuis le navigateur.

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 décrit trois services : app, l'application, db, une base MariaDB, et cron, la tâche planifiée.
• .env porte les réglages de Firefly III, dont la clé de chiffrement et l'accès à la base.
• .db.env porte les réglages de la base de données. Gardez ces deux noms : le fichier Compose les appelle par env_file.

Les réglages à changer avant le premier démarrage

Générez deux chaînes de 32 caractères avec la commande que donne le fichier .env : une pour la clé, une pour le mot de passe de la base.

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

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

MYSQL_PASSWORD=

• APP_KEY chiffre vos sessions. Elle fait exactement 32 caractères, sans caractères spéciaux comme =, #, < ou >, et le fichier demande de la garder très secrète.
• DB_PASSWORD dans .env et MYSQL_PASSWORD dans .db.env portent la même valeur.
• SITE_OWNER : votre adresse, affichée dans certaines erreurs aux utilisateurs qui ne sont pas administrateurs.
• APP_URL : l'adresse publique de votre instance. Le fichier précise qu'elle sert à valider certaines requêtes et à construire les liens des e-mails.
• TZ : votre fuseau horaire, au format de la base tz, comme le montre l'exemple du fichier.

Choisissez le mot de passe de la base avant le premier démarrage. La base le garde dans son volume dès sa création : changé ensuite, il ne correspond plus, et la FAQ Docker ne connaît qu'une sortie, supprimer les conteneurs et les volumes pour repartir de zéro.

Un port publié en local

Le fichier officiel publie l'application sur le port 80 de toutes les adresses du serveur. Pour la servir en HTTPS derrière un mandataire inverse posé sur la même machine, changez cette seule ligne du service 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

Au premier démarrage, le conteneur crée et migre la base de lui-même. Quand l'installation est terminée, Firefly III vous remercie de l'avoir installé dans le journal : passez alors au mandataire inverse.

• L'étiquette latest suit la dernière version stable. Une étiquette comme version-6.7.9 fixe une version ; le projet retire les anciennes après six mois environ.
• Les architectures : les images sont construites pour linux/amd64 et linux/arm64.
• Les volumes : firefly_iii_upload garde les pièces jointes, firefly_iii_db la base.

La documentation ne chiffre pas la mémoire nécessaire ; sa FAQ Docker conseille PHP_MEMORY_LIMIT=512M ou plus si PHP manque de mémoire. La taille dépend du nombre d'utilisateurs, du volume d'opérations et de l'importateur. Sur un VPS géré, décrivez-nous votre usage et nous vous recommandons la taille qui convient.

HTTPS et le mandataire inverse

Firefly III sert l'application en HTTP sur le port 8080 du conteneur, et HTTPS s'installe sur le mandataire inverse placé devant. L'application lit l'en-tête X-Forwarded-Proto pour savoir que le visiteur arrive en HTTPS, à condition de faire confiance au mandataire :

TRUSTED_PROXIES=*

La FAQ Docker est claire sur ce point : sans TRUSTED_PROXIES=*, les liens restent en http, les formulaires et les graphiques cessent de fonctionner, et les en-têtes de sécurité CSP échouent. Avec le port publié sur 127.0.0.1, seul le mandataire du serveur atteint l'application. Recréez le conteneur après chaque changement du fichier .env :

docker compose up -d --force-recreate app

Avec Caddy

Caddy obtient lui-même le certificat Let's Encrypt, et sa directive reverse_proxy ajoute par défaut les en-têtes X-Forwarded-For, X-Forwarded-Proto et X-Forwarded-Host :

finances.example.com {
  reverse_proxy 127.0.0.1:8080
}

Avec Nginx et Certbot

Ce bloc reprend les en-têtes de la FAQ d'installation, et les tampons qu'elle conseille contre les erreurs 502 quand l'application renvoie un jeton dans un long en-tête. Il écoute sur le port 80 pour laisser Certbot installer HTTPS :

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 installe ensuite le certificat et se charge de le renouveler :

sudo certbot --nginx

• Un nom de domaine à lui : servez Firefly III sous son propre nom, comme finances.example.com. La FAQ précise que Laravel ne lit pas une adresse IPv6 écrite en clair dans l'URL.
• Les erreurs 431 : la FAQ les attribue à une taille d'en-tête trop petite sur le mandataire, qui fait échouer certaines actions comme la connexion.

Le premier compte et les inscriptions

Le premier utilisateur qui s'inscrit devient le propriétaire de l'instance. Par mesure de sécurité, les inscriptions se ferment ensuite d'elles-mêmes : la plupart des gens installent Firefly III pour eux seuls.

1. Ouvrez votre adresse HTTPS dès que le mandataire répond, et créez votre compte : c'est lui qui prend le rôle de propriétaire.
2. Activez la double authentification dans votre profil, et gardez les huit codes de secours qu'elle affiche.
3. Pour ouvrir l'instance à d'autres personnes, allez dans /settings, ouvrez les options de configuration de Firefly III, décochez la fermeture des inscriptions et enregistrez.

• La double authentification s'appuie sur l'heure : la FAQ indique qu'un écart d'horloge entre le téléphone et le serveur la fait échouer.
• Une connexion par votre fournisseur d'identité : avec AUTHENTICATION_GUARD=remote_user_guard, Firefly III fait confiance à un mandataire d'authentification placé devant, comme Authelia ou Authentik, qui transmet l'utilisateur dans un en-tête.
• Les jetons d'accès : les clients OAuth et les jetons personnels de l'API se créent depuis le profil.

La tâche planifiée

Plusieurs fonctions ne marchent qu'avec une tâche planifiée : les budgets automatiques, les opérations récurrentes, les alertes d'abonnements et la mise à jour des taux de change. L'image Docker ne lance pas de cron elle-même ; le fichier officiel ajoute pour cela un petit service cron, qui appelle l'application chaque jour à 3 h.

Il s'authentifie avec un jeton fixe. Générez une troisième chaîne avec la même commande, et placez-la dans .env :

STATIC_CRON_TOKEN=

Ce jeton fait exactement 32 caractères : le code de la version 6.7.9 n'accepte pas une autre longueur. Voici le service, tel que le fichier officiel le déclare ; le double $$ est voulu, il renvoie aux lignes TZ et STATIC_CRON_TOKEN du fichier .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

Une seule tâche suffit pour tous les utilisateurs de l'instance. Pour vérifier qu'elle a tourné, lisez le journal du conteneur : chaque tâche y rend un compte rendu en JSON, avec job_fired et job_succeeded.

docker logs firefly_iii_cron

Pour la lancer à la main, la FAQ Docker demande de passer par l'utilisateur www-data, et non par root : la FAQ relie à ce piège les erreurs de droits sur les fichiers de journal :

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

MariaDB, PostgreSQL ou SQLite

Le fichier officiel fournit MariaDB, avec l'image mariadb:lts. Firefly III prend aussi en charge PostgreSQL et SQLite, que l'on choisit par DB_CONNECTION dans .env :

DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432

Pour PostgreSQL, la documentation fait aussi pointer le service db vers l'image postgres, qui installe PostgreSQL 18, et monter son volume sur /var/lib/postgresql. Dans .db.env, les variables MYSQL_* deviennent POSTGRES_USER, POSTGRES_DB et POSTGRES_PASSWORD.

Faites ce choix avant de saisir vos premières opérations. La FAQ indique qu'un passage d'une base à l'autre reste possible, sans être pris en charge par Firefly III lui-même, et que l'export de l'application ne reprend pas toutes les données.

L'importateur de données

Le Firefly III Data Importer est un outil à part, avec sa propre installation et ses propres mises à jour ; sa version 2.3.5 est sortie le 23 septembre 2026. Il importe des fichiers CSV et CAMT.053, et sait aussi récupérer les opérations de vos banques par des fournisseurs de données tiers, chacun avec ses conditions.

Le dépôt Docker officiel le fournit dans un second fichier, docker-compose-importer.yml, qui reprend les mêmes services et ajoute importer. Ses réglages vont dans un fichier .importer.env, tiré du .env.example de l'importateur. Servez-le sous son propre nom de domaine, avec un port publié en local et un second bloc de mandataire : la FAQ demande de ne pas le placer dans un sous-dossier.

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

• FIREFLY_III_URL : l'adresse interne de l'application, que l'importateur joint par le réseau Docker.
• VANITY_URL : l'adresse publique de Firefly III, celle de vos utilisateurs.
• Le client OAuth : dans votre profil Firefly III, créez un client dont l'adresse de retour est celle de l'importateur suivie de /callback, et décochez « Confidential ». L'importateur vous demande ensuite son identifiant.
• Plusieurs utilisateurs : laissez FIREFLY_III_ACCESS_TOKEN vide et gardez FIREFLY_III_URL ; chaque utilisateur s'authentifie alors sur l'importateur avec son propre compte.

Les e-mails : la configuration SMTP

Par défaut, MAIL_MAILER=log écrit les messages dans les journaux au lieu de les envoyer. Pour recevoir les notifications, comme les alertes d'abonnements, réglez l'envoi dans .env. La documentation demande de toujours changer MAIL_FROM et SITE_OWNER, sans quoi aucun e-mail ne part.

Sur un VPS Simafri, l'envoi passe par un relais SMTP authentifié, sur le port 587 : l'adresse d'un compte de messagerie que vous avez déjà, ou 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=mot_de_passe_du_compte
MAIL_ENCRYPTION=tls

• MAIL_ENCRYPTION accepte null, ssl, starttls ou tls, selon votre fournisseur ; le code de la version 6.7.9 prend tls quand la valeur est vide.
• L'essai : la page /settings/notifications envoie un e-mail de test, après la recréation du conteneur.
• Les autres canaux : les notifications partent aussi vers Slack, et vers Discord ou Mattermost par leur webhook suivi de /slack.

Les sauvegardes

Firefly III n'a pas de routine de sauvegarde intégrée : la documentation conseille les outils du système, et précise que la fonction d'export de l'application n'est pas une sauvegarde. Avec Docker, voici ce qu'il faut garder :

La base, service en marche

Avec MariaDB, mariadb-dump exporte la base sans arrêter le service ; son option --single-transaction donne une copie cohérente des tables InnoDB sans les verrouiller. Lancée depuis le dossier du fichier Compose, la commande lit les accès dans l'environnement du conteneur :

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

Avec PostgreSQL, la même idée passe par pg_dump :

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

Planifiez cet export sur le serveur au moins une fois par jour, et faites le tri parmi les fichiers, qui s'accumulent.

Les volumes, service arrêté

La documentation archive chaque volume avec un conteneur jetable. Docker Compose préfixe le nom des volumes par celui du projet, le nom du dossier par défaut : relevez les noms exacts avant de lancer l'archive.

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

Un nom de volume mal écrit ne produit pas d'erreur : Docker crée un volume vide sous ce nom et l'archive, ce qui écrase la sauvegarde précédente. La documentation demande de vérifier que le volume existe avant chaque archive.

Gardez une copie de .env et de ces archives hors du serveur, chiffrée, puisqu'elle porte la clé et les accès à la base. Posés sur le disque du serveur, ces fichiers entrent aussi dans ses sauvegardes de nuit.

Restaurer

La documentation restaure un volume avec la commande inverse, service arrêté ; le volume des pièces jointes se restaure de la même façon :

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

Un export SQL se recharge dans la base en marche :

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

Restaurez aussi .env avec sa clé APP_KEY, puis relancez et ouvrez vos comptes. La documentation le répète après chaque méthode : la première chose à faire d'une sauvegarde est de la restaurer, pour vérifier qu'elle fonctionne.

Les mises à jour et les migrations

Firefly III se met à jour de lui-même, depuis des versions aussi anciennes que la 4.7, et migre sa base au démarrage du conteneur. La documentation prévient que certaines mises à jour retirent ou nettoient des données, et demande une sauvegarde de la base et des volumes avant chacune, surtout entre deux versions majeures. Depuis le dossier du fichier Compose :

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

• Le rythme : de la 6.7.0 du 14 septembre 2026 à la 6.7.9 du 11 octobre 2026, dix versions sont sorties en quatre semaines. Suivez les notes de version : depuis la 6.7.8, une fenêtre de l'application résume les changements importants de la version installée.
• La 6.7.0 a apporté une nouvelle interface ; son moteur d'expressions des règles est désactivé par défaut et se réactive dans /settings.
• Le fichier Compose : si vous le téléchargez à nouveau, vérifiez la version de la base qu'il déclare. La documentation prévient qu'une nouvelle version majeure de MariaDB peut ne pas reprendre le volume de l'ancienne.
• Une migration qui n'a pas pris : depuis la 6.4.19, php artisan correction:rollback-single-migration retire la dernière entrée de migration sans toucher aux données, puis php artisan migrate la rejoue, dans le conteneur.
• Les versions signées : le projet signe ses versions, vérifiables avec sa clé PGP.

L'importateur se met à jour de la même façon, avec docker compose rm -f entre l'arrêt et le téléchargement des images, selon sa documentation.

Qui fait quoi sur un VPS géré

L'auto-hébergement demande de tenir le serveur en plus de l'application. Sur un VPS géré, nos équipes prennent le serveur en main et suivent votre instance de manière proactive ; Firefly III reste votre logiciel, avec ses réglages et vos données financières.

Si vous préférez que nos équipes interviennent dans l'application elle-même, cette prestation se facture à l'heure ou au forfait, avec un chiffrage communiqué avant l'intervention.