Firefly III Complete Guide: Self-Hosted Personal Finance

What is Firefly III?

Firefly III is a free, open-source, self-hosted personal finance manager. It helps you track spending, manage budgets, monitor savings goals, automate imports, and make better decisions about your money — all while keeping your financial data entirely under your control.

Unlike cloud-based tools (YNAB, Monarch, Actual), Firefly III never phones home, never uploads your transactions, and never requires a subscription. Once you install it, you own it forever — data, code, and all.

Why Firefly III over cloud alternatives?

The trade-off is clear: Firefly III requires setup and some comfort with Docker and self-hosting. The reward is a lifetime of privacy and unlimited customisation without recurring vendor costs.

Who is it for?

• Self-hosters and home-labbers who want full control over their data
• Privacy-conscious users who refuse to share bank data with aggregators
• Power users who want to build custom rules, automations, and reports
• Multi-currency households or expats managing several regions of money
• Small teams / couples doing shared-household accounting

If you want to track money without giving anyone else your bank login — this is your tool.

Key Financial Concepts in Firefly III

Firefly III uses several overlapping but distinct classification systems. Understanding them upfront saves hours of confusion later.

The Six Classifications

1. Accounts

Every financial account lives here: your bank account, your credit card, your savings, your mortgage. Each account has a type:

💡 Design tip: create one asset/revenue/liability per real-world account. But for expenses, be flexible — you can have one “Groceries” expense account, or separate ones for “Coles”, “Woolies”, “Aldi”. Whichever matches how you think about your spending.

2. Categories

Use categories to answer: “What was this for?”

• Groceries, Utilities, Car Maintenance, Dining Out, Christmas gifts.
• Categories are flexible, optional, and never block budgets.

3. Budgets

Use budgets to answer: “How much can I spend this period?” Every budget has a limit (say, $600/month for Groceries) and Firefly shows you progress bars as you spend against it. This is the key tool for staying within limits.

4. Tags

Use tags to judgmentally label transactions retroactively.

• bad-buy-2026, impulse, shared-cost, reimbursable-from-Dawn, deductible.
• Tags are excellent for ad-hoc analysis, not for limiting spend.

5. Recurring transactions

Automated repetition — rent, Netflix, salary, fortnightly transfer to savings. Once defined, Firefly automatically generates the matching transactions on schedule.

6. Rules

The automation engine. When a transaction arrives with certain properties, a rule can assign a category, set a budget, add a tag, convert currency, etc. Rules turn messy bank imports into clean, organised data.

A worked example

A $47 Coles groceries purchase is stored as:

The budget limits your monthly groceries spend and tracks progress.
The category groups it logically so you can slice reports.
The tag labels it for future retrieval.
The expense account (“Coles”) lets you see how much you’ve spent at that specific shop over time.

All four tools do different jobs. Learn which answers which question and you’re set.

Transaction types

Firefly uses a classic double-entry model. Every transaction has a source and a destination. There are only three kinds:

Installation on Docker (Recommended)

Firefly III ships as a Docker image (fireflyiii/core) and is trivial to self-host with a docker-compose.yml. Here’s the production-ready version running on your own EliteDesk.

Prerequisites

• Docker + Docker Compose installed
• A stable storage location (on your box, a volume, or a separate drive)
• ~500 MB free disk space
• 1–2 GB RAM available for the stack

Minimal production docker-compose.yml

Create a directory called firefly-iii somewhere durable (/home/user/firefly-iii/ works fine on Linux Mint):

x-common: &common
  restart: unless-stopped
  networks:
    - firefly-iii

