jimmyandClaude Opus 5.5 17b48f25e8 Make login optional and fix 403 on changes
- 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>
2026-10-24 17:41:01 +13:00

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

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):

mkdir -p data
(umask 077; echo "CASHBOOK_PASSWORD=$(openssl rand -base64 18)" >> .env)

Then start it:

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.

services:
  cashbook:
    volumes:
      - /path/to/anz:/statements:ro

Without Docker

Needs Python 3 with LibreOffice's UNO bridge and pdftotext. On Debian/Ubuntu:

sudo apt install libreoffice-calc python3-uno poppler-utils
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

python3 src/new_book.py data/cashbook-2026-27.ods --year 2026 --opening-balance 74.70
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 (IRD copyright statement). 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 licence instead.

Code

Copyright (C) 2026 jimmy

The code is licensed under the GNU Affero General Public License v3.0; see 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.

S
Description
No description provided
Readme AGPL-3.0
636 KiB
0 Stars 1 Watchers 0 Forks
Languages
Python 64.4%
HTML 23.4%
JavaScript 10.6%
CSS 1.2%
Dockerfile 0.4%