tonym
99b4dd2368
- changelog.json is now the single source of truth; version.py reads it. - release.py: one command to bump version + prepend a changelog entry + regen CHANGELOG.md. Dogfooded to cut 0.2.0. - repo CLAUDE.md documents the MANDATORY 'cut a release on every deploy' rule + deploy/secrets conventions, so it applies to anyone who pulls the repo. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
50 lines
2.5 KiB
Markdown
50 lines
2.5 KiB
Markdown
# Moon Household Budget
|
|
|
|
Personal household-budgeting web app. Bonna (Tony's wife) is the primary user.
|
|
Self-hosted; also serves as a **testbed** for a future low-cost SaaS (planned
|
|
price point ~$2.00 — do **not** build billing yet, just keep the option open).
|
|
|
|
## Stack
|
|
- **Flask + gunicorn** (1 worker + threads — state lives in files on the volume,
|
|
so multiple processes would race). Jinja templates all extend `base.html`.
|
|
- **Storage:** small data = JSON files via `storage.py` (atomic writes,
|
|
crash-safe loads). **Transactions = SQLite** (`txns_db.py`, `transactions.db`)
|
|
with the same list-of-dicts API as the old JSON.
|
|
- **Settings/secrets:** `/settings` page → `settings.py` → `settings.json` on the
|
|
volume (never in git). `reminders.py` reads Gmail creds from there.
|
|
- **Suggestions (💡):** `suggestions/` blueprint files feedback as Gitea issues
|
|
(needs `GITEA_URL/GITEA_TOKEN/GITEA_REPO` in `.env`).
|
|
- **Version chip + changelog:** `version.py` + `/changelog`, sourced from
|
|
`changelog.json`.
|
|
|
|
## ⚠️ Release process — REQUIRED on every deploy
|
|
Every deploy MUST cut a release so users see what changed. Before deploying:
|
|
|
|
```sh
|
|
python release.py <version> "<plain-language change>" "<another change>" [--title "..."]
|
|
```
|
|
|
|
- Bump the **patch** (0.1.0 → 0.1.1) for fixes, the **minor** (0.1.0 → 0.2.0)
|
|
for new features.
|
|
- Write changes in plain language Bonna will understand (not code-speak).
|
|
- This updates `changelog.json` (drives `__version__`, the footer chip, and
|
|
`/changelog`) and regenerates `CHANGELOG.md`. Commit both with your change.
|
|
- **Do not deploy without a new changelog entry.**
|
|
|
|
## Deploy (Docker on Unraid NAS — http://192.168.0.5:8052)
|
|
```sh
|
|
# from the repo root, after committing (incl. the release entry):
|
|
rsync -a --exclude='.git/' --exclude='data/' --exclude='.env' --exclude='__pycache__/' \
|
|
./ root@192.168.0.5:/mnt/user/appdata/moon-household-budget/
|
|
ssh root@192.168.0.5 'cd /mnt/user/appdata/moon-household-budget && docker compose up -d --build'
|
|
```
|
|
- **Never** rsync `data/` or `.env` — that's live data and secrets on the volume.
|
|
- Templates are baked into the image, so template changes need `--build`.
|
|
- Backups: the `backup` sidecar tars `/data` to `/mnt/user/Backup/moon-household-budget/`
|
|
daily; pushes to Backblaze B2 only once a real bucket/key is in `.env`.
|
|
|
|
## Conventions
|
|
- Secrets never go in source — use `.env` (container) or `settings.json` (volume).
|
|
- Keep other small JSON files as JSON; only `transactions` warranted SQLite.
|
|
- Repo lives on the home Gitea: `bonna61/Moon-Household-Budget`.
|