services:
  firefly-iii:
    <<: *common
    image: fireflyiii/core:latest
    container_name: firefly-iii
    ports:
      - "8080:8080"
    volumes:
      - firefly_iii_upload:/var/www/html/storage/upload
    environment:
      SITE_OWNER: "you@example.com"
      APP_KEY:            # see "Generate an APP_KEY" below
      TZ: "Australia/Melbourne"
      TRUSTED_PROXIES: "**"
      DB_HOST: db
      DB_PORT: "3306"
      DB_CONNECTION: mysql
      DB_DATABASE: firefly_iii
      DB_USERNAME: firefly
      DB_PASSWORD:         # pick a strong password
      MAIL_MAILER: "log"
      APP_URL: "http://localhost:8080"
    depends_on:
      - db

  db:
    <<: *common
    image: mariadb:10.11
    container_name: firefly-db
    volumes:
      - firefly_iii_db:/var/lib/mysql
    environment:
      MYSQL_DATABASE: firefly_iii
      MYSQL_USER: firefly
      MYSQL_PASSWORD:         # same as above
      MYSQL_RANDOM_ROOT_PASSWORD: "yes"

volumes:
  firefly_iii_upload:
  firefly_iii_db:

networks:
  firefly-iii:

Generate a secure APP_KEY

The APP_KEY encrypts session cookies and stored credentials. Never reuse or lose it, or you lose stored data access. Generate once:

docker run --rm fireflyiii/core:latest php artisan key:generate --show

Copy the output (base64:xxxxxxxx...) verbatim into docker-compose.yml.

Start the stack

cd /home/user/firefly-iii
docker compose up -d
docker logs -f firefly-iii

Initial startup takes 1–2 minutes for migrations. Watch the logs for Application startup complete. Then open http://localhost:8080 and log in with the email address you set in SITE_OWNER.

Post-install checklist

• Change your password immediately after login
• Enable 2FA under Profile → Two-Factor Authentication
• Set your default currency and timezone under Administration → Configuration → Localization
• Export the APP_KEY password from your secrets manager
• Schedule a weekly backup (see Backups section)

Optional: data importer

For automated bank CSV / Open Banking imports, spin up the Data Importer alongside:

git clone --depth 1 https://github.com/firefly-iii/data-importer.git
cd data-importer
cp .env.example .env     # edit it
docker compose up -d

The importer runs on http://localhost:8081 (separate from Firefly itself) and supports CSV, CAMT.053, and — with your free GoCardless/Nordigen credentials — direct European bank feeds.

First-Time Setup Walkthrough

Once you’ve logged in, here’s the order to do things:

Step 1 — Configure basics

Go to Profile → Preferences:

• Set default currency (AUD)
• Set first day of week (Monday)
• Enable dark mode or leave default

Step 2 — Create your asset accounts

Navigate to Accounts → Asset accounts → Create new. Start with:

• Your primary transaction account (e.g. “CBA Everyday Access”)
• Your main savings account (e.g. “Macquarie Savings”)
• Any cash envelope (even $20 in your wallet counts)
• Credit cards if you use them as a payment method

Each asset account should start with a current balance (opening balance transaction) so the rest of the math has a real baseline.

Step 3 — Create expense accounts (optional but useful)

Firefly lets you lump every purchase into a generic “expense”, or get specific. I recommend at least these:

• “Everyday groceries”
• “Dining out”
• “Fuel”
• “Utilities”
• “Transport”

You can create more granular vendor accounts later (Coles, Woolies, Origin, etc.) as you need them.

Step 4 — Create revenue accounts

One per income source:

• Your primary employer
• Any side-income payer
• “Refunds” (a generic revenue account)

Step 5 — Set your budgets

Go to Budgets → Create new and add the big buckets:

• Groceries — $400/month
• Utilities — $250/month
• Dining out — $200/month
• Transport — $150/month
• Everything else — $300/month

Don’t aim for perfect on the first month. Let the first month be a data-gathering exercise; refine ranges afterwards.

Step 6 — Schedule recurring transactions

Anything regular belongs here:

• Monthly rent/mortgage
• Utilities bills
• Payroll deposits
• Netflix, Spotify, gym — every subscription
• Transfers to savings / offset mortgage

Firefly will generate the actual transactions on schedule so your future never looks empty.

Daily Workflow

Once you’re set up, your daily workflow is simple:

