Make Docker Compose setup production-ready

- Require a login: HTTP Basic auth from CASHBOOK_PASSWORD (compose
  refuses to start without it); /healthz stays open for health checks
- Run as non-root (1000:1000 by default, CASHBOOK_USER to override)
  with a read-only filesystem, tmpfs /tmp, no capabilities,
  no-new-privileges, and CPU/memory/pid limits
- Health check, log rotation, configurable bind address and port
- Refuse cross-origin POSTs by matching Origin to Host (works behind a
  reverse proxy), cap request size, add security headers, and stop
  leaking exception text in 500 responses
- Make the extra statements mount opt-in; create the data folder at
  startup; document server setup and reverse proxying in the README

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
jimmyandClaude Opus 5.5 committed 2026-10-24 17:25:45 +13:00
1 parent 971de14356
commit 9b9203c4bb
5 files changed
+192 -36

No files matched your search

+62 -8
View File
@@ -22,22 +22,74 @@ Everything runs on your machine; nothing is sent anywhere.
### 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>. Stop it with `docker compose down`.
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`.
The compose file mounts:
**What the compose file sets up**
| Host | Container | Purpose |
- **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.
- **Limits:** 1 CPU, 1 GB of memory, 256 processes. It uses about 150 MB in practice.
- **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 |
|---|---|---|
| `./data` | `/data` | cashbooks and `statements/` (uploads go here) |
| `~/Downloads/anz` | `/statements` (read-only) | ANZ CSV exports to pick from |
| `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 |
The app is only published on `127.0.0.1`. With rootless Docker the container runs as
root, which maps to your user, so saved files stay yours. With rootful Docker, set
`CASHBOOK_USER=$(id -u):$(id -g)` before `docker compose up`.
**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
@@ -53,6 +105,8 @@ 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