# Operating a Haddon deployment What to run, when, and how to read the result. Every command here exits non-zero when something is wrong, so all of it works from cron or a release gate. Apart from the deployment section, which describes example configuration files for you to adapt, everything on this page is something `bin/` can run and `tests/` checks. ## Installing From a clone, into a virtual environment in the clone (the `bin/` scripts run `.venv/bin/python`): ``` python3 -m venv .venv && .venv/bin/pip install --upgrade pip && make install make web # build the reviewer bundle (needs Node.js) ``` Put hledger 1.52.1 at `vendor/hledger` if the deployment will export journals, over the API or with `bin/haddon-export`; see [hledger import, export and the oracle](/docs/hledger.md#the-pinned-binary). Without it `/readyz` answers `503` with the `verifier` check failing (so do not use `/readyz` as a load-balancer health check on such a deployment; `/healthz` is liveness only), and exports are refused. Everything else works. WeasyPrint, used for the PDF statements, needs Pango from the system package manager. ## Configuration `bin/haddon-serve` reads one JSON file, named by `--config` or `$HADDON_CONFIG`. Relative paths in it resolve against the directory the file is in. A minimal one: ```json { "entities": {"acme-holdings": "acme.db"}, "tokens": {"": {"actor": "agent:bookkeeper", "entities": ["acme-holdings"]}}, "cursor_keys": [{"id": "2026-09", "secret": ""}] } ``` | Key | What it is | Unset | |---|---|---| | `entities` | entity id → database file. One file is one entity, and the id must match the one stored in the file. | required | | `tokens` | bearer token → `{actor, entities}`. The actor is recorded verbatim on everything the token writes; `entities` is the scope. | no token can reach `/v1` | | `cursor_keys` | the pagination-cursor keyring, newest first: the first key signs, every key verifies. `cursor_secret` is the one-key spelling. | the service invents a key per process, so cursors break at every restart, and `/readyz` reports `not_ready` | | `proxy_auth` | `{header, entities, prefix?}`: lets a reverse proxy that has already authenticated a person pass who it was in `header`, recorded as `ui:`. Configure it **only** when nothing can reach the service without passing through that proxy. | the reviewer UI's API entrance (`/ui/v1`) has no credential | | `entity_root` | where `POST /v1/entities` creates new database files | `422 entity_root_unset` | | `blob_root` | the only directory `GET /documents/{id}/content` reads document bytes from | no document content is served | | `export_root` | where `POST /exports` writes journal files, one subdirectory per entity | `422 export_root_unset` | | `default_limit`, `max_limit`, `event_default_limit`, `event_max_limit` | page sizes | the published defaults | The configuration holds secrets (the tokens and the cursor keys). Keep it out of version control and readable only by the service's user. Three process settings are environment variables rather than configuration: | Variable | Meaning | |---|---| | `HADDON_CONFIG` | the configuration file, when `--config` is not given | | `HADDON_RECONCILIATION` | `off` switches the reconciliation extension off: its routes are not mounted, `/capabilities` does not advertise them, and its close checks are not asked | | `HADDON_CORPUS` | the corpus manifest the importer and the oracle verify against (not needed to serve) | `bin/haddon-serve --check --config ` opens every configured entity, prints the readiness report and exits 0 when ready, 1 when not, without binding a port. ## Adding a set of books One database file is one entity, so a new set of books means a new file that is migrated, provisioned and named in the service's configuration. You can do that over the API or on the machine itself. ### Over the API (an agent, or anyone with a token) ``` curl -X POST https:///v1/entities \ -H 'Authorization: Bearer ' -H 'Idempotency-Key: '"$(uuidgen)" \ -H 'Content-Type: application/json' -d '{ "entity_id": "acme-holdings", "legal_name": "Acme Holdings Ltd", "legal_form": "Ltd", "country": "GB", "base_currency": "GBP", "base_precision": 2}' ``` This is `initialize_entity`, the same command `bin/haddon-init` runs. It creates the file under `entity_root`, migrates it to head, provisions the entity and writes the new mapping back into the configuration file the service was started from, so the book survives a restart, and then serves it immediately. The reply is the same `EntitySummary` that `GET /v1/entities` lists. Two things in the configuration decide whether this is available at all. Without them the request is refused rather than half-done: | Key | Without it | |---|---| | `entity_root` | `422 entity_root_unset`: there is nowhere to put a database file. Leave it unset on a deployment whose entity map is managed by hand. | | a configuration *file* (`--config` / `$HADDON_CONFIG`) | `422 config_not_durable`: a service built from an in-process config has nowhere durable to register the entity. | The entity id is both the book's permanent address and the name of its file, so it has to be a plain slug of 1–63 lower-case letters, digits and hyphens. Anything else is refused before a file is created. Creating an id that already exists is `409`, not an update; retrying the *same* creation with the same `Idempotency-Key` replays the original `201`. `starter_chart` defaults to false, since a book you are about to import or author brings its own chart. The retained-earnings equity account is created either way, so the book can always take an opening balance. ### On the machine (the bootstrap) ``` bin/haddon-init var/acme.db --id acme-holdings --name "Acme Holdings Ltd" \ --legal-form Ltd --country GB --base-currency GBP --base-precision 2 ``` Then add `"acme-holdings": "acme.db"` to the configuration's `entities` map and restart. This is the path for the *first* book on a deployment. The configuration's `entities` map may not be empty, so a service has to have one before it can be asked for another. ## Exporting the journal Exports write the books out as hledger journal files. The bytes are deterministic, the pinned `hledger` binary checks them before anything is published, and an immutable `exports` row records each file and its `sha256`. You can run an export over the API or on the machine; both use the same function. ### Over the API (an agent, or the reviewer interface) ``` curl -X POST https:///v1/entities/acme-holdings/exports \ -H 'Authorization: Bearer ' -H 'Idempotency-Key: '"$(uuidgen)" \ -H 'Content-Type: application/json' -d '{"year": 2025}' ``` The body is the range and nothing else: `{}` exports the whole journal, `{"year": 2025}` is the calendar-year shorthand, and `{"from": "2025-01-01", "to": "2025-06-30"}` is any inclusive range with either side open. `{"overwrite": false}` asks to be refused rather than replacing an export already published for that range; the default is to replace it. The reply names the `exports` row, the snapshot, the `state_hash`, the verifier's verdict and one `href` per file. Fetch a file with an ordinary GET: ``` curl -O -J https:///v1/entities/acme-holdings/exports//artifacts/2025.journal \ -H 'Authorization: Bearer ' ``` | Key | Without it | |---|---| | `export_root` | `422 export_root_unset`: there is nowhere to write the files, and the route refuses rather than choosing a directory. Leave it unset on a deployment that exports only on the machine. | Files land in `export_root///