# Firefly III — Self-Hosted Personal Finance Manager

> Firefly III is an open-source personal finance manager for tracking expenses, budgets, and bank accounts. Self-hosted with full privacy, multi-currency, and powerful reporting.

## Install

Save as a script file and run:

## Quick Use

```bash
docker run -d --name firefly 
  -p 8080:8080 
  -e APP_KEY=SomeRandomStringOf32Characters!! 
  -e DB_CONNECTION=sqlite 
  -v firefly-data:/var/www/html/storage 
  fireflyiii/core:latest
```

Open `http://localhost:8080` — register your account and start tracking finances.

## Intro

**Firefly III** is a self-hosted personal finances manager that helps you track expenses, income, budgets, and financial goals. Built with PHP (Laravel), it provides comprehensive financial management with multi-currency support, bank import, automation rules, and detailed reports — all while keeping your financial data completely private.

With 22.9K+ GitHub stars and AGPL-3.0 license, Firefly III is one of the most feature-rich open-source personal finance tools, used by thousands of users worldwide who want complete control over their financial data.

## What Firefly III Does

- **Transaction Tracking**: Record expenses, income, and transfers between accounts
- **Budgeting**: Set monthly/weekly budgets per category and track spending progress
- **Account Management**: Multiple bank accounts, credit cards, savings, and cash wallets
- **Multi-Currency**: Full multi-currency support with automatic exchange rates
- **Bank Import**: Import transactions from CSV, OFX, QIF, CAMT.053, and via Spectre/GoCardless
- **Categories & Tags**: Organize transactions with categories, tags, and custom groups
- **Rules Engine**: Auto-categorize, auto-tag, and auto-process transactions based on rules
- **Reports**: Spending reports, income vs expense, net worth, budget performance
- **Recurring Transactions**: Automatic creation of recurring bills and income
- **Piggy Banks**: Virtual savings goals with progress tracking
- **Bills**: Track recurring expenses and see upcoming payments

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Web UI      │────▶│  Firefly III │────▶│  MySQL /     │
│  (Blade/JS)  │     │  (Laravel)   │     │  PostgreSQL /│
└──────────────┘     └──────────────┘     │  SQLite      │
                                          └──────────────┘
```

## Self-Hosting

### Docker Compose

```yaml
services:
  firefly:
    image: fireflyiii/core:latest
    ports:
      - "8080:8080"
    environment:
      APP_KEY: your-32-character-app-key-here!
      DB_CONNECTION: pgsql
      DB_HOST: db
      DB_PORT: 5432
      DB_DATABASE: firefly
      DB_USERNAME: firefly
      DB_PASSWORD: firefly
      TZ: Asia/Shanghai
      DEFAULT_LANGUAGE: zh_CN
      DEFAULT_LOCALE: equal
    depends_on:
      - db
    volumes:
      - firefly-upload:/var/www/html/storage/upload

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: firefly
      POSTGRES_PASSWORD: firefly
      POSTGRES_DB: firefly
    volumes:
      - pg-data:/var/lib/postgresql/data

  # Optional: automated bank import
  importer:
    image: fireflyiii/data-importer:latest
    ports:
      - "8081:8080"
    environment:
      FIREFLY_III_URL: http://firefly:8080
      FIREFLY_III_ACCESS_TOKEN: your-personal-access-token

volumes:
  firefly-upload:
  pg-data:
```

## Key Features

### Transaction Types

```
Withdrawal:  💸 Spending money (expenses)
Deposit:     💰 Receiving money (income)
Transfer:    🔄 Moving between own accounts

Example:
├── Withdrawal: Grocery store → $85.50 (Category: Food)
├── Withdrawal: Netflix → $15.99 (Category: Entertainment)
├── Deposit: Salary → $5,000 (Category: Income)
└── Transfer: Checking → Savings → $500
```

### Budget System

```
Monthly Budget: $3,000
├── Food & Groceries: $600 [$420 spent, $180 remaining]
│   ██████████████░░░░░░ 70%
├── Transportation: $200 [$180 spent, $20 remaining]
│   ██████████████████░░ 90%
├── Entertainment: $150 [$75 spent, $75 remaining]
│   ██████████░░░░░░░░░░ 50%
└── Utilities: $300 [$285 spent, $15 remaining]
    ███████████████████░ 95%
```

### Automation Rules

```
Rule: "Auto-tag grocery purchases"
  When: Description contains "Walmart" OR "Costco" OR "Whole Foods"
  Then:
    → Set category to "Groceries"
    → Add tag "Supermarket"
    → Set budget to "Food"

Rule: "Flag large purchases"
  When: Amount > $500
  Then:
    → Add tag "Large Purchase"
    → Add note "Review this transaction"
```

### Reports

Available reports:
- **Budget**: Monthly budget performance with overspend alerts
- **Category**: Spending breakdown by category with trends
- **Tag**: Tag-based analysis and comparison
- **Net Worth**: Assets minus liabilities over time
- **Income vs Expense**: Monthly comparison chart
- **Audit**: Transaction audit log per account

### API

```bash
# List transactions
curl http://localhost:8080/api/v1/transactions 
  -H "Authorization: Bearer YOUR_TOKEN"

# Create transaction
curl -X POST http://localhost:8080/api/v1/transactions 
  -H "Authorization: Bearer YOUR_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"transactions": [{"type": "withdrawal", "date": "2024-04-10", "amount": "25.50", "description": "Coffee shop", "source_id": "1", "category_name": "Food"}]}'
```

## Firefly III vs Alternatives

| Feature | Firefly III | Actual Budget | YNAB | GnuCash |
|---------|------------|---------------|------|---------|
| Open Source | Yes (AGPL-3.0) | Yes (MIT) | No | Yes (GPL) |
| Approach | Transaction tracking | Envelope budget | Envelope budget | Double-entry |
| Multi-currency | Yes | Limited | Yes | Yes |
| Bank import | CSV + API | GoCardless | Plaid | OFX/QIF |
| Rules engine | Yes | Basic | No | No |
| Reports | Extensive | Basic | Basic | Extensive |
| Stack | PHP (Laravel) | Node.js | SaaS | C++ |

## FAQ

**Q: Should I pick Firefly III or Actual Budget?**
A: Firefly III focuses on comprehensive transaction records and report analysis — ideal for users who want to track every inflow and outflow in detail. Actual Budget centers on envelope budgeting — ideal for users who want strict budget control. Pick Firefly III for bookkeeping, Actual Budget for budgeting.

**Q: Does it support a Chinese UI?**
A: Yes. Set `DEFAULT_LANGUAGE=zh_CN` for a Simplified Chinese interface. All reports and UI elements are fully translated.

**Q: Can I automatically import bank transactions?**
A: The Data Importer tool can connect to the Nordigen (GoCardless) API to auto-import transactions from European and US banks. For Chinese banks you need to manually export CSV and import. You can also write custom import scripts via the API.

## Sources & Credits

- GitHub: [firefly-iii/firefly-iii](https://github.com/firefly-iii/firefly-iii) — 22.9K+ ⭐ | AGPL-3.0
- Website: [firefly-iii.org](https://firefly-iii.org)

---
Source: https://tokrepo.com/en/workflows/de4aaf47-34b7-11f1-9bc6-00163e2b0d79
Author: Script Depot