Héberger Firefly III sur un VPS : finances pro sous contrôle

Pourquoi Firefly III plutôt qu'un outil SaaS ?

Les gestionnaires de finances en ligne (YNAB, Mint, Freeform…) imposent un abonnement mensuel, hébergent vos données sur leurs serveurs américains et peuvent fermer leur service sans préavis. Pour un indépendant ou une petite structure, les implications RGPD de partager ses relevés bancaires avec un tiers sont rarement évaluées.

Firefly III règle ces trois problèmes à la fois : licence AGPL-3.0 (code ouvert, modifiable), docker-compose en moins de dix commandes, données dans votre propre base PostgreSQL. Avec 24 300 étoiles sur GitHub et une v6.6.6 sortie en juillet 2025, c'est un projet mature, activement maintenu et documenté.

Ce que Firefly III gère pour vous : comptes courants et d'épargne, cartes de crédit, portefeuilles de cryptomonnaies, budgets mensuels ou annuels, règles d'automatisation des transactions, catégories personnalisées, rapports par période ou catégorie, et import depuis vos relevés bancaires via le Data Importer.

Fonctionnalités clés

Multi-comptes : gérez simultanément plusieurs comptes courants, d'épargne, cartes de crédit et portefeuilles crypto.
Budgets et enveloppes : définissez des budgets mensuels par catégorie (loyer, fournitures, honoraires…) et suivez leur consommation en temps réel.
Règles d'automatisation : créez des règles qui s'appliquent automatiquement aux nouvelles transactions (ex. : dépenses Uber → catégorie Transports).
Rapports avancés : graphiques par période, par compte, par catégorie, exportables en CSV pour votre comptable.
Data Importer : importez vos relevés bancaires au format OFX, QFX, CSV ou via des connecteurs bancaires européens (Nordigen/GoCardless).
API REST complète : automatisez la création de transactions depuis n'importe quel script ou outil tiers.
Interface mobile responsive : accédez à vos comptes depuis votre téléphone via le navigateur.

Prérequis serveur

Firefly III est une application PHP/Laravel légère. Voici ce dont vous avez besoin :

- Un VPS sous Ubuntu 22.04 ou Debian 12 avec au moins 1 Go de RAM (2 Go recommandés).
- Docker Engine ≥ 24 et Docker Compose V2 installés.
- Un nom de domaine pointant vers votre VPS (recommandé pour configurer TLS).
- Un port 8080 accessible (UI Firefly III) et 8081 (Data Importer, optionnel).
- 5 Go de stockage minimum pour la base de données et les pièces jointes.

Firefly III ne nécessite pas de GPU ni de RAM excessive — c'est l'un de ses avantages par rapport à des outils comme ERPNext.

Installation avec Docker Compose

Étape 1 — Cloner le dépôt officiel

Firefly III fournit un fichier docker-compose.yml officiel et un template .env dans son dépôt firefly-iii/docker :

mkdir -p /opt/firefly && cd /opt/firefly
curl -L https://raw.githubusercontent.com/firefly-iii/docker/main/docker-compose-importer.yml \
  -o docker-compose.yml
curl -L https://raw.githubusercontent.com/firefly-iii/firefly-iii/main/.env.example \
  -o .env
curl -L https://raw.githubusercontent.com/firefly-iii/data-importer/main/.env.example \
  -o .importer.env

Étape 2 — Configurer les variables d'environnement

Ouvrez .env et modifiez ces variables :

# Base de données
DB_HOST=db
DB_PORT=5432
DB_DATABASE=firefly
DB_USERNAME=firefly
DB_PASSWORD=MOT_DE_PASSE_FORT_ICI

# Clé d'application — OBLIGATOIRE, 32 caractères exactement
APP_KEY=SomeLongRandomStringOf32CharsMin

# URL de votre instance
APP_URL=https://firefly.votredomaine.com

# Mot de passe administrateur PostgreSQL
POSTGRES_PASSWORD=MOT_DE_PASSE_POSTGRES

⚠️ La variable APP_KEY doit contenir exactement 32 caractères alphanumériques. Générez-en une avec openssl rand -hex 16.

Étape 3 — Lancer les conteneurs

docker compose up -d

Le démarrage complet prend 30 à 60 secondes. Vérifiez l'état des conteneurs :

docker compose ps

Vous devez voir trois conteneurs en état healthy (ou running) : firefly-iii, db (PostgreSQL) et importer. Firefly III attend que PostgreSQL soit prêt grâce à la directive depends_on: condition: service_healthy dans le docker-compose.yml — vous n'avez rien à gérer manuellement.

Étape 4 — Accéder à l'interface

Ouvrez votre navigateur sur http://<IP_VPS>:8080. Firefly III vous invite à créer votre compte administrateur. Renseignez votre adresse e-mail et un mot de passe. Une fois connecté, l'assistant de configuration vous guide pour créer votre premier compte bancaire.

Étape 5 — Configurer Nginx avec TLS

Ne laissez pas Firefly III accessible sans HTTPS en production. Configurez Nginx comme reverse proxy :

apt install -y nginx certbot python3-certbot-nginx

cat > /etc/nginx/sites-available/firefly << 'EOF'
server {
    server_name firefly.votredomaine.com;
    location / {
        proxy_pass http://127.0.0.1:8080;
        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;
    }
}
EOF

ln -s /etc/nginx/sites-available/firefly /etc/nginx/sites-enabled/
certbot --nginx -d firefly.votredomaine.com
nginx -t && systemctl reload nginx

Fermez ensuite le port 8080 dans votre pare-feu (ufw deny 8080).

