First commit
This commit is contained in:
@@ -1,2 +1,85 @@
|
||||
# Spendr
|
||||
# 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**
|
||||
```bash
|
||||
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](https://lucide.dev) (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.
|
||||
|
||||
Reference in New Issue
Block a user