parsimony/README.md
tgiachi ccb2940d6e build(docker): run as a non-root user with a read-only root filesystem
- Use the distroless nonroot image and USER 65532
- Make /data the only writable path, owned by the unprivileged user
- Read the config from /etc/parsimony/parsimony.yaml, mounted read-only
- Expose the three listener ports
- Document the run command in the README
2026-11-09 16:11:55 +01:00

4.3 KiB

parsimony

A modern, single-binary mailing list manager: an evolution of Mailman.

  • Postfix delivers to parsimony over LMTP; parsimony relays through SMTP.
  • Discussion lists with member-only posting, List-* headers, one-click unsubscribe and DMARC-safe From rewriting.
  • Durable outbound queue: a post is accepted once it is stored, one delivery per recipient, and a background worker sends it with retries (1m, 5m, 15m, 1h, 3h, then every 6h, for up to 3 days). Relay outages and restarts lose nothing.
  • Self-service subscribe and unsubscribe by email with double opt-in: send to list+join@domain or list+leave@domain, then reply to the confirmation.
  • Moderated lists: posts wait in a queue that the API can approve or discard.
  • VERP bounces: every recipient gets a signed return address; 3 hard bounces disable a member.
  • Archive with full-text search (SQLite FTS5) and threading. Each list has an archive_policy: private (default, API only), public (web pages) or off. Public pages hide email addresses.
  • Per-recipient one-click unsubscribe links (RFC 8058) with signed tokens.
  • SQLite storage, one YAML config file.
  • Admin REST API under /api/v1 (see docs/openapi.yaml).
  • Admin web UI (Vite, React, shadcn/ui) served by the API listener at /: lists, settings, members, held queue and archive.

Run

cp parsimony.example.yaml parsimony.yaml
PARSIMONY_API_TOKEN=<token> go run ./cmd/parsimony -config parsimony.yaml

The API is disabled when PARSIMONY_API_TOKEN is not set.

Three listeners, each configurable:

Listener Default Purpose
lmtp 127.0.0.1:2424 mail from Postfix
api 127.0.0.1:8080 admin REST API, bearer token
web 127.0.0.1:8081 public archive and unsubscribe pages ("" disables)

Put the web listener behind a reverse proxy with TLS and set base_url to its public URL: the unsubscribe links in every message use it. Keep the api listener private.

curl -H "Authorization: Bearer $PARSIMONY_API_TOKEN" -d '{"name":"dev","domain":"example.org","title":"Dev"}' localhost:8080/api/v1/lists

Docker

The image runs as an unprivileged user (uid 65532) and works with a read-only root filesystem. Config is mounted read-only; the only writable path is the /data volume (the database).

docker build -t parsimony .
docker run -d --name parsimony --read-only --cap-drop ALL \
  -v parsimony-data:/data \
  -v $PWD/parsimony.yaml:/etc/parsimony/parsimony.yaml:ro \
  -e PARSIMONY_API_TOKEN=... -p 2424:2424 -p 8080:8080 -p 8081:8081 parsimony

Use db: /data/parsimony.db in the config. A new named volume gets the right ownership by itself; for a bind mount, make the host directory writable by uid 65532.

Delivery and the queue

LMTP answers 250 when the post is in the queue, so a down relay never bounces mail back to Postfix. It answers 451 only when the database itself fails.

  • Temporary relay errors (4xx, timeouts, connection failures) are retried with backoff.
  • A permanent rejection (5xx) drops that delivery. Only a bad-mailbox reply (5.1.x) counts as a hard bounce for the member; errors such as "relay access denied" never disable members.
  • Delivery is at-least-once: a crash between the relay accepting a message and the queue entry being removed can send one message to one recipient twice.
  • GET /api/v1/queue and the Queue page show what is pending or failing, and a stuck delivery can be discarded.

Admin UI

The UI is a single-page app in admin/, built into internal/adminui/dist and embedded in the binary. It is served on the API listener together with /api, so it needs no CORS, and only when PARSIMONY_API_TOKEN is set. You sign in with that token (kept in sessionStorage, gone when the tab closes).

make admin     # npm ci && npm run build
make build     # go build, embeds the UI
make test      # go test + vitest

Without make admin the binary still builds and the UI answers 503 with a hint. For frontend work run the daemon, then cd admin && npm run dev (Vite proxies /api to 127.0.0.1:8080).

Postfix

Deliver the list domains to parsimony over LMTP and keep the + extensions intact, for example:

transport_maps = hash:/etc/postfix/transport
# /etc/postfix/transport
lists.example.org  lmtp:inet:127.0.0.1:2424