Why Firefly III Instead of a SaaS Tool?
Firefly III solves three problems at once: AGPL-3.0 license (open, modifiable), docker-compose in under ten commands, data in your own PostgreSQL database. With 24,300 GitHub stars and v6.6.6 released in July 2025, it is a mature, actively maintained project.
What Firefly III handles for you: checking and savings accounts, credit cards, crypto wallets, monthly or annual budgets, transaction automation rules, custom categories, period/category reports, and bank statement imports via the Data Importer.
Key Features
- Multi-account management: simultaneously manage checking, savings, credit card, and crypto wallet accounts.
- Budgets and envelopes: set monthly budgets by category and track consumption in real time.
- Automation rules: create rules applied automatically to new transactions.
- Advanced reports: period/account/category charts, exportable to CSV for your accountant.
- Data Importer: import bank statements via OFX, QFX, CSV, or European bank connectors (GoCardless).
- Full REST API: automate transaction creation from any script or third-party tool.
- Responsive mobile interface: access your accounts from your phone via the browser.
Server Prerequisites
Firefly III is a lightweight PHP/Laravel application. Minimum requirements: a VPS with at least 1 GB of RAM (2 GB recommended), Docker Engine ≥ 24 and Docker Compose V2, a domain name for TLS configuration, port 8080 accessible (Firefly III UI) and 8081 (Data Importer), 5 GB of storage minimum.
Installation with Docker Compose
Step 1 — Clone the official repository
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.envStep 2 — Configure environment variables
Open .env and set: DB_PASSWORD, APP_KEY (exactly 32 chars — generate with openssl rand -hex 16), APP_URL (your domain), and POSTGRES_PASSWORD.
Step 3 — Start the containers
docker compose up -d
docker compose psThree containers should be healthy: firefly-iii, db (PostgreSQL), and importer. Firefly III waits for PostgreSQL using depends_on: condition: service_healthy.
Step 4 — Access the interface
Open your browser at http://<VPS_IP>:8080. Create your admin account. The setup wizard guides you through creating your first bank account.
Step 5 — Set up Nginx with TLS
Configure Nginx as a reverse proxy with a Let's Encrypt certificate:
certbot --nginx -d firefly.yourdomain.com
nginx -t && systemctl reload nginxThen close port 8080 in your firewall.
Step 6 — Import Your Bank Statements
The Data Importer runs on port 8081. Go to http://localhost:8081 in your browser:
1. Upload your bank's CSV file or connect via GoCardless (EU banks).
2. Choose target account (the one you created in Firefly III).
3. Click Import and review the mapped transactions.
Important: configure a Date format matching your bank's format (e.g. d/m/Y for a French Crédit Agricole CSV).
Set Up Budgets and Automation Rules
Create a monthly budget: go to Budgets → New budget, name the budget (e.g., "Office Supplies"), set the monthly amount, and link transactions to it.
Create an automation rule: go to Automation → Rules → New rule, set a trigger (e.g., "Description contains 'Amazon'"), then set an action ("Assign to Office Supplies category"). Rules apply automatically to new transactions.
Export for your accountant: go to Export data, select CSV format, filter by period and account.
Schedule Automatic Backups
Firefly III stores data in PostgreSQL. Schedule a daily backup:
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
echo '0 3 * * * root /opt/firefly/backup.sh' >> /etc/cron.d/firefly-backupInvalid APP_KEY: The Most Common Error
If Firefly III shows a blank page or authentication fails, check APP_KEY in your .env first. Two strict rules: exactly 32 characters, and never change it after first launch — changing it invalidates all sessions and corrupts encrypted stored data.
Generate a valid key: openssl rand -hex 16
Firefly III vs YNAB vs Budgea
| Criterion | Firefly III (self-hosted) | YNAB | Budgea |
|---|---|---|---|
| Price | Free (VPS cost ~$5-10/mo) | ~$99/year | ~€60/year |
| Data hosting | Your VPS (full sovereignty) | US servers (Plaid) | FR servers |
| Bank import | CSV/OFX + GoCardless (EU) | Direct connection (US) | Direct connection (FR) |
| Automation rules | Yes | Yes | No |
| REST API | Yes (full) | Not public | No |
| Multi-currency | Yes | No (USD only) | Yes (partial) |
| Customizable reports | Yes (advanced) | Limited | Limited |
| Native mobile app | No (responsive web) | Yes (iOS/Android) | Yes |
Troubleshoot Common Issues
Firefly III shows a blank page or 500 error: check container logs with docker compose logs firefly-iii. Most common cause: invalid APP_KEY or PostgreSQL not yet ready.
Data Importer rejects the CSV: check that your bank's CSV uses comma separators. Convert with sed 's/;/,/g' import.csv > import-comma.csv.
Duplicate transactions after import: enable deduplication in the Data Importer by checking Ignore duplicates.
Connection refused to database on startup: verify that POSTGRES_PASSWORD in .env matches DB_PASSWORD.
Update Firefly III
cd /opt/firefly
docker compose pull
docker compose up -dDocker Compose downloads the new images and restarts with the updated version. Database migrations run automatically on first startup. Before any major update, take a manual PostgreSQL backup.
