Files
accounts/README.md
T
jimmyandClaude Opus 5.5 5dac554050 Drop container resource limits from compose
Newer Docker Compose rejects pids_limit alongside deploy.resources.limits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-24 17:29:15 +13:00

208 lines
7.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Accounts
A small local web app for keeping a New Zealand business cashbook from ANZ bank
statements. It fills in a LibreOffice/Excel cashbook spreadsheet (one sheet per
month, April–March), so the spreadsheet stays the record and can still be opened
and edited directly.
- Import ANZ statements: **CSV exports** from internet banking or **PDF statements**
(including a PDF holding several monthly statements).
- Upload statements by drag-and-drop, then view, download, rename or remove them.
Each one shows how much of it is already in the selected book.
- Preview an import before it happens. Transactions already in the book are skipped,
matched on date and amount, so a CSV and a PDF of the same period don't double up.
- Review each month and set GST (incl/excl) and the income or expense category per
transaction.
- See the year at a glance, with a six-monthly GST summary (Apr–Sep, Oct–Mar) and
IRD due dates.
Everything runs on your machine; nothing is sent anywhere.
## Running it
### Docker Compose (recommended)
One-time setup, as the user who should own the books (uid 1000 by default).
Create the data folder, then put a login password in `.env`:
```bash
mkdir -p data
```
```bash
(umask 077; echo "CASHBOOK_PASSWORD=$(openssl rand -base64 18)" >> .env)
```
Then start it:
```bash
docker compose up -d --build
```
Open <http://127.0.0.1:8765> and log in as `cashbook` with the password from
`.env`. Compose refuses to start if `CASHBOOK_PASSWORD` isn't set. Stop it with `docker compose down`, and check it with
`docker compose ps` (it reports `healthy`) or `docker compose logs`.
**What the compose file sets up**
- **Data:** `./data` is mounted at `/data` and holds the cashbooks and `statements/`
(uploads go there). Back up this folder.
- **Login:** HTTP Basic auth, with the password from the `CASHBOOK_PASSWORD`
environment variable.
- **Network:** published on `127.0.0.1:8765` only.
- **Lockdown:**
- read-only container filesystem, with scratch space only in `/tmp` (tmpfs);
- no Linux capabilities and `no-new-privileges`;
- runs as a non-root user.
- **Operations:** a health check on `/healthz`, rotated logs (3 × 10 MB) and
`restart: unless-stopped`.
**Settings** go in a `.env` file next to `compose.yaml`. Keep it private
(`chmod 600 .env`); it's git-ignored.
| Variable | Default | Purpose |
|---|---|---|
| `CASHBOOK_PASSWORD` | *(required)* | login password |
| `CASHBOOK_USER` | `1000:1000` | uid:gid to run as; it should own `data/`. Use `0:0` with rootless Docker, which maps container root to you. |
| `CASHBOOK_USERNAME` | `cashbook` | login name |
| `CASHBOOK_BIND` | `127.0.0.1` | host address to publish on |
| `CASHBOOK_PORT` | `8765` | host port |
**Reaching it from other machines:** keep it on `127.0.0.1` and put a reverse proxy
with HTTPS in front (Caddy, nginx, Traefik). Basic auth sends the password with every
request, so don't expose it over plain HTTP. The proxy must pass the original `Host`
header through; uploads and changes are refused when the page's origin doesn't match
it. For example, with Caddy:
```
cashbook.example.com {
reverse_proxy 127.0.0.1:8765
}
```
To also list ANZ exports from a folder on the host, add a `compose.override.yaml`.
It's git-ignored too.
```yaml
services:
cashbook:
volumes:
- /path/to/anz:/statements:ro
```
### Without Docker
Needs Python 3 with LibreOffice's UNO bridge and `pdftotext`. On Debian/Ubuntu:
```bash
sudo apt install libreoffice-calc python3-uno poppler-utils
```
```bash
python3 src/webapp.py
```
Options: `--port 8765`, `--host 127.0.0.1`, `--data DIR` (default `./data`), and
`--statements DIR` (repeatable) for extra folders to list statements from.
Set `CASHBOOK_PASSWORD` (or `CASHBOOK_PASSWORD_FILE`) to require a login; without
one, anyone who can reach the port can see your books.
## Using it
1. **New book…** creates `data/cashbook-YYYY-YY.ods` from the template for a
financial year. If you've ticked a PDF statement covering 31 March, the opening
balance is filled in from it.
2. Add statements (drop them on the page, or **Add…**), tick them, and **Preview import**.
3. Check the preview: new rows, rows already in the book, and rows outside the book's
year. Then import. The book is backed up to `<book>.ods.bak` first.
4. Go through each month: fix GST settings and allocate categories. **Only unallocated**
filters to what still needs doing.
5. Check the GST table on the Year page before filing.
Close a book in LibreOffice before changing it in the app; the app refuses to save
while LibreOffice has it open.
### How transactions are classified
These are starting guesses to review, not tax advice:
- NZ card purchases and payments out: **Incl GST**, unallocated.
- Overseas purchases (with a foreign currency amount), bank fees, transfers and money
in: **Excl GST**.
- Bank fees go to *Bank fees*.
- Transfers to and from your own accounts (`OWN_ACCOUNT_PREFIX` in
`src/statements.py`) go to *Drawings* (out) or *Funds Intr.* (in).
Income that is a GST-able sale needs changing to **Incl GST** by hand, otherwise it
won't count in the GST summary.
## Command line
```bash
python3 src/new_book.py data/cashbook-2026-27.ods --year 2026 --opening-balance 74.70
```
```bash
python3 src/anz_import.py data/cashbook-2026-27.ods data/statements/statement.pdf
```
`anz_import.py` refuses transactions outside the book's year unless you pass `--force`.
## Layout
```
src/
webapp.py web server and JSON API (stdlib only)
static/ the web page
statements.py reads ANZ CSV and PDF statements, GST/category guesses
cashbook.py reads and writes the spreadsheet
office.py runs a private headless LibreOffice
new_book.py creates a book from the template (also a CLI)
anz_import.py imports statements (CLI)
template.ods blank cashbook template
data/ your books and statements (git-ignored)
```
`data/` is in `.gitignore`: books, backups and bank statements are never committed.
Removed statements go to `data/statements/.trash`.
## Licence
### Cashbook template
`src/template.ods` is adapted from a free cashbook spreadsheet published by the
New Zealand Government. Its instructions refer to downloading it "from our website"
and to newzealand.govt.nz, and it was created in 2008. It appears to be the Inland
Revenue (IRD) cashbook template, but the original download page couldn't be confirmed.
Inland Revenue publishes its Crown copyright material under the
[Creative Commons Attribution 4.0 International licence](https://creativecommons.org/licenses/by/4.0/)
([IRD copyright statement](https://www.ird.govt.nz/about-this-site/conditions-of-use/copyright)).
You may reuse and adapt it, including commercially, if you:
- acknowledge the source and its Crown copyright status,
- reproduce it accurately and say what was changed,
- don't use it in a misleading or derogatory way.
The licence excludes logos, emblems, trademarks, design elements and photography.
The template contains none of these.
Attribution: *Cashbook template © Crown copyright, New Zealand Government (Inland
Revenue), licensed under CC BY 4.0. Modified: all transaction data and the opening
balance cleared.*
If you confirm the template came from a different agency, check that agency's terms.
Some, such as business.govt.nz, use the non-commercial
[CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/) licence instead.
### Code
Copyright (C) 2026 jimmy
The code is licensed under the GNU Affero General Public License v3.0; see
[LICENSE](LICENSE). It's free software: you can redistribute and modify it under
the AGPL. If you run a modified version as a network service, you must offer its
source code to the people who use it. It comes with no warranty.
The template is covered by its own CC BY 4.0 licence above, not the AGPL.