docker.recipes

Firefly III Personal Finance

intermediate

Firefly III personal finance manager for budgeting and expense tracking.

Overview

Firefly III is a free, self-hosted personal finance manager that helps individuals and households track expenses, manage budgets, and gain insights into their financial habits. Originally created by James Cole in 2017, Firefly III has grown into a comprehensive financial management platform that supports multiple account types, transaction categorization, bill tracking, and detailed reporting. Built with PHP and Laravel, it offers a modern web interface that makes personal finance management accessible without relying on cloud-based services or sharing sensitive financial data with third parties. This stack combines Firefly III with PostgreSQL to create a robust personal finance platform that handles complex financial relationships and data integrity requirements. PostgreSQL's advanced transaction support ensures financial data remains consistent, while its JSON capabilities allow Firefly III to store flexible metadata about transactions, rules, and user preferences. The combination provides ACID compliance for financial records, ensuring that double-entry bookkeeping principles are maintained even during system failures or concurrent operations. Individuals seeking financial independence, small business owners managing personal and business expenses, and privacy-conscious users who want complete control over their financial data will find this stack valuable. The PostgreSQL backend enables complex financial queries for trend analysis, budget variance reports, and multi-currency calculations, while Firefly III's rule engine can automatically categorize transactions and apply tags based on sophisticated criteria that leverage PostgreSQL's pattern matching and full-text search capabilities.

Key Features

  • Double-entry bookkeeping system with PostgreSQL ACID compliance ensuring transaction integrity
  • Multi-currency support with automatic exchange rate fetching and currency conversion tracking
  • Advanced rule engine for automatic transaction categorization using PostgreSQL pattern matching
  • Budget tracking with variance analysis and spending trend visualization over time periods
  • Bill and subscription management with automatic matching against imported transactions
  • Piggy bank savings goals with progress tracking and automatic transfer scheduling
  • Comprehensive reporting including net worth calculations, category spending, and account balance histories
  • Bank import capabilities supporting CSV, OFX, and direct bank connections through data importer

Common Use Cases

  • 1Personal budget management for individuals tracking monthly expenses across multiple bank accounts
  • 2Household financial planning for families managing shared expenses, allowances, and savings goals
  • 3Freelancer expense tracking separating business costs from personal spending for tax purposes
  • 4Investment portfolio monitoring combining brokerage accounts with cash flow management
  • 5Debt payoff planning with multiple loan tracking and payment schedule optimization
  • 6Small business owners managing personal finances separately from business accounting systems
  • 7Privacy-focused users wanting complete control over financial data without cloud service dependencies

Prerequisites

  • Minimum 1GB RAM recommended for PostgreSQL database operations and financial calculations
  • Port 8080 available for Firefly III web interface access
  • Basic understanding of personal finance concepts like double-entry bookkeeping and account types
  • APP_KEY generation capability using system tools or online generators for Laravel encryption
  • Access to bank export files (CSV, OFX) or willingness to manually enter initial transaction data
  • Docker Compose v2+ for proper dependency handling between Firefly III and PostgreSQL services

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  firefly: 
3    image: fireflyiii/core:latest
4    container_name: firefly
5    environment: 
6      - APP_ENV=production
7      - APP_KEY=${APP_KEY}
8      - DB_CONNECTION=pgsql
9      - DB_HOST=postgres
10      - DB_PORT=5432
11      - DB_DATABASE=firefly
12      - DB_USERNAME=${POSTGRES_USER}
13      - DB_PASSWORD=${POSTGRES_PASSWORD}
14      - TRUSTED_PROXIES=**
15      - APP_URL=${APP_URL}
16      - TZ=${TZ}
17    volumes: 
18      - firefly_upload:/var/www/html/storage/upload
19    ports: 
20      - "8080:8080"
21    depends_on: 
22      - postgres
23    networks: 
24      - firefly-network
25
26  postgres: 
27    image: postgres:16-alpine
28    container_name: firefly-db
29    environment: 
30      - POSTGRES_USER=${POSTGRES_USER}
31      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
32      - POSTGRES_DB=firefly
33    volumes: 
34      - postgres_data:/var/lib/postgresql/data
35    networks: 
36      - firefly-network
37
38volumes: 
39  firefly_upload: 
40  postgres_data: 
41
42networks: 
43  firefly-network: 
44    driver: bridge

