Documentation · The Lagstyr handbook
Planning an installation
Lagstyr runs as one isolated deployment for one customer. Your team supplies the infrastructure, identity, credentials, integrations and recovery arrangements. The kernel controls authoritative writes; workers compute projections or carry out bounded work through their own interfaces. Host access is powerful administrative access and belongs in your organisation’s security model.
Read this part in order for a first installation. For an existing one, use routine operations, upgrades, recovery and incident response.
Establish the support boundary first
The release’s api/support-policy.json distinguishes the newest tag, standard.latestTag, from
the installable release, standard.currentRelease. Read the policy and docs/SUPPORTED-VERSIONS.md
supplied with the intended release before approving a deployment. A GitHub Latest badge or a
successful build does not establish support or recoverability.
At this handbook review, currentRelease is none: there is no supported production release.
Complete, signed candidate artifacts can support a clean-room exercise, but the installer refuses
unsupported tags by default. The candidate override is for an explicitly accepted exercise that
holds no customer data. It does not establish production readiness.
The implemented installation path is a source-free install kit on x86_64 NixOS 26.05, with
PostgreSQL 18 and pgcrypto, pg_trgm, btree_gist and pgvector at least 0.8.4. The NixOS module
builds pgvector from its pinned source because the host series’ default is below that floor.
The current installation schema admits the isolated-single-node topology and public and
internal data classes. Other platforms, topologies or data classes require a reviewed exception
and validation; the architectural possibility of another deployment shape does not make it a
supported installation path.
Assign the work
| Responsibility | What the owner must supply and retain |
|---|---|
| Engineering / operations | Host configuration, installation JSON, exact service selection, capacity, release/change records, monitoring and restore evidence. |
| Security / identity | TLS, OIDC issuer and MFA/group mapping, separate workload identities, secret custody, egress policy and access reviews. |
| Business authority | The founding authority-profile decision, accountable people, mandates, exact skill grants and approval routes. |
| Integration maintainer | Source meanings, provider API version, connector code/configuration, credentials, tests, reconciliation and support ownership. |
| Recovery custodians | Independent offsite media, two-person key retrieval and a second operator who can rebuild without the primary host. |
| Privacy / data owner | The data-home inventory, processor approvals, encryption choices, retention, holds and offboarding acceptance. |
One person may hold several responsibilities, but a two-person control still requires two people. Record who takes over during absence and who may authorise production cutover.
Design the installation boundary
Keep the kernel, worker, database and object-store traffic inside the installation-controlled network. In the collapsed deployment, application listeners use loopback. Publish only the intended TLS ingress; keep administrative access restricted. Never proxy the kernel’s loopback operational listener to the public network.
Use separate cloud/account or hardware, network, database, object namespace and backup-key boundaries for each customer. Isolation is by deployment. The database’s internal compatibility tenant value is neither the customer identity nor legal-entity isolation within one installation.
Choose the exact operating-package tuple from infra/install/operating-profiles.json. The offered
single-node tier provides recovery-based availability and carries no availability-percentage
promise. A standby, contracted continuity or an external paging service needs its own approved
design and evidence.
Size against the configured capacity profile and representative workload. Retain expected document and chunk counts, event growth, concurrent requests, queue-age budgets, disk/WAL growth and database connections. The example’s minima are admission inputs, not a sizing result for your corpus.
Decide what is ready
Keep a cutover record binding the release, configuration digest, as-built host/network state and named reviewers. It should include passing activation preflight, the password-authenticated runtime role confinement proof, required-unit and smoke results, live identity tests, integration acceptance, offsite restore/key-retrieval evidence and verified alert delivery. A second operator should perform the fresh-host exercise.
Infrastructure activation does not commission an agent, connector or model, and local tests do not prove independent recovery. Unresolved acceptance items keep the deployment in its agreed exercise scope. Proceed to Installing Lagstyr once the prerequisites and the intended scope are agreed.