1. Open Firefly. Either the web UI on your laptop or a pinned tab on your phone.
2. Check the dashboard. Are there uncategorised transactions? Are any budgets close to their limit?
3. Add or import new transactions. Either manual entry or CSV from your bank app.
4. Run rules. If you have rules that auto-categorise, they’ll have fired on import. Otherwise, tidy up manually.
5. Glance at reports. The dashboard chart shows spending by category this month.

Total time: 5–10 minutes most days, longer on import day.

Manual entry tips

• Keep the “quick add” button in your phone’s home screen (or use a Telegram/WhatsApp shortcut with Firefly’s API).
• Use the description autocomplete — it remembers past vendors.
• Use amount shortcuts: 47.50 is fine; AUD 47.50 works too.
• Set a default expense account so 90% of groceries don’t need a vendor account.

Automation with Rules

Rules are what turn Firefly III from a ledger into a true finance system. They run on every transaction — whether entered manually or imported.

Rule anatomy

Each rule is:

1. A list of triggers (all must match, OR logic option available)
2. A list of actions (applied in order)
3. A scope — new transactions only, or also existing ones?

Example: “Every transaction whose description contains ‘COLES’ goes into the Groceries budget and the ‘Groceries’ category.”

Triggers:
  - Description contains "coles" (case-insensitive)

Actions:
  - Set category to "Groceries"
  - Set budget to "Groceries"
  - Add tag "weekly-shop"

Rule-writing best practices

• Order matters. Most specific rules first, most generic last. “Coles at Chermside” before “Coles”.
• Keep rules small and composable. 30 rules of 3 actions each is nicer than 1 giant rule.
• Put “catch-all” rules last — they only fire if nothing before them matched.
• Always test on existing transactions before enabling. Firefly offers a “test on existing” toggle.
• Use regular expressions when literal strings aren’t flexible enough. ^\*POS\s+Caf.* matches any Cafe purchase from a bank CSV.

Common starter rules

Running rules on historical data

When you add a new rule and want it to apply to past transactions:

1. Go to Automation → Rules
2. Click the rule, then “Test against existing transactions”
3. Review the preview — make sure it matched correctly
4. Click “Apply to existing transactions”

This is how you clean up hundreds of old transactions in one afternoon.

Importing Transactions from Your Bank

Option 1: CSV (Universal)

Almost every bank lets you export a CSV. Go to Import → Upload file and follow the wizard:

1. Upload the CSV.
2. Map each column (date, amount, description, reference).
3. Pick how amounts are signed (negative = withdrawal on most AU banks).
4. Preview the mapped import.
5. Confirm.

Common AU bank CSV formats:

• CommBank: “Date, Description, Amount, Balance”
• ANZ: 3-column or 4-column export
• Macquarie: CSV with signed amounts
• NAB / Westpac: CSV with separate debit/credit columns

Option 2: Direct bank feeds (Nordigen / GoCardless)

European banks get direct integration via the free Nordigen / GoCardless Open Banking API. Australian banks support Open Banking but via the CDR register which requires individual merchant registration — not trivial.

For AU users, CSV is still the most practical approach. For EU/UK readers, Nordigen gives you real-time sync.

Option 3: The Data Importer

The separate Data Importer is a dedicated UI/CLI for bulk jobs. It handles:

• CSV imports with saved column mappings
• CAMT.053 XML bank statements (common in Europe)
• Spectre / Nordigen connectors

Run it as a separate Docker container pointing at http://firefly-iii:8080.

Post-import triage

Every import produces a batch of transactions that need:

• Matching to budgets
• Categorisation (or auto-categorisation via rules)
• Flagged duplicates (use “merge duplicates” under Import → Tools)

Reporting and Analysis

Firefly ships with five main report types:

1. Dashboard report (default view)

Current month at a glance:

• Income vs expense balance
• Budget progress bars
• Category breakdown
• Net worth trend

2. Transaction reports

Time-bounded views (“All of 2026”, “March to April”, “Last 30 days”). Filter by account, category, tag, or budget. Export to CSV.

3. Budget reports

For each budget:

• Planned vs actual
• Remaining balance for the period
• Daily spend allowance

4. Category reports

How much you spent on Groceries vs Dining Out vs Utilities in any period.

