- CASHBOOK_PASSWORD is now optional; without it there's no login and the server logs a warning - Origin check compares host names only, and also accepts X-Forwarded-Host and CASHBOOK_ALLOWED_HOSTS, so changes work when the app is reached by IP, on another port or through a proxy; refusals are logged with the reason and explained in the error - Add a favicon so browsers stop requesting a missing /favicon.ico Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
215 lines
8.3 KiB
Markdown
215 lines
8.3 KiB
Markdown
# 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` (optional, see below):
|
||
|
||
```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`. With no `CASHBOOK_PASSWORD` set, there's no login: anyone who can reach the
|
||
port can see and change your books, so only do that on a network you trust. 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. Leave it unset to turn the login off.
|
||
- **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` | *(none)* | login password; unset means no login |
|
||
| `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 |
|
||
| `CASHBOOK_ALLOWED_HOSTS` | | extra host names you open the app by, comma-separated; see below |
|
||
|
||
**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.
|
||
|
||
To block other websites from making changes through your login, the app refuses
|
||
changes whose page address doesn't match the server's host name. It checks the
|
||
`Host` and `X-Forwarded-Host` headers. Caddy passes the original host through. With
|
||
nginx, add `proxy_set_header Host $host;`. Otherwise, list the name you use in
|
||
`CASHBOOK_ALLOWED_HOSTS`. A refused request shows up in `docker compose logs` with
|
||
the reason. A Caddy example:
|
||
|
||
```
|
||
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.
|