.env Template

.env
1# Firefly III
2APP_KEY=SomeRandomString32CharsExactly!
3POSTGRES_USER=firefly
4POSTGRES_PASSWORD=firefly_password
5APP_URL=http://localhost:8080
6TZ=UTC

Usage Notes

  1. 1UI at http://localhost:8080
  2. 2Generate APP_KEY with: head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32
  3. 3Register account on first visit
  4. 4Bank import via data importer
  5. 5Supports budgets, categories, tags

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

firefly
firefly:
  image: fireflyiii/core:latest
  container_name: firefly
  environment:
    - APP_ENV=production
    - APP_KEY=${APP_KEY}
    - DB_CONNECTION=pgsql
    - DB_HOST=postgres
    - DB_PORT=5432
    - DB_DATABASE=firefly
    - DB_USERNAME=${POSTGRES_USER}
    - DB_PASSWORD=${POSTGRES_PASSWORD}
    - TRUSTED_PROXIES=**
    - APP_URL=${APP_URL}
    - TZ=${TZ}
  volumes:
    - firefly_upload:/var/www/html/storage/upload
  ports:
    - "8080:8080"
  depends_on:
    - postgres
  networks:
    - firefly-network
postgres
postgres:
  image: postgres:16-alpine
  container_name: firefly-db
  environment:
    - POSTGRES_USER=${POSTGRES_USER}
    - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    - POSTGRES_DB=firefly
  volumes:
    - postgres_data:/var/lib/postgresql/data
  networks:
    - firefly-network

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  firefly:
5    image: fireflyiii/core:latest
6    container_name: firefly
7    environment:
8      - APP_ENV=production
9      - APP_KEY=${APP_KEY}
10      - DB_CONNECTION=pgsql
11      - DB_HOST=postgres
12      - DB_PORT=5432
13      - DB_DATABASE=firefly
14      - DB_USERNAME=${POSTGRES_USER}
15      - DB_PASSWORD=${POSTGRES_PASSWORD}
16      - TRUSTED_PROXIES=**
17      - APP_URL=${APP_URL}
18      - TZ=${TZ}
19    volumes:
20      - firefly_upload:/var/www/html/storage/upload
21    ports:
22      - "8080:8080"
23    depends_on:
24      - postgres
25    networks:
26      - firefly-network
27
28  postgres:
29    image: postgres:16-alpine
30    container_name: firefly-db
31    environment:
32      - POSTGRES_USER=${POSTGRES_USER}
33      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
34      - POSTGRES_DB=firefly
35    volumes:
36      - postgres_data:/var/lib/postgresql/data
37    networks:
38      - firefly-network
39
40volumes:
41  firefly_upload:
42  postgres_data:
43
44networks:
45  firefly-network:
46    driver: bridge
47EOF
48
49# 2. Create the .env file
50cat > .env << 'EOF'
51# Firefly III
52APP_KEY=SomeRandomString32CharsExactly!
53POSTGRES_USER=firefly
54POSTGRES_PASSWORD=firefly_password
55APP_URL=http://localhost:8080
56TZ=UTC
57EOF
58
59# 3. Start the services
60docker compose up -d
61
62# 4. View logs
63docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/firefly-finance/run | bash

Troubleshooting

  • Error 500 on first access: Generate proper APP_KEY using 'head /dev/urandom | LC_ALL=C tr -dc A-Za-z0-9 | head -c 32' and restart containers
  • Database connection failed: Verify POSTGRES_USER and POSTGRES_PASSWORD environment variables match between services
  • Transaction import fails with encoding errors: Ensure CSV files use UTF-8 encoding and verify column mapping in import wizard
  • Currency exchange rates not updating: Check internet connectivity from container and verify Firefly III has access to fixer.io API
  • Duplicate transactions appearing: Configure transaction matching rules properly and check for overlapping import date ranges
  • Slow performance during large imports: Increase PostgreSQL shared_buffers and work_mem settings, or import data in smaller batches

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

fireflypostgres

Tags

#firefly#finance#budgeting#expenses#money-management

Category

Productivity & Collaboration

Related Recipes

Ad Space