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
data/
.env
compose.override.yaml
+11 -3
View File
@@ -9,10 +9,18 @@ RUN apt-get update \
WORKDIR /app
COPY src ./src
# LibreOffice needs a writable home; the container may run as any user
ENV HOME=/tmp
# LibreOffice needs a writable home; /tmp is the only writable place besides /data
ENV HOME=/tmp \
PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1
# run unprivileged by default (compose can override with `user:`)
USER 1000:1000
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/;
# /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"]
+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
+40 -7
View File
@@ -1,15 +1,48 @@
services:
cashbook:
build: .
image: accounts-cashbook:latest
init: true
# Rootless Docker maps container root to you, so files stay owned by you.
# With rootful Docker, set CASHBOOK_USER=1000:1000 (your uid:gid) instead.
user: "${CASHBOOK_USER:-0:0}"
restart: unless-stopped
stop_grace_period: 20s
# 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:
- "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:
# cashbooks and statements/ (uploads go there too)
- ./data:/data
# ANZ CSV exports, read-only
- ${HOME}/Downloads/anz:/statements:ro
restart: unless-stopped
# optional: a folder of ANZ exports to pick from, read-only
# - /path/to/anz:/statements:ro
# 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.
"""
import argparse
import base64
import hmac
import json
import os
import re
@@ -294,37 +296,91 @@ def api(method, path, query, body):
return None
class Handler(BaseHTTPRequestHandler):
def log_message(self, fmt, *args):
pass
# Optional HTTP Basic auth: set CASHBOOK_PASSWORD, or CASHBOOK_PASSWORD_FILE (e.g. a
# Docker secret). The user name is CASHBOOK_USERNAME (default "cashbook").
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()
self.send_response(status)
self.send_header("Content-Type", ctype)
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.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):
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"):
with open(os.path.join(HERE, "static", "index.html"), "rb") as f:
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""
try:
if method == "GET" and url.path == "/api/statement/file":
p = statement_path(parse_qs(url.query).get("path", [""])[0])
with open(p, "rb") as f:
data = f.read()
self.send_response(200)
self.send_header("Content-Type", "application/pdf" if p.lower().endswith(".pdf") else "text/csv")
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)
return self._send(200, data, "application/pdf" if p.lower().endswith(".pdf") else "text/csv",
{"Content-Disposition": f'attachment; filename="{os.path.basename(p)}"'})
if method == "POST" and url.path == "/api/upload":
name = parse_qs(url.query).get("filename", [""])[0]
path = save_upload(name, raw)
@@ -336,18 +392,14 @@ class Handler(BaseHTTPRequestHandler):
self._send(200, result)
except (BadRequest, BookLocked, KeyError, ValueError) as e:
self._send(400, {"error": str(e)})
except Exception as e:
except Exception:
traceback.print_exc()
self._send(500, {"error": str(e)})
self._send(500, {"error": "something went wrong; see the server log"})
def do_GET(self):
self._handle("GET")
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")
@@ -363,10 +415,17 @@ def main():
args = ap.parse_args()
global BOOKS, UPLOADS
BOOKS = os.path.abspath(os.path.expanduser(args.data))
os.makedirs(BOOKS, exist_ok=True)
UPLOADS = os.path.join(BOOKS, "statements")
STATEMENT_DIRS[:] = [UPLOADS, BOOKS, os.path.expanduser("~/Downloads/anz")]
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
signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
server = ThreadingHTTPServer((args.host, args.port), Handler)