How to Use Firefly III: The Beginner's Guide (First Deploy, the Yesterday's-Balance Rule, Your First Budget, and the Cron-Job Rule)

CodexFuse Team · 2026-11-01T11:18:14.157Z · 15 min read

Learn how to use Firefly III: the first Docker deploy, the yesterday's-balance rule, transactions, budgets, the daily cron job, bills, rules, and CSV imports.

What is Firefly III, exactly?

Firefly III is a self-hosted, open-source personal finance manager — not Adobe Firefly AI, the image generator that shares the name. If you are looking for a firefly iii tutorial that starts from zero, here is the one-line version: you run Firefly III on your own server or home machine, it stores every account, transaction, budget, and bill you have, and your money data never leaves hardware you control.

The project is a full double-entry bookkeeping system wrapped in a web UI, with a REST JSON API, piggy banks for savings goals, categories and tags, two-factor authentication, budgets, financial reports, and support for any currency including crypto. It is licensed GNU AGPL-3.0 and lives at github.com/firefly-iii/firefly-iii, where it has collected roughly 25,049 stars and 2,356 forks since its 2014 start — the maintainer still calls it "a side gig." The current stable release as of November 2026 is v6.7.9.

Learning how to use Firefly III means learning a small set of rules, each of which this guide covers once: the yesterday's-balance rule that makes your books self-checking, the positive-amounts rule for withdrawals, the auto-created account lesson, the auto-budget lesson, the cron-job rule, and the rules engine that keeps imported transactions tidy. Follow this page end to end and you will have a working personal finance system, not just a running container.

How do you use Firefly III, step by step?

If you want the entire first run in one glance, this is it — this is how to use Firefly III from a blank server to a working personal budget.

1. Deploy the official Docker stack (app, MariaDB, and a cron container) and open the web UI.
2. Register your account, pick your currency, and name your first bank.
3. Enter yesterday's balance — never today's — so Firefly III can compute today for you.
4. Recreate yesterday's transactions by hand as a correctness check on your books.
5. Learn the transaction rules: withdrawals are entered as positive amounts, and expense and revenue accounts create themselves when you type.
6. Organize with categories and tags so reports mean something later.
7. Set your first budget — and an auto-budget if you want it to repeat every month.
8. Turn on the daily cron job, because auto-budgets silently fail without it.
9. Create bills for recurring payments like rent and subscriptions.
10. Build one or two rules to auto-categorize future imports, then import your bank history as CSV.

How do I install Firefly III with Docker?

The Docker path is the recommended one for beginners: the official stack is three containers — the app (fireflyiii/core:latest, built for linux/amd64 and linux/arm64), the database (mariadb:lts), and a tiny alpine cron container that just calls the app's cron endpoint. New to containers? Start with our Docker beginner guide first.

Get the official compose file and the two config templates, then fill in three values that cannot be defaults. In .env, APP_KEY must be a random string of exactly 32 characters — generate it with head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32 and avoid =, #, and other special characters. Also in .env, STATIC_CRON_TOKEN must be another random string of exactly 32 characters; the cron container uses it to authenticate against the app. In .db.env, set DB_PASSWORD to match MYSQL_PASSWORD — and do it before the first run, because the database volume keeps whatever password it was initialized with.

cp .env.example .env
cp database.env .db.env
echo "edit .env and .db.env: APP_KEY, STATIC_CRON_TOKEN, DB_PASSWORD/MYSQL_PASSWORD"
docker compose -f docker-compose.yml up -d --pull=always

Open http://localhost in a browser and register your first account. The compose file maps host port 80 to the app's port 8080; if you are putting this on a public server, set APP_URL to your real URL and TRUSTED_PROXIES=** so Firefly III trusts your reverse proxy — our Caddy beginner guide covers the HTTPS part in one config file. Running this on rented hardware? Our what is VPS hosting explainer covers what that means in plain terms.

PostgreSQL users are not left out: set DB_CONNECTION=pgsql, change the port to 5432, swap the MYSQL_* variables for POSTGRES_* ones, and point the database service at the postgres image. SQLite is also a supported fallback. This is the firefly iii docker story in full: three containers, two config files, three secrets you must set yourself.

What do I do right after registering?

You name your currency and your first bank, and then you hit the most important moment in this whole guide: enter yesterday's balance, not today's. The vendor's own first-steps tutorial says it plainly — do not fill in today's balance; instead, fill in yesterday's, recreate yesterday's transactions, and let Firefly III calculate today's balance for you. That number matching your real balance is your proof the books are correct. It is the whole reason this firefly iii self hosted setup can be trusted from day one.

After that, the opening wizard gets out of your way and the main dashboard appears. Do not try to configure everything on day one. Enter one account, enter the yesterday's-balance number, recreate yesterday's handful of transactions, and watch today's balance land exactly where your bank app says it is. Everything else in this guide builds on that trust.

How do withdrawals, deposits, and transfers work?

Every transaction starts at the + (plus) button in the top-right corner. Firefly III has three transaction types, and each has exactly one rule you must learn once.

