Files
Spendr/README.md
T
2026-11-17 21:48:36 +01:00

6.9 KiB
Raw Blame History

Finance: a self-hosted dashboard for ING, Revolut, investments, gold and debts

browser ──https──▶ Traefik ──forward-auth──▶ authentik (login, MFA)
                      │
                      └──▶ finance (FastAPI) ──▶ Postgres
                                 │
                                 ├─ Yahoo Finance  (stocks/ETFs, gold spot, FX)
                                 ├─ CoinGecko      (crypto)
                                 └─ Enable Banking (optional automatic ING/Revolut sync)

What it does

Feature How
Categories ~200 seed rules for Dutch merchants (AH, Jumbo, NS, Ziggo, Vattenfall, CZ, Belastingdienst…). Fix one in the table and it gets a 🔒 lock. Click +rule to turn a fix into a rule. Moves between your own IBANs are auto-tagged Transfers and left out of spending.
Subscriptions / monthly costs Detects weekly, monthly, quarterly and yearly payments from regular gaps and similar amounts (price increases are tolerated). You can confirm, ignore, or add an item by hand (rent, salary, yearly insurance).
Missed payment alert A recurring item whose next date + grace period (6 days for monthly) has passed shows as missed on the dashboard.
Investments You log buys and sells; cost is tracked with the average-cost method. Shows value vs paid, unrealised and realised P/L, allocation, and history. Stocks/ETFs use Yahoo tickers (VWRL.AS, IWDA.AS, ASML.AS), crypto uses CoinGecko ids (bitcoin). Everything is in EUR.
Gold Grams or troy oz × purity (24k, 22k Krugerrand, 18k jewellery…) × spot (COMEX GC=F → EUR). A manual price override is available for dealer buyback prices. Silver works too: use symbol SI=F.
Debts Covers both directions (what you owe and what you're owed). With a monthly amount and due day set, it shows on track / ahead / behind (n missed), the next due date and an estimated payoff date. Payments are matched from bank transactions automatically by a text pattern, or you can add them by hand.
Joint account Give the ING shared account a "your share %" (e.g. 50) and its spending is scaled in the totals.
Live numbers Every 30 s (and whenever you come back to the tab) the page fetches /api/live. Changed totals, prices and P/L count up or down and flash green or red, with no reload. Refresh prices runs in place. When new transactions arrive, a "new data · reload" hint appears so charts can be redrawn.
Dark mode Auto (follows the system), Light or Dark toggle in the sidebar, remembered per browser.
Mobile Desktop-first layout. On phones the sidebar turns into a scrolling top bar and tables scroll sideways.

Setup

  1. DNS: point finance.home.lan and auth.home.lan (or your own names) at the Docker host, e.g. in Pi-hole, AdGuard or your router.
  2. Configure
    cp .env.example .env
    # fill in hostnames + three secrets:  openssl rand -base64 48 | tr -d '\n'
    mkdir -p authentik/data authentik/certs authentik/custom-templates secrets
    docker compose up -d --build
    
  3. authentik first run: open https://auth.home.lan/if/flow/initial-setup/ and create the admin user. Turn on TOTP or a passkey for it, because this app holds your bank data.
  4. Protect the app in authentik (Admin → Applications → Create with provider):
    • Provider type: Proxy Provider → Forward auth (single application)
    • External host: https://finance.home.lan
    • Then go to Outposts → authentik Embedded Outpost → edit and add the application.
    • Optional: bind a policy or group so only you (and your partner, if you like) can open it.
  5. Open https://finance.home.lan. You should be sent to the authentik login and then back to the app.

TLS

By default Traefik serves a self-signed certificate, so the browser shows a warning. You have two options:

  • mkcert (LAN only): mkcert "*.home.lan", save the files as traefik/certs/local.crt / local.key, then uncomment traefik/dynamic/tls.yml.
  • Let's Encrypt DNS challenge (if you own a domain): uncomment the resolver in traefik/traefik.yml and set CF_DNS_API_TOKEN (or use another provider). This works even when the hosts are only reachable on your LAN.

Getting data in

CSV (always works). Use Import and select several files at once. Overlapping periods are deduplicated.

  • ING: Mijn ING → Af- en bijschrijvingen downloaden → CSV (comma or semicolon, NL or EN headers). The account is detected from the IBAN in the file.
  • Revolut: app → ⋯ → Statement → CSV. Only completed transactions from the Current account are imported.

First go to Settings → Accounts and add the IBANs of all three accounts (Revolut's too). Transfers between them are then recognised, and the shared account gets its share %.

Automatic sync (Enable Banking, free for your own accounts):

  1. Sign up at enablebanking.com → Applications → create one (Production). Set the redirect URL to https://finance.home.lan/eb/callback.
  2. Save the downloaded private key as secrets/enablebanking.pem and put the app id in .env → EB_APP_ID.
  3. In their control panel, use Link accounts for ING and Revolut. Free "restricted mode" only returns accounts you linked there.
  4. docker compose up -d, then go to Settings → Connect (ING / NL, then Revolut; Revolut may be listed under LT).
  5. The app syncs every EB_SYNC_HOURS. Bank consent (PSD2) expires after 90–180 days, so you'll need to click Connect again now and then. The expiry date is shown in Settings.

CSV and API imports share the same dedupe key (account + date + amount + n-th of that day), so you can mix them.

Operations

  • Backup: docker compose exec finance-db pg_dump -U finance finance | gzip > finance-$(date +%F).sql.gz. Back up authentik-db the same way.
  • Logs: docker compose logs -f finance
  • Not exposed: the app has no published port. It is only reachable through Traefik and authentik. Keep it that way.
  • Prices refresh every PRICE_REFRESH_MINUTES. Yahoo's endpoint is unofficial. If a ticker fails, the holding shows "price error" and you can set a manual price.
  • The schema is created on start (create_all). Add Alembic if you start changing models.

UI

  • Icons are Lucide (ISC licence), stored inside the app as an SVG sprite (templates/_icons.svg), so no CDN is needed.
  • Charts use Chart.js and have hover tooltips: savings rate per month, and P/L at each point on the value line.
    • Click a bar to open that month, or a doughnut slice to see its transactions.
    • Click legend entries to hide or show them.
    • Range buttons (1M–All) on the history charts.
  • On phones: bottom tab bar plus a slide-out menu.

Ideas for later

Budgets per category, splitting shared-house costs with your partner, DEGIRO/Bitvavo CSV import for trades, ntfy/Telegram push for missed payments, salary-missed alerts.