Étape 6 — Importer vos relevés bancaires

Le Data Importer écoute sur le port 8081. Accédez à http://<IP_VPS>:8081 pour lancer l'import.

1. Cliquez sur Import puis Upload a file.
2. Sélectionnez votre fichier OFX, QFX ou CSV exporté depuis votre banque.
3. L'assistant vous guide pour mapper les colonnes (date, montant, description, compte).
4. Validez l'import : les transactions apparaissent immédiatement dans Firefly III.

Pour automatiser les imports, configurez un connecteur GoCardless (anciennement Nordigen) depuis l'interface du Data Importer pour synchroniser automatiquement vos comptes bancaires européens.

Configurer les budgets et les règles d'automatisation

Créer un budget mensuel :
1. Allez dans Budgets → New budget.
2. Nommez le budget (ex. « Fournitures bureau ») et définissez le montant mensuel.
3. Associez les transactions à ce budget manuellement ou via une règle.

Créer une règle d'automatisation :
1. Allez dans Automation → Rules → New rule.
2. Définissez le déclencheur : par exemple « La description contient 'Amazon' ».
3. Définissez l'action : « Assigner à la catégorie Fournitures » et « Assigner au budget Fournitures bureau ».
4. La règle s'applique automatiquement aux nouvelles transactions et peut être rejouée sur l'historique.

Exporter pour votre comptable :
Allez dans Export data et choisissez le format CSV. Filtrez par période (ex. T1 2026) et par compte. Le fichier export contient toutes les transactions avec date, montant, description, catégorie et budget.

Planifier des sauvegardes automatiques

Firefly III stocke ses données dans PostgreSQL. Voici comment planifier une sauvegarde quotidienne :

mkdir -p /opt/firefly/backups

cat > /opt/firefly/backup.sh << 'EOF'
#!/bin/bash
DATE=$(date +%Y%m%d)
docker compose -f /opt/firefly/docker-compose.yml exec -T db \
  pg_dump -U firefly firefly | gzip > /opt/firefly/backups/firefly-$DATE.sql.gz
find /opt/firefly/backups -name '*.sql.gz' -mtime +30 -delete
EOF
chmod +x /opt/firefly/backup.sh

# Cron quotidien à 03:00
echo '0 3 * * * root /opt/firefly/backup.sh' >> /etc/cron.d/firefly-backup

Pour une protection complète, complétez avec une sauvegarde hors-site (rclone vers S3, SFTP vers un autre VPS).

APP_KEY invalide : l'erreur la plus courante

Si Firefly III affiche une erreur blanche au démarrage ou si l'authentification échoue sans message clair, vérifiez en premier la variable APP_KEY dans votre fichier .env.

Deux règles strictes :
1. La clé doit contenir exactement 32 caractères.
2. Elle ne doit jamais changer après le premier démarrage — changer l'APP_KEY sur une instance existante invalide toutes les sessions et chiffre les données stockées de façon incompatible.

Générer une clé valide :

openssl rand -hex 16
# Exemple de sortie : a8f2c9d1e4b7f0a3c5e8d2b1f4a7e0c3

Cette commande produit exactement 32 caractères hexadécimaux — parfait pour APP_KEY.

Firefly III vs YNAB vs Budgea

Critère	Firefly III (self-hosted)	YNAB	Budgea
Prix	Gratuit (coût VPS ~5-10€/mois)	~99$/an	~60€/an
Hébergement données	Votre VPS (souveraineté totale)	Serveurs US (Plaid)	Serveurs FR
Import bancaire	CSV/OFX + GoCardless (EU)	Connexion directe (US)	Connexion directe (FR)
Règles d'automatisation	Oui	Oui	Non
API REST	Oui (complète)	Non publique	Non
Multi-devises	Oui	Non (USD only)	Oui (partiel)
Rapports personnalisables	Oui (avancés)	Limités	Limités
Application mobile native	Non (web responsive)	Oui (iOS/Android)	Oui

Résoudre les problèmes fréquents

Firefly III reste en page blanche ou affiche une erreur 500
Vérifiez les logs du conteneur : docker compose logs firefly-iii. Les erreurs les plus fréquentes sont une APP_KEY invalide ou un PostgreSQL non encore prêt. Solution : vérifier que db est en état healthy avec docker compose ps avant d'accéder à l'UI.

Le Data Importer refuse le fichier CSV
Firefly III attend un format CSV spécifique. Si votre banque exporte un CSV avec des séparateurs point-virgule (;) au lieu de virgule, modifiez l'encodage dans l'assistant d'import ou convertissez le fichier avec sed 's/;/,/g' import.csv > import-virgule.csv.

Les transactions en double après import
Activez la déduplication dans le Data Importer : dans la configuration de l'import, cochez Ignore duplicates. Firefly III compare les transactions par date, montant et description pour éviter les doublons.

Erreur Connection refused à la base de données au démarrage
Firefly III utilise depends_on: condition: service_healthy pour attendre PostgreSQL. Si cette erreur persiste, vérifiez que POSTGRES_PASSWORD dans .env correspond à DB_PASSWORD.

Mettre à jour Firefly III

La v6.6.6 est sortie en juillet 2025. La mise à jour se fait en deux commandes :

cd /opt/firefly
docker compose pull
docker compose up -d

Docker Compose télécharge les nouvelles images, arrête les anciens conteneurs et redémarre avec la version mise à jour. Les migrations de base de données s'exécutent automatiquement au premier démarrage de la nouvelle version. Avant chaque mise à jour majeure, effectuez une sauvegarde manuelle de PostgreSQL.