The auto-create behavior trips every beginner, so learn it deliberately: under "Destination account" on a withdrawal, type the store name — "Walmart," "Amazon," anything — and Firefly III creates that expense account for you on the spot. The same works in reverse for deposits: type the money's source ("My job," "Freelance client") in the Source Account field and it appears. There is no account-management chore before your first transaction, which is why a firefly iii tutorial can start with spending money on day one.

How do categories and tags fit in?

Categories and tags are how Firefly III turns a pile of transactions into reports worth reading. A category is a fixed bucket like "Groceries" or "Transport"; a tag is a flexible label like "vacation" or "tax-deductible" that can cut across categories. Attach both as you enter transactions — do not plan a taxonomy first and do not backfill later. A month of tagged transactions produces the spending-by-category charts that make the budgets section of this guide actually useful.

How do Firefly III budgets work?

Budgets work best measured from the first day of the month to the last, though weekly and other periods are fine. A basic budget is simply a maximum amount per period, set on the /budgets page and linked to the expenses on your transactions. That alone answers the "how much did I spend on groceries in October" question, and it is where the firefly iii budgets story starts.

The real power is auto-budgets: amounts that repeat automatically every period instead of being set by hand. The vendor's budgets guide gives the exact repeat table, and it matters which day each one fires:

Auto-budgets also grow: a "growing" auto-budget adds the amount each period (25 becomes 50, then 75), and a "growing but correct for expenses" variant reduces next month's amount when you overspend — if you spend more than twice the budget, it sets a symbolic 1 as a nudge. Note the hard lesson the docs state outright: auto-budgets are only created on the first day of their period, and if the cron job does not run at that moment, the amount is never set. That is why the next section is not optional.

Why does Firefly III need a daily cron job?

The cron job is the heartbeat of a Firefly III install. Auto-budgets fire only when it runs, recurring transactions only post when it runs, exchange rates only refresh when it runs, and bill notifications only send when it runs. The vendor's cron guide is unambiguous: the cron job should run daily. This is the firefly iii cron lesson in one sentence: skip it and your budgets silently stop working.

In the official Docker stack this is already handled: the alpine cron container runs 0 3 * * * wget -qO- http://app:8080/api/v1/cron/$STATIC_CRON_TOKEN — that is 3:00 AM every day, hitting the app's cron endpoint with the 32-character token you set in .env. On a bare-metal install the equivalent is 0 3 * * * /usr/bin/php /var/www/html/artisan firefly-iii:cron. If you ever migrate away from the compose stack, that single line is the thing you must recreate — everything recurring in Firefly III depends on it.

How do bills work?

A bill is a recurring payment with a name: rent, Spotify, your phone plan. Creating one takes a name, a description, a minimum and maximum expected amount (their average feeds the charts and the front-page "how you're doing" box), the period, the first expected date, a skip count, and optional end dates. The clever part comes right after creation: Firefly III redirects you to create a rule that is already auto-filled to match the bill's amount and description, so future transactions link themselves to the bill automatically. Set up your bills once and the bills page becomes the honest calendar of money leaving your accounts.

What can the Firefly III rules engine do?

Rules are Firefly III's answer to the mess that bank imports create: hundreds of transactions with cryptic descriptions, none categorized. Rules live in rule groups, run in order, and were designed for exactly this — updating imported data in bulk and auto-categorizing new transactions. This is the firefly iii rules engine, and it is the feature that separates a finance tracker from a finance assistant.

Each rule has triggers and actions. Triggers fire on things like transaction creation, a description containing a word, an amount above X, or a specific budget. You can require ALL triggers to match (strict) or ANY of them, and any trigger can be inverted. Actions then do the work: set the budget, category, or tags, rewrite the description, adjust the amount, change the source or destination account — even run expressions for complex cases. A "stop processing" option halts the rest of the group once a rule fires, which keeps your logic clean.

Two limits to know: a rule cannot fire other rules, and rule actions cannot create brand-new transactions (webhooks are the escape hatch for that). Rules can move money into piggy banks, but only on transfers. Start with two rules — one that tags your grocery store's transactions and one that categorizes your salary — and let the engine earn its keep before you build more.

How do I import my bank history as CSV?

Imports are handled by a separate companion, the Firefly III Data Importer — kept as its own app "for security and maintenance reasons" — which talks to Firefly III through its API. The supported file formats are CSV from any source (your bank, YNAB, Tiller), CAMT.052 and CAMT.053 bank-statement files, plus direct bank connections via Spectre/GoCardless if you want ongoing sync instead of manual imports.

The flow is designed to be learned once and repeated forever: your first import runs through the Importer UI and generates a JSON configuration file mapping your bank's columns to Firefly III's fields. Every later import reuses that config — through the UI, the CLI (php artisan importer:import config.json file.csv), or an HTTP POST auto-upload with a Personal Access Token. That reusable config plus your rules is why the firefly iii import csv story is a one-time setup, not a monthly chore: map the columns once, auto-categorize with rules, and your history lands clean every time.

Firefly III vs Actual Budget: which should you pick?

