# Firefly III Personal Finance

> Firefly III personal finance manager for budgeting and expense tracking.

- Category: Productivity & Collaboration
- Difficulty: intermediate
- Components: firefly, postgres
- Tags: firefly, finance, budgeting, expenses, money-management
- Source: https://docker.recipes/productivity/firefly-finance

## 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.

## 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

## Use cases

- Personal budget management for individuals tracking monthly expenses across multiple bank accounts
- Household financial planning for families managing shared expenses, allowances, and savings goals
- Freelancer expense tracking separating business costs from personal spending for tax purposes
- Investment portfolio monitoring combining brokerage accounts with cash flow management
- Debt payoff planning with multiple loan tracking and payment schedule optimization
- Small business owners managing personal finances separately from business accounting systems
- Privacy-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

## docker-compose.yml

```yaml
services:
  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:
    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

volumes:
  firefly_upload:
  postgres_data:

networks:
  firefly-network:
    driver: bridge
```

## .env

```bash
# Firefly III
APP_KEY=SomeRandomString32CharsExactly!
POSTGRES_USER=firefly
POSTGRES_PASSWORD=firefly_password
APP_URL=http://localhost:8080
TZ=UTC
```

## Usage notes

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

## 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

