Taking Control of Your Financial Data
Most personal finance apps require you to hand over your bank credentials, accept their data retention policies, and trust that their servers stay online. Firefly III takes the opposite approach: it runs entirely on your own hardware, stores nothing outside your control, and gives you a full double-entry accounting system without a subscription fee. For anyone who has grown uncomfortable watching a third-party app quietly sync every transaction they make, that tradeoff is worth the one-time setup effort.
Firefly III is a PHP-based web application that you host yourself, typically via Docker. It supports multiple accounts, budgets, recurring transactions, rules-based categorization, and detailed reporting. The learning curve is steeper than a polished mobile app, but the payoff is complete ownership of your financial records – no vendor lock-in, no feature removals, no price hikes.
What You Need Before You Start
The minimum requirement is a machine that can run Docker and Docker Compose. That could be a spare laptop running Ubuntu, a Raspberry Pi 4, a home server, or a cloud VPS you manage yourself. Firefly III officially supports Linux, and that is the environment this guide assumes. You will also need a domain name or local hostname if you plan to access the app from outside your home network, though a simple LAN setup works fine for a single-user deployment.
Make sure Docker and Docker Compose are installed and working before proceeding. Run docker –version and docker compose version to confirm. If either command fails, install them through your distribution’s package manager or follow the official Docker documentation for your OS.
Setting Up Firefly III with Docker Compose
The recommended way to deploy Firefly III is through the official Docker Compose file maintained by the project. Start by creating a dedicated directory for the installation. Run mkdir firefly-iii && cd firefly-iii to create and enter that folder. Then download the official compose file using curl -o docker-compose.yml https://raw.githubusercontent.com/firefly-iii/docker/main/docker-compose.yml. This file defines the Firefly III app container along with a MariaDB database container and a data importer container that you can use later.
Next, download the two environment files that the compose setup requires. Run curl -o .env https://raw.githubusercontent.com/firefly-iii/firefly-iii/main/.env.example for the main app config, and curl -o .db.env https://raw.githubusercontent.com/firefly-iii/docker/main/.db.env.example for the database config. Open the main .env file in a text editor. The most important variables to set immediately are APP_KEY, APP_URL, and the database credentials. For APP_KEY, generate a 32-character random string – you can use openssl rand -base64 32 and trim to 32 characters, or use the format base64:YOURSTRING as the app expects.
In the .db.env file, set a strong password for MYSQL_PASSWORD and make sure MYSQL_DATABASE and MYSQL_USER match the values referenced in your main .env file under DB_PASSWORD, DB_DATABASE, and DB_USERNAME. These two files need to agree on those values or the app will fail to connect to the database on startup. Double-check them before moving on – a mismatch here is the most common reason the initial launch fails.
Once both environment files are configured, run docker compose up -d from inside the firefly-iii directory. Docker will pull the required images and start the containers in the background. Give it a minute or two, then open a browser and navigate to http://your-server-ip:8080. If everything is working, you will see the Firefly III registration page. Create your admin account, log in, and you will land on the main dashboard.
Configuring Accounts and Currencies
Firefly III models your finances using accounts, and getting this structure right from the start saves a lot of cleanup later. The core account types are asset accounts (your actual bank accounts and wallets), expense accounts (merchants you pay), revenue accounts (income sources), and liability accounts (loans, credit lines). Start by adding every asset account you actively use – checking, savings, and any investment accounts you want to track. Set the opening balance for each account to its current real balance, and set the opening balance date to today so your historical data starts clean.
Under the preferences panel, set your default currency and time zone before entering any transactions. Firefly III supports multiple currencies per account, which is useful if you hold foreign accounts or frequently transact in different currencies, but the default currency determines how totals are displayed across the dashboard.
Importing Transactions and Setting Up Rules
Manually entering every transaction is possible but impractical. The data importer tool included in the Docker Compose setup handles CSV files exported from most banks. Log into the importer at http://your-server-ip:8081, connect it to your Firefly III instance using a personal access token generated from your profile settings, and upload a CSV from your bank. The importer walks you through mapping columns – date, amount, description, account – and lets you save that mapping as a configuration file for future imports.
Rules are where Firefly III becomes genuinely useful beyond basic bookkeeping. Navigate to Automation > Rules and create rules that fire on transaction creation or update. A rule can match on description keywords and automatically assign a category, budget, or tag. For example, a rule that matches descriptions containing “NETFLIX” or “netflix” can auto-assign those transactions to an Entertainment category. Building a solid ruleset over the first few weeks of use means most transactions categorize themselves without manual intervention.
Recurring transactions handle subscriptions, rent, and regular income. Under Automation > Recurring Transactions, set up each repeating transaction with its schedule, amount, and destination account. Firefly III will create these transactions automatically on schedule and flag them on the dashboard when they are due. This is particularly helpful for spotting months where a subscription renewed unexpectedly or a payment missed its usual date.
Securing and Maintaining Your Instance
Running a financial app on your home network without HTTPS is acceptable for purely local use, but if you plan to access Firefly III remotely, put it behind a reverse proxy with a valid SSL certificate. Nginx Proxy Manager or Caddy are both straightforward options that handle certificate issuance automatically through Let’s Encrypt. Point your subdomain at your server’s public IP, configure the proxy to forward traffic to port 8080, and enable HTTPS before accessing the app over the internet.
Backups are non-negotiable. The MariaDB data volume holds everything – transactions, rules, accounts, budgets. Add a cron job or Docker-based backup script that dumps the database daily using docker exec firefly-iii-db mysqldump -u firefly -p’yourpassword’ firefly > /backups/firefly-$(date +%F).sql and copies the result to a separate location. If you already use Syncthing for peer-to-peer file sync, routing those backup files through a Syncthing-monitored folder keeps an off-device copy without touching any cloud service. Losing a financial database with years of transaction history because of a failed drive is the kind of problem that is entirely preventable and extremely painful after the fact.
