What is Firefly III?
Firefly III is a free and open-source personal finances manager designed to give you insight into and control over your finances. Built on the principle that knowing where your money goes helps you stop it from going there, Firefly III offers:
- Complete self-hosting with full data isolation
- Double-entry bookkeeping system
- Budget tracking and management
- Rule-based transaction handling
- Recurring transaction support
- Multi-currency support
- REST JSON API
- 2-factor authentication
- Comprehensive financial reports and charts
Prerequisites
Before starting, ensure you have:
- A server running Linux (Ubuntu, Debian, or similar)
- Docker and Docker Compose installed
- Basic command line knowledge
- Port 80 (or custom port) available
Docker Compose Configuration
Download Required Files
First, create a directory for your Firefly III installation:
|
1 2 3 4 |
mkdir ~/firefly-iii cd ~/firefly-iii |
Download the Docker Compose configuration file:
|
1 2 3 |
curl -O https://raw.githubusercontent.com/firefly-iii/docker/main/docker-compose.yml |
Complete Docker Compose File
Here’s the complete docker-compose.yml configuration:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 |
services: app: image: fireflyiii/core:latest hostname: app container_name: firefly_iii_core restart: always volumes: - firefly_iii_upload:/var/www/html/storage/upload env_file: .env networks: - firefly_iii ports: - 80:8080 depends_on: - db db: image: mariadb:lts hostname: db container_name: firefly_iii_db restart: always env_file: .db.env networks: - firefly_iii volumes: - firefly_iii_db:/var/lib/mysql cron: image: alpine restart: always container_name: firefly_iii_cron env_file: .env command: sh -c " apk add tzdata && \ (ln -s /usr/share/zoneinfo/$$TZ /etc/localtime || true) && \ echo \"0 3 * * * wget -qO- http://app:8080/api/v1/cron/$$STATIC_CRON_TOKEN;echo\" | crontab - && \ crond -f -L /dev/stdout" networks: - firefly_iii depends_on: - app volumes: firefly_iii_upload: firefly_iii_db: networks: firefly_iii: driver: bridge |
Understanding the Components
App Service: The main Firefly III application running on port 8080 (mapped to host port 80)
Database Service: MariaDB database for persistent data storage
Cron Service: Handles scheduled tasks like recurring transactions (runs daily at 3 AM)
Environment Configuration
Application Configuration (.env)
Download the environment template:
|
1 2 3 |
curl -o .env https://raw.githubusercontent.com/firefly-iii/firefly-iii/main/.env.example |
Critical Environment Variables
Basic Configuration
APP_ENV: Set to production for production use
APP_DEBUG: Set to false in production to hide debug information
APP_KEY: MUST be a random 32-character string. Generate one with:
|
1 2 3 |
head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32 && echo |
SITE_OWNER: Your email address for error notifications
APP_URL: The external URL where Firefly III will be accessible (e.g., http://localhost or https://firefly.yourdomain.com)
Localization Settings
DEFAULT_LANGUAGE: Interface language (default: en_US)
- Available languages: https://github.com/firefly-iii/firefly-iii/blob/main/config/firefly.php#L123
DEFAULT_LOCALE: Number formatting locale (default: equal – matches language)
TZ: Timezone for the application (e.g., Europe/Amsterdam, America/New_York)
- List of timezones: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
Database Configuration
DB_CONNECTION: Database type (mysql for MariaDB/MySQL, pgsql for PostgreSQL)
DB_HOST: Database hostname (use db for Docker Compose setup)
DB_PORT: Database port (3306 for MySQL/MariaDB, 5432 for PostgreSQL)
DB_DATABASE: Database name (default: firefly)
DB_USERNAME: Database user (default: firefly)
DB_PASSWORD: MUST MATCH the password in .db.env
DB_SOCKET: Leave empty unless using socket connections
MySQL SSL Configuration
MYSQL_USE_SSL: Enable SSL for MySQL connections (default: false)
MYSQL_SSL_VERIFY_SERVER_CERT: Verify server certificate (default: true)
MYSQL_SSL_CAPATH: Path to CA certificates (default: /etc/ssl/certs/)
MYSQL_SSL_CA: Path to CA certificate file
MYSQL_SSL_CERT: Path to client certificate
MYSQL_SSL_KEY: Path to client key
MYSQL_SSL_CIPHER: SSL cipher configuration
PostgreSQL SSL Configuration
PGSQL_SSL_MODE: SSL mode (disable, allow, prefer, require, verify-ca, verify-full)
PGSQL_SSL_ROOT_CERT: Root certificate path
PGSQL_SSL_CERT: Client certificate path
PGSQL_SSL_KEY: Client key path
PGSQL_SSL_CRL_FILE: Certificate revocation list file
PGSQL_SCHEMA: Database schema (default: public)
Caching and Sessions
CACHE_DRIVER: Cache storage driver
- Options: file, database, redis, memcached
- Default: file
SESSION_DRIVER: Session storage driver
- Options: file, cookie, database, redis
- Default: file
Redis Configuration (if using Redis)
REDIS_SCHEME: Connection scheme (tcp or unix)
REDIS_PATH: Unix socket path (only for unix scheme)
REDIS_HOST: Redis server host (default: 127.0.0.1)
REDIS_PORT: Redis server port (default: 6379)
REDIS_USERNAME: Redis ACL username (Redis 6+)
REDIS_PASSWORD: Redis authentication password
REDIS_DB: Redis database number for general use (default: “0”)
REDIS_CACHE_DB: Redis database number for cache (default: “1”)
Logging Configuration
LOG_CHANNEL: Log destination
- Options: stack, single, daily, syslog, errorlog, stdout, papertrail
- Default: stack (logs to both daily and stdout)
APP_LOG_LEVEL: Logging level
- Options: debug, info, notice, warning, error, critical, alert, emergency
- Default: notice
AUDIT_LOG_LEVEL: Audit log level for financial events
- Set to info to enable, emergency to disable
- Default: emergency
AUDIT_LOG_CHANNEL: Separate channel for audit logs
- Options: audit_stdout, audit_syslog, audit_errorlog, audit_daily, audit_papertrail
PAPERTRAIL_HOST: Papertrail host (if using papertrail logging)
PAPERTRAIL_PORT: Papertrail port
Email Configuration
MAIL_MAILER: Mail driver
- Options: smtp, sendmail, mailgun, ses, postmark, log
- Default: log
MAIL_HOST: SMTP server hostname
MAIL_PORT: SMTP server port (common: 25, 465, 587, 2525)
MAIL_FROM: From email address
MAIL_USERNAME: SMTP authentication username
MAIL_PASSWORD: SMTP authentication password
MAIL_ENCRYPTION: Encryption method (tls, ssl, or leave empty)
MAIL_SENDMAIL_COMMAND: Custom sendmail command (if using sendmail)
MAIL_ALLOW_SELF_SIGNED: Allow self-signed certificates (default: false)
MAIL_VERIFY_PEER: Verify SSL peer (default: true)
MAIL_VERIFY_PEER_NAME: Verify SSL peer name (default: true)
Third-Party Email Services
MAILGUN_DOMAIN: Mailgun domain
MAILGUN_SECRET: Mailgun API secret
MAILGUN_ENDPOINT: Mailgun API endpoint (api.mailgun.net or api.eu.mailgun.net for EU)
MANDRILL_SECRET: Mandrill API secret
SPARKPOST_SECRET: SparkPost API secret
MAILERSEND_API_KEY: MailerSend API key
Notification Settings
SEND_ERROR_MESSAGE: Send error notifications (default: true)
SEND_REPORT_JOURNALS: Send transaction reports (default: true)
External Services
ENABLE_EXTERNAL_MAP: Enable location mapping for transactions (default: false)
ENABLE_EXCHANGE_RATES: Enable currency exchange rates (default: false)
ENABLE_EXTERNAL_RATES: Download exchange rates from internet (default: false)
MAP_DEFAULT_LAT: Default map latitude (default: 51.983333)
MAP_DEFAULT_LONG: Default map longitude (default: 5.916667)
MAP_DEFAULT_ZOOM: Default map zoom level (default: 6)
URL Protocol Validation
VALID_URL_PROTOCOLS: Comma-separated list of allowed URL protocols
- Default: http,https,ftp,ftps,mailto
Authentication
AUTHENTICATION_GUARD: Authentication method
- Options: web (built-in database), remote_user_guard (for Authelia, etc.)
- Default: web
- Documentation: https://docs.firefly-iii.org/how-to/firefly-iii/advanced/authentication/
AUTHENTICATION_GUARD_HEADER: Header for remote user authentication (default: REMOTE_USER)
AUTHENTICATION_GUARD_EMAIL: Email header for remote authentication
OAuth and Security
PASSPORT_PRIVATE_KEY: Custom OAuth private key (optional)
PASSPORT_PUBLIC_KEY: Custom OAuth public key (optional)
CUSTOM_LOGOUT_URL: Custom logout redirect URL
DISABLE_FRAME_HEADER: Disable X-Frame-Options header (default: false)
DISABLE_CSP_HEADER: Disable Content Security Policy header (default: false)
Webhooks
ALLOW_WEBHOOKS: Enable webhook functionality (default: false)
- Security sensitive feature that must be manually enabled
Cron Job Configuration
STATIC_CRON_TOKEN: REQUIRED – 32-character token for cron job authentication
- Generate with: head /dev/urandom | LC_ALL=C tr -dc ‘A-Za-z0-9’ | head -c 32 && echo
- Used by the cron container to trigger scheduled tasks
- Documentation: https://docs.firefly-iii.org/how-to/firefly-iii/advanced/cron/
Trusted Proxies
TRUSTED_PROXIES: Configure when using reverse proxies
- Set to ** for Docker/reverse proxy setups
- Allows proper IP forwarding and HTTPS detection
Cookie Configuration
COOKIE_PATH: Cookie path (default: “/”)
COOKIE_DOMAIN: Cookie domain (leave empty for automatic)
COOKIE_SECURE: Require HTTPS for cookies (default: false)
COOKIE_SAMESITE: SameSite cookie attribute
- Options: lax, strict, none
- Default: lax
Analytics Tracking
TRACKER_SITE_ID: Matomo site ID (optional)
TRACKER_URL: Matomo tracker URL (optional)
Advanced Docker Options
DKR_CHECK_SQLITE: Check SQLite database on startup (default: true)
USE_RUNNING_BALANCE: Enable running balance calculations (default: false)
- Run php artisan firefly-iii:correct-database after enabling
FIREFLY_III_LAYOUT: UI layout version
- Options: v1 (stable), v2 (experimental)
- Default: v1
QUERY_PARSER_IMPLEMENTATION: Search engine parser
- Options: new (experimental), legacy (classic)
- Default: new
Database Configuration (.db.env)
Download and configure the database environment file:
|
1 2 3 |
curl -o .db.env https://raw.githubusercontent.com/firefly-iii/docker/main/database.env |
Database Environment Variables
MYSQL_RANDOM_ROOT_PASSWORD: Generate random root password (set to yes)
MYSQL_USER: Database user (must match DB_USERNAME in .env)
MYSQL_PASSWORD: Database password (must match DB_PASSWORD in .env)
MYSQL_DATABASE: Database name (must match DB_DATABASE in .env)
For PostgreSQL Users
If switching to PostgreSQL, change variables to:
POSTGRES_USER: PostgreSQL user
POSTGRES_PASSWORD: PostgreSQL password
POSTGRES_DB: PostgreSQL database name
Remove MYSQL_RANDOM_ROOT_PASSWORD when using PostgreSQL.
Switching to PostgreSQL
For Raspberry Pi or arm/v7 systems, PostgreSQL may be more reliable:
1. In .env, change:
|
1 2 3 4 5 |
DB_CONNECTION=pgsql DB_HOST=db DB_PORT=5432 |
2. In .db.env, rename variables from MYSQL_* to POSTGRES_* and remove MYSQL_RANDOM_ROOT_PASSWORD
3. In docker-compose.yml, change database image from mariadb:lts to postgres:latest
4. Change the database volume mount from /var/lib/mysql to /var/lib/postgresql/data
Installation Steps
Step 1: Configure Environment Files
1. Generate a 32-character APP_KEY:
|
1 2 3 |
head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32 && echo |
2. Edit .env and set:
- APP_KEY to your generated key
- DB_PASSWORD to a secure password
- STATIC_CRON_TOKEN to another 32-character random string
- APP_URL to your server’s URL
- TZ to your timezone
- Other settings as needed
3. Edit .db.env and set:
- MYSQL_PASSWORD to the SAME password as DB_PASSWORD in .env
Step 2: Start Firefly III
Run the following command in the directory containing your configuration files:
|
1 2 3 |
docker compose -f docker-compose.yml up -d --pull=always |
Step 3: Monitor Installation
Watch the installation progress:
|
1 2 3 |
docker compose -f docker-compose.yml logs -f |
Wait until you see a message thanking you for installing Firefly III.
Step 4: Access Firefly III
Open your browser and navigate to:
- Local access: http://localhost
- Remote access: http://your-server-ip:port
First-Time Setup
- Create your first user account when prompted
- Set up your financial accounts (checking, savings, credit cards)
- Configure your budget categories
- Set up recurring transactions
- Import existing transaction data if needed
Customizing Port Mapping
To run on a different port, edit the ports section in docker-compose.yml:
|
1 2 3 4 |
ports: - 8080:8080 # Change 8080 (left) to your desired port |
Data Persistence
Your data is stored in Docker volumes:
- firefly_iii_upload: Uploaded files and attachments
- firefly_iii_db: Database data
These volumes persist even when containers are removed.
Security Recommendations
- Always use strong, randomly generated passwords
- Change the default APP_KEY before first use
- Set APP_DEBUG=false in production
- Configure HTTPS when exposing to the internet (use a reverse proxy)
- Enable 2-factor authentication in Firefly III settings
- Regularly update containers with docker compose pull
- Restrict database access to the Firefly III container only
- Set TRUSTED_PROXIES=** if using a reverse proxy
Useful Resources
- Official Documentation: https://docs.firefly-iii.org
- GitHub Repository: https://github.com/firefly-iii/firefly-iii
- Docker Repository: https://github.com/firefly-iii/docker
- Community Support: https://github.com/firefly-iii/firefly-iii/discussions
- API Documentation: https://docs.firefly-iii.org/how-to/firefly-iii/features/api/
Thoughts
You now have a fully functional Firefly III installation running on your own server. The self-hosted nature ensures your financial data remains private and under your complete control. Take time to explore the features, set up your accounts, and start tracking your finances effectively.
Mobile Apps
FAQ
What is an open source personal finance manager?
An open source personal finance manager is free software that helps you track your income, expenses, budgets, and investments. The source code is publicly available, allowing anyone to use, modify, and distribute it. Popular options include Firefly III, GnuCash, Money Manager Ex, and Actual Budget. These tools give you complete control over your financial data without relying on cloud services or paying subscription fees.
Which open source personal finance app is best for beginners?
Money Manager Ex and HomeBank are excellent choices for beginners due to their simple, user-friendly interfaces. Both offer checkbook-style registers that are familiar to most users. Firefly III is also beginner-friendly with its modern interface, though it requires self-hosting. For those wanting a desktop application without complex setup, Money Manager Ex supports Windows, Mac, Linux, and Android.
How do I install an open source personal finance manager?
Installation methods vary by software. Desktop applications like GnuCash and Money Manager Ex can be downloaded and installed like any other program. Self-hosted options like Firefly III require Docker or web server setup. Here’s a basic Docker example for Firefly III:
Most projects provide detailed installation guides in their documentation.
Is my financial data safe with open source finance software?
Yes, open source finance software is generally very secure. Most applications store data locally on your computer or on servers you control (self-hosted). Many offer AES-256 encryption for data protection. Since the code is publicly reviewable, security vulnerabilities can be identified and fixed quickly by the community. Unlike proprietary services, your financial data never goes to third-party servers unless you explicitly choose to sync it.
Can I import my bank statements into open source finance apps?
Yes, most open source personal finance managers support importing bank statements in common formats including CSV, OFX, QIF, and QFX files. GnuCash, Firefly III, HomeBank, and Money Manager Ex all have robust import capabilities. Some applications like Actual Budget and Firefly III also support automatic bank synchronization through third-party services, though this requires additional setup and may have privacy implications.
What’s the difference between Firefly III and GnuCash?
Firefly III is a modern, self-hosted web application with a clean interface and REST API, ideal for those comfortable with Docker and web hosting. GnuCash is a traditional desktop application available since 1998, offering comprehensive double-entry accounting features suitable for personal and small business use. Firefly III is better for users wanting cloud-accessible, mobile-friendly finance tracking, while GnuCash excels for users preferring offline desktop software with extensive accounting features.
Do open source finance managers work on mobile devices?
Mobile support varies by application. Money Manager Ex has a native Android app with over 100,000 downloads. Firefly III can be accessed through mobile browsers and has unofficial mobile apps. GnuCash has limited mobile support. Actual Budget offers mobile-responsive web interface. For the best mobile experience, consider self-hosted web applications like Firefly III or dedicated mobile apps like Money Manager Ex Android.
What is double-entry bookkeeping and do I need it?
Double-entry bookkeeping is an accounting method where every transaction affects two accounts – one is debited and another is credited by the same amount. This ensures your books always balance. Applications like GnuCash, Firefly III, and KMyMoney use this system. While it provides more accurate tracking and is essential for small business accounting, beginners may find it complex. If you just want simple expense tracking, applications like Money Manager Ex offer simpler single-entry modes.
Can I use open source finance software for small business accounting?
Yes, several open source options support small business needs. GnuCash is designed for both personal and small business use, offering invoicing, accounts payable/receivable, tax tracking, and employee management. Akaunting is specifically built for small businesses and freelancers with invoicing, expense tracking, and bank integration. These applications support multiple currencies, tax calculations, and financial reporting required for business operations.
How do I create budgets in open source finance apps?
Budget creation varies by application. In Money Manager Ex, you set up annual or monthly budgets and compare spending against them through reports. Firefly III allows you to create budgets with limits in multiple currencies and tracks your progress with visual charts. Actual Budget uses zero-sum budgeting where every dollar is assigned a job. Most applications let you categorize transactions and set spending limits per category, then provide reports showing budget vs. actual spending.
What does self-hosted mean for personal finance software?
Self-hosted means you install and run the software on your own computer, server, or cloud instance rather than using a company’s servers. This gives you complete control over your financial data and privacy. Popular self-hosted options include Firefly III, Actual Budget, and Paisa. You can host on local servers, Raspberry Pi, cloud providers like AWS or DigitalOcean, or use simplified hosting services like PikaPods. Self-hosting requires some technical knowledge but ensures your data never leaves your control.
Are there open source alternatives to Mint and YNAB?
Yes, several open source alternatives exist. Firefly III, Actual Budget, and Financial Freedom are positioned as open source alternatives to Mint and YNAB. Actual Budget specifically uses zero-sum budgeting similar to YNAB’s envelope method. These alternatives offer similar features like transaction tracking, budgeting, reporting, and bank import capabilities, but without subscription fees or privacy concerns. They require self-hosting, which gives you complete data ownership.
Can I track investments and stocks with open source finance software?
Yes, several applications support investment tracking. GnuCash offers comprehensive investment management with portfolio tracking, capital gains calculations, and stock price updates. Paisa is specifically designed for tracking investments including mutual funds, stocks, and NPS funds with market price updates. Firefly III can track investment accounts and net worth across multiple asset types. These applications help you monitor investment performance, calculate returns, and generate reports for tax purposes.
How do I migrate from proprietary software to open source finance apps?
Most open source finance applications support importing data from proprietary software. GnuCash imports from Quicken (QIF) and Microsoft Money. HomeBank accepts files from Quicken, Microsoft Money, and other software formats. Skrooge can import from KMyMoney, Microsoft Money, GnuCash, Grisbi, HomeBank, and Money Manager Ex. The typical process involves exporting your data from the old software to CSV, QIF, or OFX format, then importing it into your chosen open source application. Most apps provide detailed migration guides in their documentation.
What operating systems support open source personal finance software?
Most open source finance applications are cross-platform. GnuCash, Money Manager Ex, HomeBank, KMyMoney, and Skrooge all support Windows, macOS, and Linux. Money Manager Ex also has an Android app. Web-based self-hosted solutions like Firefly III, Actual Budget, and Paisa work on any device with a web browser, including smartphones and tablets. This cross-platform support means you can manage your finances on your preferred device without being locked into a specific operating system.
How do I backup my financial data in open source apps?
Backup methods depend on the application type. Desktop applications like GnuCash and Money Manager Ex store data in portable files (SQLite, XML) that you can copy to external drives or cloud storage. Self-hosted web applications require backing up database files and configuration. Here’s an example for backing up a Docker container:
Regular backups are essential. Many users automate backups using cron jobs or backup scripts.
Can multiple users access the same personal finance database?
Yes, many applications support multi-user access. GnuCash allows multiple users to work with the same database when stored on a shared network location. Money Manager Ex supports synchronization for users working from different computers. Self-hosted web applications like Firefly III naturally support multiple users accessing the same installation simultaneously. Some applications offer user permissions, allowing you to control what different users can view or modify. This is useful for family finance management or small business accounting.
Do I need programming knowledge to use open source finance software?
No, programming knowledge is not required for desktop applications like GnuCash, Money Manager Ex, HomeBank, or KMyMoney. These work like any traditional software – just download, install, and use. Self-hosted options like Firefly III require basic familiarity with Docker or web servers for initial setup, but no programming skills. Once installed, they’re designed for non-technical users. If you want to customize or contribute to the software, programming knowledge helps, but it’s not necessary for everyday use.
What reports can I generate with open source finance applications?
Most open source finance apps offer comprehensive reporting capabilities. Common reports include income vs. expense summaries, spending by category, budget performance, net worth statements, cash flow analysis, and tax summaries. GnuCash provides professional accounting reports including balance sheets, profit and loss statements, and trial balances. Firefly III offers visual charts showing weekly, monthly, or yearly trends. Many applications allow custom report creation using SQL queries or built-in report builders, giving you flexibility to analyze your finances exactly how you need.
How do recurring transactions work in personal finance software?
Recurring transactions automate entry of regular expenses like rent, subscriptions, or salary. Most applications let you set up transactions to repeat daily, weekly, monthly, or yearly. You define the amount, category, and frequency, then the software automatically creates these transactions. Some apps like Firefly III allow setting end dates or limited occurrences. GnuCash and Money Manager Ex both support scheduled transactions with reminders. This feature saves time and ensures you don’t forget regular payments when managing your budget.
