README
¶
wherefolk
A family directory service: a printable, shareable address book covering an extended family.
Wherefolk holds contact information for an extended family, records important dates, and makes familial relationships legible. It runs as a small HTTP service on a private Tailscale network — there is no public endpoint and no CLI.
See CONTEXT.md for the domain vocabulary and docs/adr/ for the decisions behind the current shape.
Running
The binary is a service, not a toolbox: it takes no arguments and is configured entirely from the environment.
| Variable | Default | Meaning |
|---|---|---|
WHEREFOLK_DATA |
/var/lib/wherefolk |
Directory holding directory.json |
WHEREFOLK_TEMPLATE |
/var/lib/wherefolk/template |
Directory holding directory.typ, the Typst layout. On disk rather than embedded so a layout tweak is a file edit and a restart — see ADR-0004. The container ships the template and sets this to /usr/local/share/wherefolk/template; mount over that path to override it |
WHEREFOLK_PORT |
8080 |
Port to listen on (the interface is fixed — see ADR-0007) |
WHEREFOLK_LOG_LEVEL |
info |
Log threshold: debug, info, warn, or error |
WHEREFOLK_FULL_PASSPHRASE |
(unset) | Passphrase that encrypts every Full-tier export. At least 8 characters, no surrounding whitespace. Unset leaves the Full tier unavailable rather than stopping the service. A secret: supply it from the host's agenix-managed .env, never from a file in git (§2.3) |
Container
Wherefolk is deployed as a container behind a Tailscale sidecar
(ADR-0006).
deploy/compose.yaml runs both, and
docs/operations/deployment.md walks the Operator from the Tailscale
admin console to the first start:
docker compose -f deploy/compose.yaml --env-file /run/agenix/wherefolk-env up -d
There is deliberately no published port. The service binds loopback only
(ADR-0001,
ADR-0007), so -p would
forward to an interface nothing listens on. The Tailscale sidecar shares the
container's network namespace and reaches the service over that same loopback,
which, given the runbook's 443-only ACL, makes tailscale serve the only way in.
Locally
mise run run # serves ./testdata on :8099
Then visit http://127.0.0.1:8099/status.
Data
A document is a JSON object with a schema version and a flat households array — not a nested
tree. Each Household carries its own id and an optional parent; the hierarchy is rebuilt from
those links at load time. testdata/directory.json is the canonical
example.
Development
nix develop # enter dev shell
mise run test # test
mise run lint # lint
mise run build # build with version ldflags
mise run snapshot # goreleaser build + container image, no push
Rendering needs the typst binary. nix develop provides it; outside that shell the
render tests skip rather than fail.
Releasing
Changes are described as changie fragments rather than edited into the changelog directly:
changie new # describe a change
mise run pre-release <major|minor|patch> # batch fragments, merge CHANGELOG, open a PR
mise run release # after merge: tag and push; CI publishes
License
MIT — see LICENSE
Documentation
¶
Overview ¶
Command wherefolk serves the family directory over HTTP.
The binary takes no arguments: it is a service, not a toolbox, so no argument can make it do anything other than serve (§2.2). Configuration comes from the environment; see internal/config.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package deploy holds the Operator's deployment artefacts — the compose file, the Tailscale Serve config and the secrets template — and the tests that pin the properties ADR-0001, ADR-0006 and ADR-0007 depend on.
|
Package deploy holds the Operator's deployment artefacts — the compose file, the Tailscale Serve config and the secrets template — and the tests that pin the properties ADR-0001, ADR-0006 and ADR-0007 depend on. |
|
internal
|
|
|
buildmeta
Package buildmeta provides build version information for wherefolk.
|
Package buildmeta provides build version information for wherefolk. |
|
config
Package config reads the service's settings from the environment.
|
Package config reads the service's settings from the environment. |
|
live
Package live holds the Directory the service is serving: the document, its Trash and the Editor's settings as last saved, the tree derived from them, and the one step Undo can return to.
|
Package live holds the Directory the service is serving: the document, its Trash and the Editor's settings as last saved, the tree derived from them, and the one step Undo can return to. |
|
render
Package render turns a Directory into a printable document.
|
Package render turns a Directory into a printable document. |
|
store
Package store persists the Directory as a single atomically-written JSON document and generates the stable identities its records carry.
|
Package store persists the Directory as a single atomically-written JSON document and generates the stable identities its records carry. |
|
web
Package web serves the Wherefolk UI over HTTP.
|
Package web serves the Wherefolk UI over HTTP. |
|
pkg
|
|
|
rolo
Package rolo holds the Directory's domain types: the Person and Household records, the Tree derived from their Parent links, and the normalisation and validation rules applied to them.
|
Package rolo holds the Directory's domain types: the Person and Household records, the Tree derived from their Parent links, and the normalisation and validation rules applied to them. |