Both are self-hosted, open-source, and free — but they serve different brains. The honest comparison from the self-hosting community: Actual Budget is the better choice if you want envelope-style budgeting with a fast, offline-first interface. Firefly III is the better choice if you need full double-entry bookkeeping with detailed reporting, automated transaction rules, and multi-currency support. Most people looking for a self-hosted YNAB replacement should pick Actual; most people wanting to track every financial account they own should pick Firefly III. (Actual Budget ships MIT; Firefly III ships AGPL-3.0.)

If the envelope-budgeting lane is yours, our Actual Budget beginner guide walks through it the same way this guide does — first deploy, first budget, the rules that keep it honest. This guide's lane is the full personal-finance-manager lane: asset and liability accounts, bills, piggy banks, the rules engine, and CSV imports in one system.

Should you self-host Firefly III or use a cloud option?

Firefly III is self-host-first software: there is no official hosted plan, so the self hosted personal finance question is really a hosting question. The Docker stack in this guide runs anywhere Docker runs — a home server, a Raspberry Pi (the images ship arm64), or a rented VPS. If you go the VPS route, our what is VPS hosting explainer will orient you, and the yesterday's-balance rule from this guide still applies the moment your instance is up. Your money data stays on hardware you chose, behind credentials you set — that is the entire point of the exercise.

Sources

Every fact in this guide was verified against a page fetched on November 1, 2026:

• Docker installation guide — docs.firefly-iii.org/how-to/firefly-iii/installation/docker/ (updated Oct 26, 2026): official compose stack, APP_KEY and STATIC_CRON_TOKEN rules, DB_PASSWORD warning
• Docker FAQ — docs.firefly-iii.org/references/faq/docker/: fireflyiii/core:latest, amd64+arm64 builds
• Official docker-compose.yml — raw.githubusercontent.com/firefly-iii/docker/main/docker-compose.yml: app/db/cron services, the 3:00 AM cron container entry
• GitHub releases — github.com/firefly-iii/firefly-iii/releases: v6.7.9 current stable
• GitHub repository — github.com/firefly-iii/firefly-iii: AGPL-3.0, ~25,049 stars, ~2,356 forks, features list
• "My first accounts" tutorial — docs.firefly-iii.org/tutorials/finances/first-steps/ (updated Jan 10, 2024): the yesterday's-balance rule
• First accounts tutorial — docs.firefly-iii.org/tutorials/finances/first-accounts/ (updated Feb 6, 2025): positive amounts, auto-created accounts, transfers
• Budgets how-to — docs.firefly-iii.org/how-to/firefly-iii/finances/budgets/ (updated Oct 26, 2026): auto-budget table, the cron requirement
• Cron how-to — docs.firefly-iii.org/how-to/firefly-iii/advanced/cron/: bare-metal schedule, what the cron fires
• Bills how-to — docs.firefly-iii.org/how-to/firefly-iii/finances/bills/: bill fields, auto-created matching rule
• Rules how-to — docs.firefly-iii.org/how-to/firefly-iii/features/rules/: triggers, actions, rule groups, limits
• Importing data tutorial — docs.firefly-iii.org/tutorials/firefly-iii/importing-data/ (updated Oct 26, 2026): Data Importer, CSV/CAMT formats, JSON config flow
• Self-managed installation — docs.firefly-iii.org/how-to/firefly-iii/installation/self-managed/ (updated Oct 26, 2026): PHP 8.5, MySQL/MariaDB, release zip upgrade path
• Actual Budget vs Firefly III — selfhosting.sh/compare/actual-budget-vs-firefly/ (updated March 2026): the draw-the-line comparison
• XDA Developers — xda-developers.com/manage-your-finances-with-firefly-iii/ (Dec 7, 2024): the closest existing walkthrough, install-focused

Frequently asked questions

Is Firefly III the same as Adobe Firefly?

No. Firefly III is a self-hosted, open-source personal finance manager (AGPL-3.0); Adobe Firefly is Adobe's AI image generator and has nothing to do with it. When searching, include "firefly iii" with the Roman numeral and "self hosted" to land on the right product.

Is Firefly III free to use?

Yes — the software is free and open source under AGPL-3.0, with no paid tiers and no feature gates. Your only cost is wherever you run it: a home machine, a Raspberry Pi, or a VPS.

What does the Firefly III cron job actually do?

The daily cron fires recurring transactions, creates auto-budgets on the first day of each period, refreshes exchange rates, and sends bill notifications. Without it running daily, auto-budgets are never set — the official Docker stack includes an alpine container that hits the app's cron endpoint at 3:00 AM every day.

Can Firefly III import my existing bank transactions?

Yes, through the separate Firefly III Data Importer app. It accepts CSV files from any bank (plus CAMT.052/CAMT.053 statements and direct bank sync via Spectre/GoCardless). Your first import creates a reusable JSON column-mapping config, and rules auto-categorize everything after that.

Do I need Docker to run Firefly III?

No, but it is the easiest path. Bare-metal installs need a LAMP/LEMP/WAMP stack with PHP 8.5 and MySQL/MariaDB (SQLite is a supported fallback), installed from the official release zip and upgraded with php artisan firefly-iii:upgrade-database. Whichever path you choose, the daily cron line is the one thing you must not skip.