brokeless: fully local by default, and a README for it

- 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>
This commit is contained in:
MangaValkandClaude Opus 5.5 committed 2026-11-17 14:08:42 +01:00
1 parent 861e65021f
commit cec3b15c2c
9 files changed
+137 -92

No files matched your search

-22
View File
@@ -1,22 +0,0 @@
# The "Update broke" button for a copy in your own GitHub: Actions, Update broke, Run workflow.
# It pulls in the latest broke and keeps your changes. Vercel then rebuilds your site by itself.
name: Update broke
on: workflow_dispatch
permissions:
contents: write
jobs:
update:
if: github.repository != 'nextwork-projects/broke'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 22
- run: |
git config user.name "broke update"
git config user.email "broke-update@users.noreply.github.com"
node scripts/update.mjs --ci
git push
+114 -44
View File
@@ -1,70 +1,140 @@
# broke # brokeless
See where your money goes, get a plan for it, and ask your own AI about it. Your bank data stays in your own database. 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.
Next.js 15, Supabase, Plaid. Free to run. AI uses the app you already pay for, with no API keys. 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.
## Run it on your computer ## What's different from broke
The easiest way. Needs [Node.js](https://nodejs.org) and [git](https://git-scm.com/downloads). On Mac or Linux: | | 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 ```bash
curl -fsSL https://raw.githubusercontent.com/nextwork-projects/broke/main/install.sh | sh git clone https://mangavalk.com/mangavalk/brokeless.git
``` ```
This puts broke in `~/broke` and opens a setup page. Paste in your keys there, one step at a time: 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):
1. **Supabase** (free): your database and sign-in.
2. **Plaid** (free for test banks): your bank connection.
3. **AI** (optional): broke finds Claude Code, Codex, Gemini CLI, opencode or a local model on your computer. Or connect OpenRouter in one click.
To start it again: open a new Terminal window and type `broke`.
On Windows: `git clone https://github.com/nextwork-projects/broke`, then `npm run app` in that folder.
## Put it online
Use it from your phone, on a site only you own.
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fnextwork-projects%2Fbroke&project-name=broke&repository-name=broke&env=NEXT_PUBLIC_SUPABASE_URL%2CNEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY%2CSUPABASE_SERVICE_ROLE_KEY%2CSUPABASE_DB_URL%2CPLAID_CLIENT_ID%2CPLAID_SECRET%2CPLAID_ENV&envDescription=Your+Supabase+project+and+Plaid+keys.+Only+your+copy+of+broke+sees+them.&envLink=https%3A%2F%2Fgithub.com%2Fnextwork-projects%2Fbroke%23put-it-online&envDefaults=%7B%22PLAID_ENV%22%3A%22sandbox%22%7D)
1. Create a free [Supabase](https://supabase.com/dashboard/new) project and get [Plaid keys](https://dashboard.plaid.com/developers/keys).
2. Press the button and paste them in. `SUPABASE_DB_URL` is under Supabase, Connect, Session pooler. broke creates its tables as it builds.
3. Open your new site. It shows one step to do in Supabase before your first sign-in.
4. Sign in once, then turn off "Allow new users to sign up" under Authentication, Sign In / Providers, so nobody else can use your copy.
**AI on an online copy:** connect OpenRouter in one click. Or, to use your Claude or opencode plan, press **Connect my computer** on Connect your AI and run the command it gives you. Your AI login stays on your computer. AI answers while that command is running.
## Improve it
broke is yours to change. Open the folder and tell your AI app what you want:
```bash ```bash
cd ~/broke && claude cd brokeless && node docker/setup.mjs --url http://192.168.1.10:3000
``` ```
`CLAUDE.md` tells it the privacy rules. Run `npm run dev` to see changes as they happen. On an online copy, `git push` publishes them. No Node on the server:
**Get the latest broke:** it updates itself each time you start it (`broke`, or the install command), as long as you haven't changed its code. With your own changes, run `npm run update`. To turn auto-update off, start it with `BROKE_NO_AUTO_UPDATE=1`. On an online copy there's nothing to install: in your GitHub repo open Actions, Update broke, Run workflow, and Vercel rebuilds your site. Your changes stay either way. ```bash
docker run --rm -v "$PWD":/w -w /w node:22-alpine node docker/setup.mjs --url http://192.168.1.10:3000
```
If you make something others would want, send a pull request. 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.
## Banks 3. Start it, with local AI:
**Banks in other countries (all optional, keys on the Setup page):** Plaid (US, Canada), Akahu (New Zealand), Enable Banking (UK, Europe), Basiq (Australia), Belvo (Brazil). Each shows only for that country. Enable Banking, Basiq and Belvo are built from their public docs and tested against stand-ins, so test against the vendor's sandbox before relying on them. Anywhere else, people import a CSV, OFX, QIF or PDF statement. ```bash
docker compose -f docker/docker-compose.yml --profile ai up -d --build
```
In test mode, press **Use a test bank**, or pick any bank in Plaid Link with username `user_good` and password `pass_good`. 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 ## 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. You can turn AI off in Settings. Each answer runs with no way to change your data. 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.
## Scripts ## 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 migrate`: apply database changes now. They also apply on start.
- `node --env-file=.env --env-file-if-exists=.env.local scripts/e2e-sandbox.mjs`: throwaway user, test bank, every page, user deleted.
- `node src/lib/format.test.ts` and `node src/lib/llm/config.test.ts`: unit checks. `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 ## Licence
MIT. MIT, like broke. Copyright (c) 2026 NextWork, see [LICENSE](LICENSE). `docker/db/*.sql` come from Supabase's self-hosting setup (Apache-2.0).
+6 -16
View File
@@ -1,6 +1,6 @@
# Run broke fully on your own server # brokeless in Docker
Everything runs here: broke, its Postgres database, sign-in and the REST API (the parts of Supabase it uses), a mail catcher for sign-in links, and optionally Ollama for AI. No Supabase cloud, no Vercel, no auto-update. Everything runs here: the app, its Postgres database, sign-in and the REST API (the parts of Supabase it uses), a mail catcher for sign-in links, and optionally Ollama for AI. No Supabase cloud, no Vercel, no auto-update.
| Container | What it does | Port | | Container | What it does | Port |
| --- | --- | --- | | --- | --- | --- |
@@ -26,7 +26,7 @@ Everything runs here: broke, its Postgres database, sign-in and the REST API (th
docker run --rm -v "$PWD":/w -w /w node:22-alpine node docker/setup.mjs --url http://192.168.1.10:3000 docker run --rm -v "$PWD":/w -w /w node:22-alpine node docker/setup.mjs --url http://192.168.1.10:3000
``` ```
On Unraid, edit `docker/.env` and set `DATA_DIR=/mnt/user/appdata/broke`. On Unraid, edit `docker/.env` and set `DATA_DIR=/mnt/user/appdata/brokeless`.
2. Start it: 2. Start it:
@@ -34,7 +34,7 @@ Everything runs here: broke, its Postgres database, sign-in and the REST API (th
docker compose -f docker/docker-compose.yml up -d --build docker compose -f docker/docker-compose.yml up -d --build
``` ```
With local AI as well: add `--profile ai`, then pull a model, for example `docker exec broke-ollama-1 ollama pull qwen3:8b`. With local AI as well: add `--profile ai`, then pull a model, for example `docker exec brokeless-ollama-1 ollama pull qwen3:8b`.
3. Open your address, type your email, then open Mailpit on port 8025 (user `broke`, password `MAIL_PASSWORD` in `docker/.env`) and click the link. 3. Open your address, type your email, then open Mailpit on port 8025 (user `broke`, password `MAIL_PASSWORD` in `docker/.env`) and click the link.
@@ -53,18 +53,8 @@ Install the Compose Manager plugin, add a stack, and point it at this folder's `
- Back up `DATA_DIR/db` and `docker/.env` together. The database is useless without the secrets in `.env`. - Back up `DATA_DIR/db` and `docker/.env` together. The database is useless without the secrets in `.env`.
- Database changes in `supabase/migrations` apply each time broke starts. - Database changes in `supabase/migrations` apply each time broke starts.
## Updating from upstream ## Updating
This copy never pulls by itself. To see and pick what's new: Nothing updates by itself. See [Update](../README.md#update) in the main README for pulling your own changes and reviewing upstream ones.
```bash
git fetch upstream
```
```bash
git log --oneline main..upstream/main
```
Review, then `git merge upstream/main` (or `git cherry-pick <commit>` for single ones), and rebuild with `up -d --build`.
`docker/db/*.sql` come from Supabase's self-hosting setup (Apache-2.0). `docker/db/*.sql` come from Supabase's self-hosting setup (Apache-2.0).
+6 -4
View File
@@ -1,11 +1,11 @@
# broke with everything it needs, all on your own server. See README.md in this folder. # brokeless: broke with everything it needs, all on your own server. See README.md in this folder.
# node docker/setup.mjs --url http://192.168.1.10:3000 (once: writes docker/.env with fresh secrets) # node docker/setup.mjs --url http://192.168.1.10:3000 (once: writes docker/.env with fresh secrets)
# docker compose -f docker/docker-compose.yml up -d --build # docker compose -f docker/docker-compose.yml up -d --build
# ... --profile ai up -d (also runs Ollama for local AI) # ... --profile ai up -d (also runs Ollama for local AI)
# #
# Supabase parts (db, auth, rest) follow Supabase's own self-hosting setup, cut down to what broke uses. # Supabase parts (db, auth, rest) follow Supabase's own self-hosting setup, cut down to what broke uses.
name: broke name: brokeless
x-hardening: &hardening x-hardening: &hardening
restart: unless-stopped restart: unless-stopped
@@ -33,11 +33,13 @@ services:
args: args:
NEXT_PUBLIC_SUPABASE_URL: ${PUBLIC_URL} NEXT_PUBLIC_SUPABASE_URL: ${PUBLIC_URL}
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY: ${ANON_KEY} NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY: ${ANON_KEY}
image: broke:local image: brokeless:local
cap_drop: [ALL] cap_drop: [ALL]
environment: environment:
NEXT_PUBLIC_SUPABASE_URL: ${PUBLIC_URL} NEXT_PUBLIC_SUPABASE_URL: ${PUBLIC_URL}
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY: ${ANON_KEY} NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY: ${ANON_KEY}
# No calls out: no update check, no exchange rates. Set to 0 for rates across currencies (frankfurter.dev).
BROKE_OFFLINE: ${BROKE_OFFLINE:-1}
SUPABASE_SERVICE_ROLE_KEY: ${SERVICE_ROLE_KEY} SUPABASE_SERVICE_ROLE_KEY: ${SERVICE_ROLE_KEY}
# Inside the stack only, so no SSL (broke turns SSL on unless the URL says otherwise). # Inside the stack only, so no SSL (broke turns SSL on unless the URL says otherwise).
SUPABASE_DB_URL: postgresql://postgres:${POSTGRES_PASSWORD}@db:5432/postgres?sslmode=disable SUPABASE_DB_URL: postgresql://postgres:${POSTGRES_PASSWORD}@db:5432/postgres?sslmode=disable
@@ -149,7 +151,7 @@ services:
MP_UI_AUTH: broke:${MAIL_PASSWORD} MP_UI_AUTH: broke:${MAIL_PASSWORD}
MP_MAX_MESSAGES: 200 MP_MAX_MESSAGES: 200
# Local AI, full detail stays here. Start with --profile ai, then: docker exec broke-ollama-1 ollama pull <model> # Local AI, full detail stays here. Start with --profile ai, then: docker exec brokeless-ollama-1 ollama pull <model>
ollama: ollama:
<<: *hardening <<: *hardening
image: ollama/ollama:latest image: ollama/ollama:latest
+4 -1
View File
@@ -39,7 +39,7 @@ writeFileSync(file, `# Made by docker/setup.mjs. Keep it private and backed up:
# The address you open broke on. Built into the app: change it and rebuild (up -d --build). # The address you open broke on. Built into the app: change it and rebuild (up -d --build).
PUBLIC_URL=${url} PUBLIC_URL=${url}
HTTP_PORT=${port} HTTP_PORT=${port}
# Where the database (and Ollama models) live. On Unraid, for example /mnt/user/appdata/broke # Where the database (and Ollama models) live. On Unraid, for example /mnt/user/appdata/brokeless
DATA_DIR=./data DATA_DIR=./data
POSTGRES_PASSWORD=${hex(24)} POSTGRES_PASSWORD=${hex(24)}
@@ -60,6 +60,9 @@ MAIL_PASSWORD=${hex(12)}
# After your first sign-in, set this to true and run up -d again. # After your first sign-in, set this to true and run up -d again.
DISABLE_SIGNUP=false DISABLE_SIGNUP=false
# 1 = no calls out (no update check, no exchange rates). 0 = fetch ECB rates for totals across currencies.
BROKE_OFFLINE=1
# Local AI (docker compose --profile ai). Empty model = the first one installed. # Local AI (docker compose --profile ai). Empty model = the first one installed.
LOCAL_LLM_BASE_URL=http://ollama:11434/v1 LOCAL_LLM_BASE_URL=http://ollama:11434/v1
LOCAL_LLM_MODEL= LOCAL_LLM_MODEL=
+2 -2
View File
@@ -1,8 +1,8 @@
#!/bin/sh #!/bin/sh
# Installs broke into ~/broke (or $BROKE_DIR) and starts it: # Installs broke into ~/broke (or $BROKE_DIR) and starts it:
# curl -fsSL https://raw.githubusercontent.com/nextwork-projects/broke/main/install.sh | sh # curl -fsSL https://mangavalk.com/mangavalk/brokeless/raw/branch/main/install.sh | sh
set -e set -e
REPO="${BROKE_REPO:-https://github.com/nextwork-projects/broke.git}" REPO="${BROKE_REPO:-https://mangavalk.com/mangavalk/brokeless.git}"
DIR="${BROKE_DIR:-$HOME/broke}" DIR="${BROKE_DIR:-$HOME/broke}"
command -v git >/dev/null || { echo "broke needs git. Get it from https://git-scm.com/downloads, then run this again."; exit 1; } command -v git >/dev/null || { echo "broke needs git. Get it from https://git-scm.com/downloads, then run this again."; exit 1; }
+3 -2
View File
@@ -19,14 +19,15 @@ const npm = (...args) => spawnSync("npm", args, { stdio: "inherit", shell: win }
// Checks for next itself, not node_modules: a stopped first install leaves a half-full node_modules. // Checks for next itself, not node_modules: a stopped first install leaves a half-full node_modules.
const nextBin = join("node_modules", ".bin", win ? "next.cmd" : "next"); const nextBin = join("node_modules", ".bin", win ? "next.cmd" : "next");
// Auto-update: each start brings in the newest broke when this copy has no changes of its own (a fast-forward only). // Auto-update: each start brings in the newest commits from your own repo (the "origin" remote, or BROKE_REPO), when
// this copy has no changes of its own (a fast-forward only). Never from upstream: those are reviewed and merged by hand.
// Your own changes or commits, no git, no internet, or BROKE_NO_AUTO_UPDATE=1: it starts the copy you have. // Your own changes or commits, no git, no internet, or BROKE_NO_AUTO_UPDATE=1: it starts the copy you have.
const git = (...args) => spawnSync("git", args, { encoding: "utf8", shell: win }); const git = (...args) => spawnSync("git", args, { encoding: "utf8", shell: win });
let lockChanged = false; let lockChanged = false;
if (existsSync(".git") && !process.env.BROKE_NO_AUTO_UPDATE) { if (existsSync(".git") && !process.env.BROKE_NO_AUTO_UPDATE) {
if (git("status", "--porcelain").stdout.trim() === "M package-lock.json") git("checkout", "--", "package-lock.json"); // npm's rewrite, not yours if (git("status", "--porcelain").stdout.trim() === "M package-lock.json") git("checkout", "--", "package-lock.json"); // npm's rewrite, not yours
const clean = git("status", "--porcelain").stdout.trim() === ""; const clean = git("status", "--porcelain").stdout.trim() === "";
const fetched = git("fetch", "--quiet", process.env.BROKE_REPO || "https://github.com/nextwork-projects/broke.git", "main").status === 0; const fetched = git("fetch", "--quiet", process.env.BROKE_REPO || "origin", "main").status === 0;
const head = git("rev-parse", "HEAD").stdout.trim(), latest = fetched ? git("rev-parse", "FETCH_HEAD").stdout.trim() : head; const head = git("rev-parse", "HEAD").stdout.trim(), latest = fetched ? git("rev-parse", "FETCH_HEAD").stdout.trim() : head;
if (latest !== head) { if (latest !== head) {
const behindOnly = git("merge-base", "--is-ancestor", "HEAD", latest).status === 0; const behindOnly = git("merge-base", "--is-ancestor", "HEAD", latest).status === 0;
+1
View File
@@ -19,6 +19,7 @@ let running: Promise<void> = Promise.resolve();
// Stores the days since the newest stored rate (2 years back on the first run), once a day per server process. // Stores the days since the newest stored rate (2 years back on the first run), once a day per server process.
// ponytail: per-process memo; a cron would do it once for every server if there are many. // ponytail: per-process memo; a cron would do it once for every server if there are many.
export function ensureRates(admin: SupabaseClient, today = new Date().toISOString().slice(0, 10)) { export function ensureRates(admin: SupabaseClient, today = new Date().toISOString().slice(0, 10)) {
if (process.env.BROKE_OFFLINE === "1") return running; // offline: no rates fetched, totals in other currencies are left out
if (checked === today) return running; if (checked === today) return running;
checked = today; checked = today;
return (running = (async () => { return (running = (async () => {
+1 -1
View File
@@ -7,7 +7,7 @@ const g = globalThis as unknown as { __brokeUpdate?: { at: number; newer: boolea
export async function updateReady() { export async function updateReady() {
const built = process.env.BROKE_BUILT_FROM; const built = process.env.BROKE_BUILT_FROM;
if (!built) return false; if (!built || process.env.BROKE_OFFLINE === "1") return false; // offline: updates are pulled and reviewed by hand
if (g.__brokeUpdate && Date.now() - g.__brokeUpdate.at < 6 * 3600_000) return g.__brokeUpdate.newer; if (g.__brokeUpdate && Date.now() - g.__brokeUpdate.at < 6 * 3600_000) return g.__brokeUpdate.newer;
let newer = false; let newer = false;
try { try {