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
.envand set:DB_PASSWORD,APP_KEY(exactly 32 chars — generate withopenssl rand -hex 16),APP_URL(your domain), andPOSTGRES_PASSWORD.Step 3 — Start the containers
docker compose up -d docker compose psThree containers should be
healthy:firefly-iii,db(PostgreSQL), andimporter. Firefly III waits for PostgreSQL usingdepends_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:8081in 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 formatmatching your bank's format (e.g.d/m/Yfor 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
Scroll the table
| 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.
Deploy Firefly III in One Click from the Marketplace
The ServOrbit Marketplace offers a Firefly III template that automatically sets up PostgreSQL 16 and the core application via Docker Compose on your Ubuntu 24.04 VPS — in minutes, without any command line. Choose your VPS, select the template, and find Firefly III ready to receive your accounts from first access. The APP_KEY is generated by ServOrbit at provisioning time.
