Fava

Prerequisites

Before you deploy, make sure you have:

• An active Azure subscription
• An SSH key pair
• A VNet and subnet in the target region
• NSG inbound rules that allow 22/tcp from your management network, 80/tcp for the web UI, and 443/tcp if you add TLS

Standard_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting point, because Fava is light on resources. Fava serves plain HTTP on port 80. For production use, terminate TLS in front of it with your own domain and restrict access to trusted IP ranges (see Maintenance).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Fava by SecureAnyCloud, and select Create.

On Basics, pick your subscription, resource group, region and size. Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22) and HTTP (80). Then select Review + create and Create.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:fava-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name fava \
  --image sac1647283583153:fava-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard
az vm open-port --resource-group <your-rg> --name fava --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

systemctl is-active fava.service nginx.service

Both report active.

Fava serves its web interface on the loopback address 127.0.0.1:5000. nginx fronts it on port 80 and adds the per-VM HTTP Basic Auth gate. The application is never bound to a public interface, so nginx is the only way in.

Step 5 - Retrieve your web UI password

nginx protects the Fava UI with HTTP Basic Auth. The username is admin. A unique password is generated on the first boot of your VM and written to a root-only file:

sudo cat /root/fava-credentials.txt

This file contains FAVA_USERNAME, FAVA_PASSWORD and the FAVA_URL to open in a browser.

The password is stored on disk only as a bcrypt hash in /etc/nginx/.fava.htpasswd, so no plaintext password ships in the image. Store the password somewhere safe.

Step 6 - Confirm the health endpoint

nginx serves an unauthenticated health endpoint for load balancers and probes. Request it with:

curl -s http://localhost/healthz

It returns ok. This endpoint never requires authentication, so it is safe for an Azure Load Balancer health probe.

Step 7 - Confirm authentication

Because a password is set on first boot, an unauthenticated request to the UI returns HTTP 401, so nobody reaches Fava without the password.

The following commands read the per-VM password from the credentials file and prove the round trip. An unauthenticated request is rejected, a wrong password is rejected, and the correct password authenticates and reaches the ledger:

PW=$(sudo grep '^FAVA_PASSWORD=' /root/fava-credentials.txt | cut -d= -f2-)
echo "unauth : $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/)"
echo "wrongpw : $(curl -s -o /dev/null -w '%{http_code}' -u admin:wrong-pw http://127.0.0.1/)"
echo "authed : $(curl -s -L -o /dev/null -w '%{http_code}' -u admin:$PW http://127.0.0.1/)"

It prints unauth : 401, wrongpw : 401 and authed : 200. The whole UI is reachable only with the per-VM password, because Fava itself is bound to loopback and nginx is the only way in.

Step 8 - Explore the example ledger from the command line

Beancount ships bean-query, a command-line BQL client, in the same virtual environment as Fava. Run it against the bundled example ledger to see the data before you open the browser:

sudo -u fava /opt/fava/venv/bin/bean-query /opt/fava/ledger/example.beancount \
  "SELECT account, sum(position) AS balance WHERE account ~ 'Assets' GROUP BY account ORDER BY account"

It prints the balance of every asset account in the example ledger: a checking account, a savings account, a cash wallet and a brokerage account holding shares. The same numbers drive the Fava reports and charts in the browser.

Step 9 - Sign in and open the Balance Sheet

Browse to http://<vm-public-ip>/. Your browser prompts for a username and password. Enter admin and the password from Step 5. Fava opens on the example ledger.

Open Balance Sheet from the left navigation. It shows assets, liabilities and equity as an expandable account tree with a treemap chart, as of the latest date in the ledger.

Step 10 - Review the Income Statement

Open Income Statement from the left navigation. It summarizes income and expenses over the selected period. You get a bar chart of net income per month and an expandable breakdown of every income and expense account, including salary, rent, groceries, utilities and transport.

Step 11 - Read the Journal

Open Journal from the left navigation. It is Fava's interactive transaction list. It shows every posting in the ledger, with running balances, and you can filter by account, date range, tag or a full-text search. Use it to audit and drill into individual transactions.

Step 12 - Run a query in the BQL editor

Open Query from the left navigation to reach the Beancount Query Language editor. Type a query, for example SELECT account, sum(position) WHERE account ~ 'Expenses' GROUP BY account ORDER BY sum(position) DESC, and run it. You get a results table that you can sort and export.

This is the same query engine as bean-query from Step 8, in the browser.

Step 13 - Point Fava at your own ledger

The image ships a populated example ledger, so the dashboard has data from the start. When you are ready, copy your own Beancount file into place and restart Fava:

sudo install -o fava -g fava -m 0644 /path/to/your-ledger.beancount /opt/fava/ledger/example.beancount
sudo systemctl restart fava

Fava reloads the file automatically when it changes on disk, and the restart guarantees that it picks up a brand-new file.

Keep the path /opt/fava/ledger/example.beancount, because the fava.service unit points there. Alternatively, edit ExecStart in /etc/systemd/system/fava.service to reference a different filename, then run sudo systemctl daemon-reload.

Maintenance

• Password: the UI password is set on first boot and stored as a bcrypt entry in /etc/nginx/.fava.htpasswd. To change it, run sudo htpasswd -B /etc/nginx/.fava.htpasswd admin, then sudo systemctl reload nginx.
• Your ledger: replace /opt/fava/ledger/example.beancount with your own Beancount file (owned fava:fava), then run sudo systemctl restart fava. Before restarting, validate any ledger with sudo -u fava /opt/fava/venv/bin/bean-check /opt/fava/ledger/example.beancount.
• Read-only mode: Fava can edit the ledger and run arbitrary queries. If you only need reporting, add --read-only to ExecStart in /etc/systemd/system/fava.service. Then run sudo systemctl daemon-reload && sudo systemctl restart fava, so the UI cannot modify your books.
• Restrict access: Fava serves plain HTTP on port 80. For production, restrict access to trusted IP ranges in your Network Security Group. Also front it with TLS (for example certbot with your own domain) that terminates on :443.
• Loopback binding: Fava is bound to 127.0.0.1:5000 in /etc/systemd/system/fava.service, so nginx is the only path in. Keep it that way, and do not change the listen address to a public interface.
• Upgrades: upgrade Fava in its virtual environment with sudo /opt/fava/venv/bin/pip install --upgrade fava, then run sudo systemctl restart fava.
• Security patches: unattended-upgrades remains enabled, so the OS keeps receiving security updates automatically.

Support

SecureAnyCloud provides 24/7 expert support for this image. Contact sales@secureanycloud.com.

Deploy on Azure

Launch Fava for Beancount on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com