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.

Frequently Asked Questions

What is plain-text accounting?

Plain-text accounting means your financial data lives in a human-readable text file — not a database or proprietary format. Each transaction is a few lines of text following Beancount’s syntax. You edit the file with any text editor, version-control it with git, grep it with standard tools, and your data is never locked into any application.

How does Fava relate to Beancount?

Beancount is the plain-text accounting system — a Python library and command-line tool that parses your .beancount files and generates reports. Fava is a separate web interface that reads those same files and presents them as interactive dashboards, charts, and filterable transaction lists. Fava needs Beancount, but Beancount works without Fava (via CLI reports).

Can I import bank statements into Beancount?

Yes, but not automatically. Use tools like smart_importer, beancount-import, or bean-extract with custom importers to convert CSV/OFX bank exports into Beancount format. The process is semi-manual: download your statement, run the importer, review the output, and paste it into your file. There’s no live bank connection like Firefly III or Actual Budget.

Is Beancount good for tracking investments?

Excellent. Beancount handles investment tracking with cost basis, lot identification, capital gains calculation, and multi-currency portfolios natively. Its balance directive catches accounting errors automatically. For a dedicated investment dashboard on top of Beancount data, pair Fava with the fava-investor plugin.

Can multiple people use the same Beancount file?

The file is just text — multiple people can edit it and merge changes via git. Fava serves a web UI that anyone on the network can access (add authentication via reverse proxy). However, concurrent editing requires git discipline to avoid merge conflicts. For family finances with separate editors, consider splitting into multiple files with Beancount’s include directive.

How steep is the Beancount learning curve?

Steeper than GUI-based tools. You need to understand double-entry accounting basics (every transaction has balanced debits and credits), learn Beancount’s syntax, and be comfortable editing text files. Plan for a weekend to get through the basics and a month of daily use to feel fluent. The payoff is complete transparency — you understand exactly what every number means because you entered it yourself.

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