5. Tag reports

Use for ad-hoc analysis: show me everything tagged bad-buy-2026 and total the damage.

Custom reports (API)

Every piece of data in Firefly is available through the REST JSON API. Pair it with Python, Pandas, or Metabase to build reports that Firefly itself doesn’t yet ship.

Backups

Since Firefly is self-hosted, you own the backups. Schedule automated dumps of both the database and the upload volume.

Daily backup script (Linux)

Drop into ~/bin/firefly-backup.sh:

#!/usr/bin/env bash
set -euo pipefail

BACKUP_DIR="/home/user/backups/firefly"
DATE="$(date +%Y-%m-%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"

# MariaDB dump
docker exec firefly-db mariadb-dump \
  -u firefly \
  -p"${DB_PASSWORD}" \
  --single-transaction \
  firefly_iii | gzip > "$BACKUP_DIR/db_$DATE.sql.gz"

# Upload volume (receipts, attachments)
docker run --rm \
  -v firefly-iii_firefly_iii_upload:/src \
  -v "$BACKUP_DIR":/dst \
  alpine:3 \
  tar -czf /dst/uploads_$DATE.tar.gz -C /src .

# Keep last 180 days of backups
find "$BACKUP_DIR" -name "*.sql.gz" -mtime +180 -delete
find "$BACKUP_DIR" -name "*.tar.gz" -mtime +180 -delete

Run daily via cron: 0 3 * * * /home/user/bin/firefly-backup.sh.

Best Practices and Pitfalls

The Five Mistakes Everyone Makes

1. Mixing up budgets, categories, and tags. Remember: budgets limit spending, categories classify it, tags judge it.
2. Forgetting to set an opening balance. All your math will be wrong until the first transaction anchors the baseline.
3. Using expense accounts for everything. Don’t create one expense account per vendor unless you want to. Lumping is fine.
4. Writing one giant rule. Build 30 small, focused rules instead. They’re easier to debug.
5. Not backing up. The database is plain MariaDB. Back it up weekly at minimum.

Things that will delight you

• Piggy banks: visual savings goals (“New MacBook — $1,200 target”).
• Bills engine: predicts recurring bills so you never get surprised by electricity.
• Auto-budgets: roll-over or top-up each month automatically.
• Shared household expenses: split grocery bills across housemates with the built-in “shared expenses” view.
• 2FA: enable it — your financial data is worth protecting.

Things to be patient about

• Learning curve: you’ll feel inefficient the first week. By week three, you’ll be faster than any bank app.
• Mobile experience: the web app works fine on phones, but there’s no native app. Bookmark it.
• Bank integration: Australian Open Banking via GoCardless is doable but awkward. CSV imports are the path of least resistance.

Glossary

Recommended Next Steps

1. Complete the first-time setup walkthrough above.
2. Import the last 3 months of bank CSVs so you have real data.
3. Create 5 starter rules (salary, groceries, fuel, streaming, rent).
4. After Month 1, refine your budget limits based on actual data.
5. Add the daily backup script to cron.
6. Explore the Firefly III API once you’re comfortable — it’s excellent for custom reports and integrations.

Resources

• Official documentation: https://docs.firefly-iii.org
• GitHub repo: https://github.com/firefly-iii/firefly-iii
• Community forum / discussions: https://github.com/orgs/firefly-iii/discussions
• Data Importer: https://github.com/firefly-iii/data-importer
• REST API reference: https://api-docs.firefly-iii.org

Final Thoughts

Firefly III is one of those rare self-hosted projects that genuinely replaces a paid SaaS product and does it better — because it’s yours, forever. There is a modest learning curve, yes. The first two weeks feel like homework.

After that, you’ll find yourself spending less, saving more, and actually understanding where your money went. That clarity is worth the 20 minutes it takes to install.

The guide on this site (docker-basics) covers everything you need to fire up the Docker side. This guide covers the financial side. Between them, you’ve got a complete self-hosted finance stack.

Guide compiled from Firefly III official documentation and practical self-hosting experience. Last reviewed July 2026.