- BROKE_OFFLINE=1 (on in Docker) turns off the GitHub update check and the exchange-rate fetch, so the server makes no calls out - auto-update in scripts/start.mjs pulls from your own repo (origin), never upstream - install.sh points at brokeless; drop the workflow that merged upstream by itself - compose project and image are named brokeless - README: what changed from broke, how to run it, how to review upstream Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
141 lines
6.2 KiB
Markdown
141 lines
6.2 KiB
Markdown
# 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).
|