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

+2
View File
@@ -4,3 +4,5 @@ __pycache__/
# your books and bank statements stay local # your books and bank statements stay local
data/ data/
.env
compose.override.yaml
+11 -3
View File
@@ -9,10 +9,18 @@ RUN apt-get update \
WORKDIR /app WORKDIR /app
COPY src ./src COPY src ./src
# LibreOffice needs a writable home; the container may run as any user # LibreOffice needs a writable home; /tmp is the only writable place besides /data
ENV HOME=/tmp ENV HOME=/tmp \
PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1
# run unprivileged by default (compose can override with `user:`)
USER 1000:1000
EXPOSE 8765 EXPOSE 8765
HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
CMD ["python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8765/healthz', timeout=3)"]
# /data holds the cashbooks and statements/; # /data holds the cashbooks and statements/;
# /statements holds ANZ statement folders mounted read-only # /statements can hold a read-only folder of ANZ exports
CMD ["python3", "src/webapp.py", "--host", "0.0.0.0", "--data", "/data", "--statements", "/statements"] CMD ["python3", "src/webapp.py", "--host", "0.0.0.0", "--data", "/data", "--statements", "/statements"]
+62 -8
View File
@@ -22,22 +22,74 @@ Everything runs on your machine; nothing is sent anywhere.
### Docker Compose (recommended) ### 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 ```bash
docker compose up -d --build 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) | | `CASHBOOK_PASSWORD` | *(required)* | login password |
| `~/Downloads/anz` | `/statements` (read-only) | ANZ CSV exports to pick from | | `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 **Reaching it from other machines:** keep it on `127.0.0.1` and put a reverse proxy
root, which maps to your user, so saved files stay yours. With rootful Docker, set with HTTPS in front (Caddy, nginx, Traefik). Basic auth sends the password with every
`CASHBOOK_USER=$(id -u):$(id -g)` before `docker compose up`. 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 ### Without Docker
@@ -53,6 +105,8 @@ python3 src/webapp.py
Options: `--port 8765`, `--host 127.0.0.1`, `--data DIR` (default `./data`), and Options: `--port 8765`, `--host 127.0.0.1`, `--data DIR` (default `./data`), and
`--statements DIR` (repeatable) for extra folders to list statements from. `--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 ## Using it
+40 -7
View File
@@ -1,15 +1,48 @@
services: services:
cashbook: cashbook:
build: . build: .
image: accounts-cashbook:latest
init: true init: true
# Rootless Docker maps container root to you, so files stay owned by you. restart: unless-stopped
# With rootful Docker, set CASHBOOK_USER=1000:1000 (your uid:gid) instead. stop_grace_period: 20s
user: "${CASHBOOK_USER:-0:0}"
# Run as the owner of ./data so saved books stay owned by them on the host.
# Rootless Docker maps container root to you instead: set CASHBOOK_USER=0:0.
user: "${CASHBOOK_USER:-1000:1000}"
# Only published on localhost by default; put a TLS reverse proxy in front
# to reach it from elsewhere (set CASHBOOK_BIND=0.0.0.0 only behind a firewall).
ports: ports:
- "127.0.0.1:8765:8765" - "${CASHBOOK_BIND:-127.0.0.1}:${CASHBOOK_PORT:-8765}:8765"
# Browser login (HTTP Basic). Set CASHBOOK_PASSWORD in .env; compose won't start without it.
environment:
CASHBOOK_USERNAME: "${CASHBOOK_USERNAME:-cashbook}"
CASHBOOK_PASSWORD: "${CASHBOOK_PASSWORD:?set CASHBOOK_PASSWORD in .env}"
volumes: volumes:
# cashbooks and statements/ (uploads go there too) # cashbooks and statements/ (uploads go there too)
- ./data:/data - ./data:/data
# ANZ CSV exports, read-only # optional: a folder of ANZ exports to pick from, read-only
- ${HOME}/Downloads/anz:/statements:ro # - /path/to/anz:/statements:ro
restart: unless-stopped
# Locked down: read-only image, scratch space in /tmp, no extra privileges
read_only: true
tmpfs:
- /tmp:size=512m,mode=1777
cap_drop:
- ALL
security_opt:
- no-new-privileges:true
pids_limit: 256
deploy:
resources:
limits:
cpus: "1.0"
memory: 1g
logging:
driver: json-file
options:
max-size: 10m
max-file: "3"
+77 -18
View File
@@ -9,6 +9,8 @@ from src/template.ods. Statements are .csv/.pdf files in DATA/statements
(where uploads go), DATA, ~/Downloads/anz and any --statements folders. (where uploads go), DATA, ~/Downloads/anz and any --statements folders.
""" """
import argparse import argparse
import base64
import hmac
import json import json
import os import os
import re import re
@@ -294,37 +296,91 @@ def api(method, path, query, body):
return None return None
class Handler(BaseHTTPRequestHandler): # Optional HTTP Basic auth: set CASHBOOK_PASSWORD, or CASHBOOK_PASSWORD_FILE (e.g. a
def log_message(self, fmt, *args): # Docker secret). The user name is CASHBOOK_USERNAME (default "cashbook").
pass AUTH = None
def _send(self, status, data, ctype="application/json"): SECURITY_HEADERS = {
"Cache-Control": "no-store",
"X-Content-Type-Options": "nosniff",
"X-Frame-Options": "DENY",
"Referrer-Policy": "no-referrer",
"Content-Security-Policy": "default-src 'self'; script-src 'self' 'unsafe-inline'; "
"style-src 'self' 'unsafe-inline'; frame-ancestors 'none'",
}
def load_auth():
password = os.environ.get("CASHBOOK_PASSWORD")
path = os.environ.get("CASHBOOK_PASSWORD_FILE")
if path:
with open(path) as f:
password = f.read().strip()
if not password:
return None
user = os.environ.get("CASHBOOK_USERNAME", "cashbook")
return base64.b64encode(f"{user}:{password}".encode()).decode()
class Handler(BaseHTTPRequestHandler):
server_version = "cashbook"
sys_version = ""
def log_request(self, code="-", size="-"):
if not self.path.startswith("/healthz"): # health checks would flood the log
super().log_request(code, size)
def _send(self, status, data, ctype="application/json", headers=None):
payload = data if isinstance(data, bytes) else json.dumps(data).encode() payload = data if isinstance(data, bytes) else json.dumps(data).encode()
self.send_response(status) self.send_response(status)
self.send_header("Content-Type", ctype) self.send_header("Content-Type", ctype)
self.send_header("Content-Length", str(len(payload))) self.send_header("Content-Length", str(len(payload)))
self.send_header("Cache-Control", "no-store") for k, v in {**SECURITY_HEADERS, **(headers or {})}.items():
self.send_header(k, v)
self.end_headers() self.end_headers()
self.wfile.write(payload) self.wfile.write(payload)
def _authorised(self):
if AUTH is None:
return True
given = self.headers.get("Authorization", "")
return given.startswith("Basic ") and hmac.compare_digest(given[6:].strip(), AUTH)
def _same_origin(self):
# browsers send Origin on POST; it must match the host the page was served from
origin = self.headers.get("Origin")
if not origin:
return True
return urlparse(origin).netloc == self.headers.get("Host") or \
urlparse(origin).hostname in ("127.0.0.1", "localhost")
def _handle(self, method): def _handle(self, method):
url = urlparse(self.path) url = urlparse(self.path)
if url.path == "/healthz":
return self._send(200, {"ok": True})
if not self._authorised():
return self._send(401, {"error": "login required"},
headers={"WWW-Authenticate": 'Basic realm="Cashbook", charset="UTF-8"'})
if method == "POST" and not self._same_origin():
return self._send(403, {"error": "forbidden"})
if method == "GET" and url.path in ("/", "/index.html"): if method == "GET" and url.path in ("/", "/index.html"):
with open(os.path.join(HERE, "static", "index.html"), "rb") as f: with open(os.path.join(HERE, "static", "index.html"), "rb") as f:
return self._send(200, f.read(), "text/html; charset=utf-8") return self._send(200, f.read(), "text/html; charset=utf-8")
length = int(self.headers.get("Content-Length") or 0) try:
length = int(self.headers.get("Content-Length") or 0)
except ValueError:
return self._send(400, {"error": "bad Content-Length"})
if length > MAX_UPLOAD:
self.close_connection = True
return self._send(413, {"error": "request too large"})
raw = self.rfile.read(length) if length else b"" raw = self.rfile.read(length) if length else b""
try: try:
if method == "GET" and url.path == "/api/statement/file": if method == "GET" and url.path == "/api/statement/file":
p = statement_path(parse_qs(url.query).get("path", [""])[0]) p = statement_path(parse_qs(url.query).get("path", [""])[0])
with open(p, "rb") as f: with open(p, "rb") as f:
data = f.read() data = f.read()
self.send_response(200) return self._send(200, data, "application/pdf" if p.lower().endswith(".pdf") else "text/csv",
self.send_header("Content-Type", "application/pdf" if p.lower().endswith(".pdf") else "text/csv") {"Content-Disposition": f'attachment; filename="{os.path.basename(p)}"'})
self.send_header("Content-Disposition", f'attachment; filename="{os.path.basename(p)}"')
self.send_header("Content-Length", str(len(data)))
self.end_headers()
return self.wfile.write(data)
if method == "POST" and url.path == "/api/upload": if method == "POST" and url.path == "/api/upload":
name = parse_qs(url.query).get("filename", [""])[0] name = parse_qs(url.query).get("filename", [""])[0]
path = save_upload(name, raw) path = save_upload(name, raw)
@@ -336,18 +392,14 @@ class Handler(BaseHTTPRequestHandler):
self._send(200, result) self._send(200, result)
except (BadRequest, BookLocked, KeyError, ValueError) as e: except (BadRequest, BookLocked, KeyError, ValueError) as e:
self._send(400, {"error": str(e)}) self._send(400, {"error": str(e)})
except Exception as e: except Exception:
traceback.print_exc() traceback.print_exc()
self._send(500, {"error": str(e)}) self._send(500, {"error": "something went wrong; see the server log"})
def do_GET(self): def do_GET(self):
self._handle("GET") self._handle("GET")
def do_POST(self): def do_POST(self):
# only accept requests from our own page
origin = self.headers.get("Origin")
if origin and urlparse(origin).hostname not in ("127.0.0.1", "localhost"):
return self._send(403, {"error": "forbidden"})
self._handle("POST") self._handle("POST")
@@ -363,10 +415,17 @@ def main():
args = ap.parse_args() args = ap.parse_args()
global BOOKS, UPLOADS global BOOKS, UPLOADS
BOOKS = os.path.abspath(os.path.expanduser(args.data)) BOOKS = os.path.abspath(os.path.expanduser(args.data))
os.makedirs(BOOKS, exist_ok=True)
UPLOADS = os.path.join(BOOKS, "statements") UPLOADS = os.path.join(BOOKS, "statements")
STATEMENT_DIRS[:] = [UPLOADS, BOOKS, os.path.expanduser("~/Downloads/anz")] STATEMENT_DIRS[:] = [UPLOADS, BOOKS, os.path.expanduser("~/Downloads/anz")]
STATEMENT_DIRS.extend(os.path.abspath(os.path.expanduser(d)) for d in args.statements) STATEMENT_DIRS.extend(os.path.abspath(os.path.expanduser(d)) for d in args.statements)
global AUTH
AUTH = load_auth()
if AUTH is None and args.host not in ("127.0.0.1", "localhost", "::1"):
print("Warning: no CASHBOOK_PASSWORD set; anyone who can reach this port can see your books",
file=sys.stderr, flush=True)
# stop LibreOffice too when the server is killed # stop LibreOffice too when the server is killed
signal.signal(signal.SIGTERM, lambda *_: sys.exit(0)) signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
server = ThreadingHTTPServer((args.host, args.port), Handler) server = ThreadingHTTPServer((args.host, args.port), Handler)