Files
brokeless/README.md
T

140 lines
6.2 KiB
Markdown
Raw Normal View History

# brokeless
See where your money goes, get a plan for it, and ask a local AI about it. Everything runs on your own server: the app, the database, sign-in and the AI. Nothing goes to the cloud.
brokeless is a self-hosted copy of [broke](https://github.com/nextwork-projects/broke) by NextWork (MIT). It keeps broke's features and adds a complete Docker setup, Dutch bank import and a few fixes. New broke changes are reviewed by hand before they come in.
## What's different from broke
| | broke | brokeless |
| --- | --- | --- |
| Database and sign-in | Supabase cloud project | Supabase's own Postgres, Auth and REST images, in Docker on your server |
| Sign-in emails | Supabase sends them | Mailpit catches them on your server, or your own mail server |
| Hosting | Your computer, or Vercel | Docker, for example on Unraid |
| AI | Your Claude/Codex/Gemini login, OpenRouter, or a local model | Ollama in the same Docker setup (the others still work if you want them) |
| Banks | Plaid and other cloud bank feeds | Statement import (CSV, OFX, QIF, PDF). Bank feeds still work if you add keys. |
| ING Netherlands CSV | Spending and income all came in as income | Reads the "Af Bij" column |
| Updates | Pulls from GitHub on every start | Never by itself. You review upstream commits and merge the ones you want. |
| Calls out | Update check on GitHub, exchange rates from frankfurter.dev | Both off (`BROKE_OFFLINE=1`) |
| Next.js and React | 15.5.4 and 19.1.0 (critical advisory) | 15.5.29 and 19.1.10 |
Also fixed: sign-in links sent you to `http://0.0.0.0:3000` behind Docker or a proxy. Redirects now use the address your browser used.
## Run it
Needs Docker with Compose. The steps below use Unraid's IP as the example, but any Linux server works.
1. Get the code on your server:
```bash
git clone https://mangavalk.com/mangavalk/brokeless.git
```
2. Make the secrets. Use the address you'll open brokeless on, with your server's LAN IP or name (not `localhost`: the containers need to reach it too):
```bash
cd brokeless && node docker/setup.mjs --url http://192.168.1.10:3000
```
No Node on the server:
```bash
docker run --rm -v "$PWD":/w -w /w node:22-alpine node docker/setup.mjs --url http://192.168.1.10:3000
```
This writes `docker/.env` with a new database password, signing keys and a Mailpit password. On Unraid, set `DATA_DIR=/mnt/user/appdata/brokeless` in it.
3. Start it, with local AI:
```bash
docker compose -f docker/docker-compose.yml --profile ai up -d --build
```
Then pull a model for Ollama (pick one that fits your RAM or GPU):
```bash
docker exec brokeless-ollama-1 ollama pull qwen3:8b
```
Leave out `--profile ai` to run without AI.
4. Open `http://192.168.1.10:3000` and type your email. Open Mailpit on port 8025 (user `broke`, password `MAIL_PASSWORD` from `docker/.env`) and click the sign-in link.
5. Lock it to you: set `DISABLE_SIGNUP=true` in `docker/.env`, then run the `up -d` command again.
6. Add your bank: Accounts, Add accounts, Import a statement. For ING, download your transactions from Mijn ING as CSV (comma or semicolon both work). Importing the same file again adds nothing.
More detail, including what each container does: [docker/README.md](docker/README.md).
## Keep it private
- Keep port 3000 and 8025 on your LAN or behind a VPN like Tailscale. Don't forward them on your router.
- Back up `DATA_DIR/db` and `docker/.env` together. The database is useless without the secrets in `.env`.
- `docker/.env` is in `.gitignore`. Never commit it.
## Update
brokeless never updates itself. Your server runs exactly the commit you built.
**Your own changes:** `git pull`, then `docker compose -f docker/docker-compose.yml up -d --build`. Database changes in `supabase/migrations` apply when it starts.
**New broke changes from upstream:** add upstream once, read only:
```bash
git remote add upstream https://github.com/nextwork-projects/broke.git
```
```bash
git remote set-url --push upstream DISABLED
```
Then each time:
```bash
git fetch upstream
```
```bash
git log --oneline main..upstream/main
```
Read what changed (`git show <commit>`). Take everything with `git merge upstream/main`, or single commits with `git cherry-pick <commit>`. Then push to your repo and rebuild.
Things to check in upstream changes: new outside calls (`fetch(` to a new host), new environment variables, and changes to `scripts/start.mjs` or `src/lib/llm/`.
## How AI stays private
Every AI path goes through one gate. A cloud model gets a summary: rounded amounts, names replaced by tokens. Full detail goes only to a local model, which is what Ollama is here. You can turn AI off in Settings. Each answer runs with no way to change your data.
## Optional things that do go out
All off unless you set them up:
- **Bank feeds:** Plaid (US, Canada), Akahu (New Zealand), Enable Banking (UK, Europe), Basiq (Australia), Belvo (Brazil). These are cloud services by nature. Keys go in `docker/.env`.
- **Cloud AI:** OpenRouter, or your Claude or Codex login. They only ever get the summary.
- **Exchange rates:** set `BROKE_OFFLINE=0` to total accounts in different currencies (rates from the ECB through frankfurter.dev). Without rates, money in another currency than yours is left out of totals. The "Use made-up data" demo bank is in US dollars, so it needs this unless your currency is USD.
- **Real sign-in emails:** set `SMTP_HOST` and friends in `docker/.env` to use your own mail server instead of Mailpit.
## Develop
Without Docker: you need your own Supabase (cloud or self-hosted) and Node 22.
```bash
npm ci
```
```bash
npm run dev
```
Keys go in on http://localhost:3000/setup. `CLAUDE.md` has the privacy rules for AI coding tools. Checks:
- `npm run lint` and `npx tsc --noEmit`
- `node src/lib/statement.test.ts`, `node src/lib/origin.test.ts` and the other `src/lib/*.test.ts` files
- `npm run migrate`: apply database changes now. They also apply on start.
`npm run app` starts it like broke's own installer does, and fast-forwards from your repo (`origin`) on each start. Set `BROKE_NO_AUTO_UPDATE=1` to turn that off.
## Licence
MIT, like broke. Copyright (c) 2026 NextWork, see [LICENSE](LICENSE). `docker/db/*.sql` come from Supabase's self-hosting setup (Apache-2.0).