Install

Bookend runs entirely inside the bank’s network as Docker containers. Nothing is cloud-hosted; the only outbound calls the platform makes are the ones visible in Settings (core adapter endpoint, SMTP relay, metering heartbeat, and, only if configured, single sign-on and a template-suggestion model), and the heartbeat can be turned off. The Installation Guide (docs/guides/installation.md) explains every step below in full.

1. Sizing and prerequisites

Item	Reference
Host	Linux x86-64 (or Windows Server with Docker Desktop / WSL 2 for evaluation); 16 vCPU / 64 GB RAM / 500 GB SSD for the reference sizing, 4 vCPU / 16 GB / 100 GB is enough for a pilot
Docker	Engine 24+ with Compose v2.24.4 or later
Database	the bundled postgres:16-alpine service, or an existing Postgres 16+ / SQL Server 2019+ instance (DB__PROVIDER=sqlserver for SQL Server)
Network	one internal Docker network; only app-ui is published (port 8081 by default, 443 behind the bank’s TLS terminator)
Mail	an SMTP relay reachable from the host

2. Prepare the environment

1. Check bookend-<version>.tar.gz against its .sha256, unpack it, and verify the bundle per its VERIFY.md (sha256sum -c SHA256SUMS, then the minisign signature on SHA256SUMS). Load the images: docker load -i bookend-<version>-images.tar.
2. cp deploy/.env.example deploy/.env, restrict it to the service account, and set:
   • POSTGRES_PASSWORD (owner/migrator principal) and DB_APP_PASSWORD (least-privilege bookend_app principal). Replace both example values.
   • BOOKEND_MASTER_KEY: base64 of 32 random bytes (openssl rand -base64 32). This key encrypts every secret in settings (SMTP password, core credentials, the RS256 signing key). Store it in the bank’s secret vault; losing it means re-entering every secret and re-issuing every token.
   • BOOKEND_VERSION: the release version, exactly as the loaded images are tagged.
   • BOOKEND_SKIP_SCRIPTS=908_seed_demo_users.sql, so the evaluation user accounts are never created.
   • Proxy__TrustedNetworks: the load balancer’s network, if it is not in the private ranges.
3. Create deploy/compose.production.yml (Installation Guide, section 4): it withdraws the database and api ports, keeps the evaluation fixtures (jxchange-mock, metering-mock, mailhog) from starting, restores the production login limit and mounts the license public key Bookend provides (deploy/license-public.pem). For an external database add deploy/compose.external-db.yml from the same section and set DB__CONNECTION / DB__MIGRATOR_CONNECTION in deploy/.env.
4. TLS: put the bank’s certificate on the load balancer in front of app-ui:8080, or mount certificates and a listen 443 ssl server block through an nginx override. The load balancer must pass X-Forwarded-For and X-Forwarded-Proto; the api trusts those headers only from Proxy__TrustedNetworks. Keep app.public_url (wizard step 5) equal to the URL users type.

3. Start

docker compose -f deploy/compose.yml -f deploy/compose.production.yml up -d --wait
docker compose -f deploy/compose.yml -f deploy/compose.production.yml ps               # every service healthy; only app-ui has a host port
docker compose -f deploy/compose.yml -f deploy/compose.production.yml ps -a migrator   # "Exited (0)"

migrator applies the scripts in db/<dialect>/ forward-only and records each in schema_versions with a checksum; it refuses to run (exit 4) if an applied script changed or disappeared. api starts only after the migrator succeeded, and its /readyz reports schema unhealthy if the ledger lacks a script the build requires. The api runs as the non-root app user with the documents, exports and watch volumes.

4. Onboard

Open https://<host>/. A clean database lands on the onboarding wizard: administrator → institution → database preflight → SMTP (sends a real test email) → sign-in policy (public URL, token lifetimes, allowed email domains) → core adapter (file.export or jackhenry.jxchange) with a connection test → document sources (watch folder, package size cap, retention) → LAR mapping (preview against a sample, or skip) → licensing and metering (license key, metering endpoint, or air-gapped) → activate. Activation requires steps 1 to 6 and a passing SMTP test and core test. An administrator can reopen the wizard later (Settings → Other options, or POST /v1/setup/reopen).

5. Verify

• GET /readyz → healthy; GET /v1/diagnostics (administrator, also System → Diagnostics) → version, database and schema, license, metering, inference probe, jobs.
• Upload the validation pack’s golden package (validation-pack/golden-packages/BK-DEMO-001) through Loans → New loan; the pipeline reaches review with no findings and every value carries page provenance. Reject the test loan afterward.
• Send a metering heartbeat from System → Metering & license (or confirm air-gapped mode) and note the install id for support.
• Create the operational users (Users & access → invite; roles: specialist, manager, boarding checker, read-only auditor).

6. Day-2 pointers

upgrade.md (releases), backup-restore.md (what to back up and how to rehearse a restore), incident.md (what each alert means and the first commands to run), resilience.md (failure modes and the restore drill).