How to Self-Host Fava (Beancount) with Docker

What Is Fava?

Fava is a web interface for Beancount, a plain-text double-entry accounting system. Instead of a database, your financial data lives in a .beancount text file — version-controllable, auditable, and impossible to lose to vendor lock-in. Fava adds a web UI with dashboards, balance sheets, income statements, and interactive charts on top of Beancount’s text-file engine. It replaces Quicken, YNAB, or Mint for users who want full control over their financial data.

Official site: beancount.github.io/fava/

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 256 MB of free RAM (minimum)
• Basic understanding of double-entry accounting concepts

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  fava:
    image: yegle/fava:v1.30
    container_name: fava
    restart: unless-stopped
    ports:
      - "5000:5000"
    volumes:
      - ./beancount:/bean
    environment:
      BEANCOUNT_FILE: /bean/main.beancount
    networks:
      - fava

networks:
  fava:

Create the beancount directory and a starter file:

mkdir -p beancount

cat > beancount/main.beancount << 'EOF'
option "title" "My Finances"
option "operating_currency" "USD"

2026-01-01 open Assets:Bank:Checking
2026-01-01 open Assets:Bank:Savings
2026-01-01 open Expenses:Groceries
2026-01-01 open Expenses:Rent
2026-01-01 open Income:Salary
2026-01-01 open Equity:Opening-Balances

2026-01-01 * "Opening balance"
  Assets:Bank:Checking  5000.00 USD
  Equity:Opening-Balances

2026-01-15 * "Employer" "Monthly salary"
  Assets:Bank:Checking  4500.00 USD
  Income:Salary
EOF

Start the stack:

docker compose up -d

Initial Setup

1. Open http://your-server-ip:5000 in your browser
2. Fava loads the beancount file specified in BEANCOUNT_FILE
3. The web interface immediately shows your accounts, balances, and transactions
4. No database, no wizard, no account creation — everything comes from the text file

Configuration

Fava reads all configuration from the beancount file itself. Add these options to main.beancount:

; Fava-specific options
2026-01-01 custom "fava-option" "language" "en"
2026-01-01 custom "fava-option" "default-page" "income_statement"
2026-01-01 custom "fava-option" "currency-column" "80"
2026-01-01 custom "fava-option" "indent" "2"

Option	What It Does
language	UI language (en, de, es, fr, zh, and more)
default-page	Landing page after login
currency-column	Column alignment for amounts in the text file
indent	Indentation width for transaction entries

Multi-File Setup

For larger accounting systems, split into multiple files:

; main.beancount
include "accounts.beancount"
include "2026-transactions.beancount"
include "prices.beancount"

Authentication

Fava has no built-in authentication. For remote access, protect it with:

• A reverse proxy with HTTP basic auth
• Authelia or Authentik for SSO
• Restrict access to VPN only (Tailscale or WireGuard)

Reverse Proxy

Example Nginx Proxy Manager configuration:

Field	Value
Domain	finance.yourdomain.com
Scheme	http
Forward Host	fava
Forward Port	5000
SSL	Request a new certificate

Add HTTP basic auth or an auth proxy — Fava has no login screen.

For more options: Reverse Proxy Setup

Backup

Your entire financial history is a text file:

# Back up the beancount directory
cp -r beancount/ beancount-backup-$(date +%Y%m%d)/

Since beancount files are plain text, they work perfectly with git:

cd beancount/
git init
git add .
git commit -m "Financial snapshot $(date +%Y-%m-%d)"

This gives you full version history of every financial change. For automated backups: Backup Strategy

Troubleshooting

Fava Shows “No beancount file found”

Symptom: Blank page or error on startup.

Fix: Verify BEANCOUNT_FILE points to an existing file inside the container. The volume mount maps ./beancount to /bean, so the file should be at /bean/main.beancount.

Syntax Errors in Beancount File

Symptom: Red error bar at the top of the Fava UI showing parse errors.

Fix: Beancount is strict about formatting. Common issues:

• Accounts must be opened before use (open directive)
• Transactions must balance exactly (both sides must sum to zero)
• Dates use YYYY-MM-DD format
• Account names use Title:Case:Colon:Separated format

Container Exits Immediately

Symptom: Container starts and stops within seconds.

Fix: Check that the beancount file exists and has valid syntax:

docker logs fava

The log will show the specific parsing error. Fix the .beancount file and restart.

Resource Requirements

Resource	Usage
RAM	~50-100 MB
CPU	Very low
Disk	Negligible (text files only)

Fava is one of the lightest finance apps you can self-host. A decade of personal finances fits in a few megabytes.

Verdict

Fava with Beancount is the most developer-friendly personal finance tool available. Plain-text accounting means your data is truly portable — no database exports, no proprietary formats, no vendor lock-in. The learning curve is steeper than Actual Budget or Firefly III, but the payoff is complete transparency and git-level version control over your finances. Choose Fava if you value data ownership above convenience. Choose Actual Budget if you want an easier envelope-based budgeting experience.

Related

• Firefly III: Full-Featured Budget App
• Actual Budget: Envelope Budgeting
• Ghostfolio: Investment Tracking
• Firefly III vs Beancount
• Best Self-Hosted Budget Apps
• Self-Hosted YNAB Alternatives
• Self-Hosted Quicken Alternatives
• Docker Compose Basics
• Reverse Proxy Setup