Skip to content
LQMS
LQMS Deployment Guide
Initializing search
nburri/lqms
LQMS
nburri/lqms
Home
Evaluate LQMS
Evaluate LQMS
LQMS Known Limits
LQMS Security Posture
Architecture
Architecture
1. Introduction and Goals
2. Architecture Constraints
3. Context and Scope
4. Solution Strategy
5. Building Block View
6. Runtime View
7. Deployment View
8. Crosscutting Concepts
9. Architecture Decisions
10. Quality Requirements
11. Risks and Technical Debt
12. Glossary
The arrival bundle format
Decisions (ADRs)
Decisions (ADRs)
ADR-0001: Content-Addressed Document Storage with PostgreSQL as Source of Truth
ADR-0002: Single Instance with Scope Hierarchy and Copy-on-Derive
ADR-0003: Fixed Life Cycle States with Configurable Review Processes
ADR-0004: Global Catalogs for Roles and Document Types with Per-Scope Activation
ADR-0005: Modular Monolith
ADR-0006: Three-Layer Search with In-Database Index and Pluggable LLM
ADR-0007: Angular Frontend with Server-Side-Only Enforcement
ADR-0008: Flyway Migrations and jOOQ Codegen from the Migrated Schema
ADR-0009: RLS Enforcement via a Session-Scoped Authorized Scope Set
ADR-0010: Self-Managed QMS via an Internal Mandator
ADR-0011: Authentication via OIDC SSO with Server-Side (BFF) Sessions
ADR-0012: Permission-Based Authorization and System Bootstrap
ADR-0013: User Identity Lifecycle
ADR-0014: Electronic Signatures (Part 11 / Annex 11-Capable)
ADR-0015: Document Effectivity, Periodic Review & Validity
ADR-0016: Data Retention, Disposal & Privacy (FADP / GDPR)
ADR-0017: Multi-Part Version Content
ADR-0018: Non-Functional Targets (Capacity, Availability, Security)
ADR-0019: Notifications & Tasks
ADR-0020: Internationalization (Content Language, Time Zones, Formatting)
ADR-0021: General Typed Document Relationships
ADR-0022: Read-Acknowledgement & Questionnaires
ADR-0023: Migration / Import — Current Released State
ADR-0024: Draft / In-Review Cancellation
ADR-0025: Disposal & Erasure Mechanics (Storage, Index, Backups)
ADR-0026: RLS Runtime Safety — Connection-Pool Scope Isolation
ADR-0027: RLS Boundary — Content-Plane vs Control-Plane
ADR-0028: Stateless Encrypted Token-State Cookie (no server-side session store)
ADR-0029: Document Content Model — Draft-Freeze, Content-Table RLS, Append-Only Audit
ADR-0030: Review & Life-Cycle Realization Model
ADR-0031: Released-base readability enforcement & copy-on-derive mechanics
ADR-0032: Frontend realization — Quinoa, Angular Material, i18n & E2E
ADR-0033: CSRF control for the BFF session — SameSite + JSON content-type
ADR-0034: Notification realization — in-process domain events + system-context fan-out
ADR-0035: Fan-out contract as shipped — gate semantics, count disclosure, audit protocol
ADR-0036: Repository layer — services carry rules, repositories carry jOOQ
ADR-0037: Task scheduler — in-process tick, advisory-lock election, SQL sweep
ADR-0038: Periodic-review realization — derived due date, policy-gated confirmation
ADR-0039: Sweep & periodic-review contract as shipped — grants, guards, addressing
ADR-0040: Disposal-due surfacing — closure-anchored retention, scope-level legal hold
ADR-0041: Email channel & notification i18n — notification-as-outbox, structured messages
ADR-0042: Disposal execution — document tombstoning, single-actor hard-gated destruction
ADR-0043: Disposal blob deletion is post-commit, GC-backstopped
ADR-0044: Search FTS baseline — event-indexed, RLS-scoped search_index
ADR-0045: Image Attachments as Content Parts (Rich-Content Slice R2)
ADR-0046: Four-Eyes — Submitter Excluded from Approval
ADR-0047: Four-Eyes — Submitter-Only Exclusion
ADR-0048: Document Organization — Folder Tree per Scope
ADR-0049: Content Model Round 2 — Type Categories, Template Instantiation, Trace Relations, Completeness Rules
ADR-0050: Live Frontend — SSE State Push, CodeMirror 6, Draft Presence
ADR-0051: In-Text Document Links (doc: Scheme)
ADR-0052: Addressees & Read-Acknowledgement (REQ-TRN Realization)
ADR-0053: Addressees Per Document + Process Owner (amends ADR-0052 K-1)
ADR-0054: Process Owner Is a Role (amends ADR-0053 P-3)
ADR-0055: WYSIWYG Editing Mode over Markdown (editor step R4)
ADR-0056: Visual-Editor Chrome via Milkdown Crepe (gated adoption)
ADR-0057: Content Record Is the ProseMirror Document Tree; Markdown Becomes a Derived Projection
ADR-0058: PM_DOC Is the Only Content Format (pre-production cut; amends ADR-0057 §5)
ADR-0059: Editor Engine Switches to TipTap (spike-gated; supersedes the Milkdown/Crepe choice)
ADR-0060: Backup & Restore — Scripted Ordered Backup with Automated Restore Rehearsal
ADR-0061: CSV — Generated Validation Package per Release
ADR-0062: SBOM — CycloneDX over the Production Layers, Validated Against the Artifact
ADR-0063: User Identity Binds on Subject Only (Issuer Becomes Provenance)
ADR-0064: Per-Document Workflow Role Bindings (Author / Reviewer / Releaser), Enforced
ADR-0065: Diagrams — Excalidraw as the Manual Layer, Mermaid Stays for Text-First/UML
ADR-0066: WITHDRAW — the Author Side May Reclaim a Version from Review
ADR-0067: Review Comments — Anchored, Immutable, Resolvable
ADR-0068: Confluence/Jira QMS Import — Staged, Read-Only, Repeatable
ADR-0069: Arbitrary File Attachments — Download-Only Confinement
ADR-0070: Training Questionnaires — Versioned, Auto-Scored, Release-Gated
ADR-0071: Training Plans — Document Obligations + External Trainings & Certifications
ADR-0072: Diagrams — Self-Hosted draw.io Replaces Excalidraw
ADR-0073: Per-Scope QMS Configuration Surface
ADR-0074: PDF Export of Released Documents — Server-Side via Apache FOP over the Canonical Projection
ADR-0075: Source History Import — Continuity Without Forged Audit
ADR-0076: Periodic-review status visibility (completing MVP gap #2)
ADR-0077: Requirement Items — Keyed Blocks Inside Controlled Documents
ADR-0078: Generalized Trace Items (Traceability Model — Stage A)
ADR-0079: Risk & Risk-Control Items (Traceability Model — Stage B)
ADR-0080: Traceability Workspace — Hub, Sub-Pages, and Role-Gated Views
ADR-0081: Draft-Only Trace-Structure Changes, Server-Enforced
ADR-0082: Table-Shaped Risk Authoring over Risk Blocks
ADR-0083: The TD Dossier — a Versioned, Cross-Scope, Regulatory-Structured Deliverable
ADR-0084: Validation & Regulatory Axes (Traceability Model — Stage C)
ADR-0085: Relation-Layer Consolidation — One Trace Vocabulary, One Surface
ADR-0086: Requirement Traceability Chains — End-to-End Path View + Flat Path Export
ADR-0087: The Scope Traceability Report — One Derived Overview Artifact, Never a Controlled Document
ADR-0088: Verification Evidence Classes — Planned vs. Verified, Derived at the Read Layer
ADR-0089: Recurring Obligations — Periodic Tasks With Record Evidence, Not Calendar Series
ADR-0090: Release & Versioning Policy — Deliberate Releases, One Auditor-Facing Number
ADR-0091: Release Modes — Single-Person Record Release With a Structural Four-Eyes Floor
ADR-0092: Orphan-Blob Garbage Collection With a Quarantine Bin
ADR-0093: One Scope Context — the Toolbar Switcher Is the Only Scope Selector
ADR-0094: Calendar-Anchored Obligation Schedules (Clamped, Never Too Late)
ADR-0095: Key-Rule Governance — Free Until First Use, Then Frozen
ADR-0096: Transition Permissions — Always Visible, Deny Unless Granted
ADR-0097: A Governed Provisioning Surface — MANAGE_SCOPES
ADR-0098: Org Chart × Role System — Marriage at the Evidence Level, Never in Authorization
ADR-0099: The User Manual is an In-App Topic Reference, Not a Document
ADR-0100: LQMS Is the Living Quality Management System
ADR-0101: The Executable Validation Journey (PQ Evidence That Cannot Drift)
ADR-0102: Typed Template Variables (text | date | number — and Deliberately No Enum)
ADR-0103: npm audit Joins the Verification Gate as a Second Standing Input
ADR-0104: The Issued Dossier Is a Persisted Artifact of Record — and Clones to a New Draft
ADR-0105: Navigation Information Architecture — Group by Moment-of-Use
ADR-0106: The Client Reflection Follows Assignments, Not Only Content Reach
ADR-0107: The Audit Append Gate Follows Assignment Reach, Not Content Reach
ADR-0108: Mandator Membership — Invite-Accept, with Pre-Assigned Responsibilities
ADR-0109: Organization Founding Is Its Own Process
ADR-0110: The Audit Trail Is Not a Read Model
ADR-0111: The Imported-Person Model, and Project Portability's First Doctrines
ADR-0112: The Element-Kind Catalog — Semantics in the Model, Not Only in the Code
ADR-0113: Project Arrival Import — Records Arrive as They Are, People Arrive as They Were
ADR-0114: The Operating Model Arrives — Roles as Functions, Names as Words, People as This Instance's Decision
ADR-0115: Collaborative Draft Editing — Two Carets, One Truth, Honest Credit
ADR-0116: The System Maintenance Surface — the App Backs Itself Up, the Host Keeps One Dumb Job
ADR-0117: Role Documentation — a Link, a Finding, Per-Source Recognizers; Substitution Rejected
ADR-0118: The Offline QMS Copy — the Repo Carries the Audit Pack, Not a Second Renderer
ADR-0119: Module-Internal Package Structure — Capabilities First, Layers Second, the Root Is the Surface
ADR-0120: The Shared Kernel — the Domain-Exception Vocabulary Leaves the Authorization Module
ADR-0121: The Project Administrator Role — Per-Scope Administration With Read Access, Seeded in the Base Catalog
ADR-0122: Organization-Level Administration — the Cascade Stays, Becomes Visible, and Founds Projects
ADR-0123: Draft Save-Points — Every Save Restorable, Kept for the Life of the Version
ADR-0124: The Birth Path Completes Without Borrowing Content Clothes
ADR-0125: The Export Twin — Export Emits an Arrival Bundle
ADR-0126: Project Dissolution — the Un-Birth of an Unused Scope
ADR-0127: The Base-QMS Layers — One Library, Derived Adaptations, Local Records
ADR-0128: The GLOBAL Cascade Carries Administration, Never Content
ADR-0129: Role Identity from a GLOBAL Assignment Acts in GLOBAL Alone
ADR-0130: Break-Glass — the Project Administrator's Escalation Is a First-Class, Witnessed, Self-Expiring Act
ADR-0131: Role Substitution as Declared Adoption Edges — Emergency Cover Is Governed, Own-Name, Timed Staffing
ADR-0132: Dual-Hat Reviewer Satisfaction Is a Declared Policy Choice — the Strict Floor Stays the Default
ADR-NNNN:
</span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" > <div class="md-nav__link md-nav__container"> <a href="../../requirements/" class="md-nav__link "> <span class="md-ellipsis"> Requirements </span> </a> <label class="md-nav__link " for="__nav_5" id="__nav_5_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_5"> <span class="md-nav__icon md-icon"></span> Requirements </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../requirements/stakeholder_requirements/" class="md-nav__link"> <span class="md-ellipsis"> Stakeholder Requirements </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/gap-analysis/" class="md-nav__link"> <span class="md-ellipsis"> Requirements Gap Analysis </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_admin/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Administration, Permissions & Onboarding </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_api_ui/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: API & User Interface </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_audit_reporting/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Audit Trail & Regulatory Reporting </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_auth/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Authentication & Session </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_backup/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Backup & Restore </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_catalogs/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Catalogs, Roles & Users </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_data_protection/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Data Protection, Retention & Disposal </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_documents/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Documents, Versions & Storage </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_dossiers/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Technical Documentation Dossiers </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_effectivity/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Effectivity, Periodic Review & Validity </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_gspr/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Regulatory Conformity (GSPR / Essential Principles) </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_i18n/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Internationalization </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_lifecycle/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Life Cycle & Reviews </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_memberships/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Mandator Membership & Invitations </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_migration/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Migration & Import </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_nfr/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Non-Functional </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_notifications/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Notifications & Tasks </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_obligations/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Recurring Obligations </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_relationships/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Document Relationships </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_risk/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Risk Management (ISO 14971 Hazards & Controls) </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_sbom/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Software Bill of Materials & Supply-Chain Assurance </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_search/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Search </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_separation/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Scopes, Mandators & Separation </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_signatures/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Electronic Signatures </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_training/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Read-Acknowledgement & Questionnaires </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_users/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: User Identity & Lifecycle </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_validation/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Design Validation & the Validation Traceability Axis </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6" > <div class="md-nav__link md-nav__container"> <a href="../../process/" class="md-nav__link "> <span class="md-ellipsis"> Process (IEC 62304) </span> </a> <label class="md-nav__link " for="__nav_6" id="__nav_6_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_6"> <span class="md-nav__icon md-icon"></span> Process (IEC 62304) </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../process/configuration_management_plan/" class="md-nav__link"> <span class="md-ellipsis"> Configuration Management Plan </span> </a> </li> <li class="md-nav__item"> <a href="../../process/problem_resolution/" class="md-nav__link"> <span class="md-ellipsis"> Problem Resolution Process </span> </a> </li> <li class="md-nav__item"> <a href="../../process/risk_management/" class="md-nav__link"> <span class="md-ellipsis"> Risk Management </span> </a> </li> <li class="md-nav__item"> <a href="../../process/software_development_plan/" class="md-nav__link"> <span class="md-ellipsis"> Software Development Plan </span> </a> </li> <li class="md-nav__item"> <a href="../../process/verification_plan/" class="md-nav__link"> <span class="md-ellipsis"> Verification Plan </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--active md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_7" checked> <label class="md-nav__link" for="__nav_7" id="__nav_7_label" tabindex="0"> <span class="md-ellipsis"> Operations </span> <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_7_label" aria-expanded="true"> <label class="md-nav__title" for="__nav_7"> <span class="md-nav__icon md-icon"></span> Operations </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../genesis-installation/" class="md-nav__link"> <span class="md-ellipsis"> Genesis: Birthing an LQMS Installation with a Base Library </span> </a> </li> <li class="md-nav__item md-nav__item--active"> <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc"> <label class="md-nav__link md-nav__link--active" for="__toc"> <span class="md-ellipsis"> LQMS Deployment Guide </span> <span class="md-nav__icon md-icon"></span> </label> <a href="./" class="md-nav__link md-nav__link--active"> <span class="md-ellipsis"> LQMS Deployment Guide </span> </a> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#1-prerequisites" class="md-nav__link"> <span class="md-ellipsis"> 1. Prerequisites </span> </a> </li> <li class="md-nav__item"> <a href="#2-building-the-production-image" class="md-nav__link"> <span class="md-ellipsis"> 2. Building the production image </span> </a> <nav class="md-nav" aria-label="2. Building the production image"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#buildversion-stamp-git_sha-stale-deployment-detector" class="md-nav__link"> <span class="md-ellipsis"> Build/version stamp (GIT_SHA, stale-deployment detector) </span> </a> </li> <li class="md-nav__item"> <a href="#the-jooq-build-time-docker-dependency-important" class="md-nav__link"> <span class="md-ellipsis"> The jOOQ build-time Docker dependency (important) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#3-deployment-topology" class="md-nav__link"> <span class="md-ellipsis"> 3. Deployment topology </span> </a> </li> <li class="md-nav__item"> <a href="#4-database-roles-and-the-bypassrls-requirement-read-this" class="md-nav__link"> <span class="md-ellipsis"> 4. Database roles and the BYPASSRLS requirement (READ THIS) </span> </a> <nav class="md-nav" aria-label="4. Database roles and the BYPASSRLS requirement (READ THIS)"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#why-it-matters-adr-0035-7-adr-00020009" class="md-nav__link"> <span class="md-ellipsis"> Why it matters (ADR-0035 §7, ADR-0002/0009) </span> </a> </li> <li class="md-nav__item"> <a href="#minimum-setup--the-migration-role" class="md-nav__link"> <span class="md-ellipsis"> Minimum setup — the migration role </span> </a> </li> <li class="md-nav__item"> <a href="#current-single-datasource-reality" class="md-nav__link"> <span class="md-ellipsis"> Current single-datasource reality </span> </a> </li> <li class="md-nav__item"> <a href="#two-role-hardening-recommended-for-production" class="md-nav__link"> <span class="md-ellipsis"> Two-role hardening (recommended for production) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#5-configuration-reference" class="md-nav__link"> <span class="md-ellipsis"> 5. Configuration reference </span> </a> <nav class="md-nav" aria-label="5. Configuration reference"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#51-datasource" class="md-nav__link"> <span class="md-ellipsis"> 5.1 Datasource </span> </a> </li> <li class="md-nav__item"> <a href="#52-flyway-schema-migrations" class="md-nav__link"> <span class="md-ellipsis"> 5.2 Flyway (schema migrations) </span> </a> </li> <li class="md-nav__item"> <a href="#53-http--rest-boundary" class="md-nav__link"> <span class="md-ellipsis"> 5.3 HTTP / REST boundary </span> </a> </li> <li class="md-nav__item"> <a href="#54-frontend-quinoa-adr-0032" class="md-nav__link"> <span class="md-ellipsis"> 5.4 Frontend (Quinoa, ADR-0032) </span> </a> </li> <li class="md-nav__item"> <a href="#55-authentication--oidc-adr-001100280033-req-auth-" class="md-nav__link"> <span class="md-ellipsis"> 5.5 Authentication / OIDC (ADR-0011/0028/0033, REQ-AUTH-*) </span> </a> </li> <li class="md-nav__item"> <a href="#56-keycloak-dev-services-testdev-only--ignore-in-prod" class="md-nav__link"> <span class="md-ellipsis"> 5.6 Keycloak Dev Services (test/dev only — ignore in prod) </span> </a> </li> <li class="md-nav__item"> <a href="#57-system-bootstrap-adr-0012--see-7" class="md-nav__link"> <span class="md-ellipsis"> 5.7 System bootstrap (ADR-0012) — see §7 </span> </a> </li> <li class="md-nav__item"> <a href="#58-content-store-adr-0001" class="md-nav__link"> <span class="md-ellipsis"> 5.8 Content store (ADR-0001) </span> </a> </li> <li class="md-nav__item"> <a href="#59-overdue-task-sweep-adr-0037-req-not-004--see-9" class="md-nav__link"> <span class="md-ellipsis"> 5.9 Overdue-task sweep (ADR-0037, REQ-NOT-004) — see §9 </span> </a> </li> <li class="md-nav__item"> <a href="#510-notification-email-adr-0041--see-8" class="md-nav__link"> <span class="md-ellipsis"> 5.10 Notification email (ADR-0041) — see §8 </span> </a> </li> <li class="md-nav__item"> <a href="#511-runtime-postgresql-session-variables-not-config-keys" class="md-nav__link"> <span class="md-ellipsis"> 5.11 Runtime PostgreSQL session variables (not config keys) </span> </a> </li> <li class="md-nav__item"> <a href="#512-spa-cache-headers-stale-bundle-prevention" class="md-nav__link"> <span class="md-ellipsis"> 5.12 SPA cache headers (stale-bundle prevention) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#6-idp-integration-real-deployment" class="md-nav__link"> <span class="md-ellipsis"> 6. IdP integration (real deployment) </span> </a> </li> <li class="md-nav__item"> <a href="#7-bootstrap-admin-flow-adr-0012" class="md-nav__link"> <span class="md-ellipsis"> 7. Bootstrap admin flow (ADR-0012) </span> </a> </li> <li class="md-nav__item"> <a href="#8-email-enablement-adr-0041--backlog-note-adr-0043" class="md-nav__link"> <span class="md-ellipsis"> 8. Email enablement (ADR-0041) + backlog note (ADR-0043) </span> </a> </li> <li class="md-nav__item"> <a href="#9-sweep-tuning-adr-0037" class="md-nav__link"> <span class="md-ellipsis"> 9. Sweep tuning (ADR-0037) </span> </a> </li> <li class="md-nav__item"> <a href="#10-upgrade-path" class="md-nav__link"> <span class="md-ellipsis"> 10. Upgrade path </span> </a> </li> <li class="md-nav__item"> <a href="#11-backup--retention-window-adr-0025--adr-0016" class="md-nav__link"> <span class="md-ellipsis"> 11. Backup & retention window (ADR-0025 / ADR-0016) </span> </a> </li> <li class="md-nav__item"> <a href="#12-verifying-a-deployment" class="md-nav__link"> <span class="md-ellipsis"> 12. Verifying a deployment </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../server-deployment/" class="md-nav__link"> <span class="md-ellipsis"> LQMS Server Deployment (single Linux host, public HTTPS) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8" > <div class="md-nav__link md-nav__container"> <a href="../../traceability/" class="md-nav__link "> <span class="md-ellipsis"> Traceability </span> </a> <label class="md-nav__link " for="__nav_8" id="__nav_8_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_8_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8"> <span class="md-nav__icon md-icon"></span> Traceability </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../traceability/matrix/" class="md-nav__link"> <span class="md-ellipsis"> Requirements Traceability Matrix </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_9" > <div class="md-nav__link md-nav__container"> <a href="../../validation/" class="md-nav__link "> <span class="md-ellipsis"> Validation (tool lane) </span> </a> <label class="md-nav__link " for="__nav_9" id="__nav_9_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_9_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_9"> <span class="md-nav__icon md-icon"></span> Validation (tool lane) </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../validation/templates/ai-authorship-posture/" class="md-nav__link"> <span class="md-ellipsis"> AI-Authorship Posture — How LQMS Is Built, and Why the Validation Evidence Does Not Rest on It (TEMPLATE) </span> </a> </li> <li class="md-nav__item"> <a href="../../validation/templates/intended-use/" class="md-nav__link"> <span class="md-ellipsis"> Intended-Use Specification — LQMS as a QMS / Document-Control Tool (TEMPLATE) </span> </a> </li> <li class="md-nav__item"> <a href="../../validation/templates/tool-risk-assessment/" class="md-nav__link"> <span class="md-ellipsis"> Tool-Risk Assessment — LQMS as a QMS Tool (TEMPLATE) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10" > <label class="md-nav__link" for="__nav_10" id="__nav_10_label" tabindex="0"> <span class="md-ellipsis"> Regulatory </span> <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_10"> <span class="md-nav__icon md-icon"></span> Regulatory </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../regulatory/mdr-annex-i-skeleton/" class="md-nav__link"> <span class="md-ellipsis"> MDR Annex I — GSPR authoring skeleton (paraphrased) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" > <div class="md-nav__link md-nav__container"> <a href="../../user-guide/" class="md-nav__link "> <span class="md-ellipsis"> User guide </span> </a> <label class="md-nav__link " for="__nav_11" id="__nav_11_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_11"> <span class="md-nav__icon md-icon"></span> User guide </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../user-guide/tutorial/" class="md-nav__link"> <span class="md-ellipsis"> Tutorial — from zero to a released document </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/administration/" class="md-nav__link"> <span class="md-ellipsis"> Administering an LQMS Installation </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/diagrams/" class="md-nav__link"> <span class="md-ellipsis"> Diagrams </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/documents-lifecycle/" class="md-nav__link"> <span class="md-ellipsis"> Documents & the Lifecycle </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/exports/" class="md-nav__link"> <span class="md-ellipsis"> PDF Exports & the Audit Pack </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/obligations/" class="md-nav__link"> <span class="md-ellipsis"> Recurring Obligations </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/project-context/" class="md-nav__link"> <span class="md-ellipsis"> The Project Context & App Version </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/review-comments/" class="md-nav__link"> <span class="md-ellipsis"> Review Comments </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/activity-trail/" class="md-nav__link"> <span class="md-ellipsis"> Who did what, when — reading a project's activity </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/admin-scopes/" class="md-nav__link"> <span class="md-ellipsis"> Renaming a project, and what can never change </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/authority-view/" class="md-nav__link"> <span class="md-ellipsis"> Who holds each function here, and what may it do </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/break-glass/" class="md-nav__link"> <span class="md-ellipsis"> The permission I need is held by a role I do not hold — what now? </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/coverage-and-chains/" class="md-nav__link"> <span class="md-ellipsis"> Coverage or chains? — which requirement view answers your question </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/credentials/" class="md-nav__link"> <span class="md-ellipsis"> Your password: changing it, resetting it — and why LQMS never sees it </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/emergency-cover/" class="md-nav__link"> <span class="md-ellipsis"> Who may cover for whom here — declaring emergency cover, and reading where the glass was broken </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/key-rules/" class="md-nav__link"> <span class="md-ellipsis"> Special elements: what a project declares, and when its names freeze </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/memberships/" class="md-nav__link"> <span class="md-ellipsis"> Belonging to an organization: invitations, acceptance, and what they change </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/provisioning-birth-path/" class="md-nav__link"> <span class="md-ellipsis"> How a new organization and project are born </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/review-policies/" class="md-nav__link"> <span class="md-ellipsis"> What a review policy controls, and what an empty grant means </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/setup-wizard-lanes/" class="md-nav__link"> <span class="md-ellipsis"> The setup wizard: the lanes, and what it writes </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/staffing-and-assignments/" class="md-nav__link"> <span class="md-ellipsis"> Staffing people into roles, and the accountable holder </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/technical-dossier/" class="md-nav__link"> <span class="md-ellipsis"> How do I assemble a technical dossier? </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/trace-items/" class="md-nav__link"> <span class="md-ellipsis"> Trace Items — Requirements, Risks & Risk Controls </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/trace-links/" class="md-nav__link"> <span class="md-ellipsis"> Trace Links & the Suspect Cycle </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/traceability-workspace/" class="md-nav__link"> <span class="md-ellipsis"> The Traceability Workspace </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/training/" class="md-nav__link"> <span class="md-ellipsis"> Training & Acknowledgements </span> </a> </li> </ul> </nav> </li> </ul> </nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" > <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner"> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#1-prerequisites" class="md-nav__link"> <span class="md-ellipsis"> 1. Prerequisites </span> </a> </li> <li class="md-nav__item"> <a href="#2-building-the-production-image" class="md-nav__link"> <span class="md-ellipsis"> 2. Building the production image </span> </a> <nav class="md-nav" aria-label="2. Building the production image"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#buildversion-stamp-git_sha-stale-deployment-detector" class="md-nav__link"> <span class="md-ellipsis"> Build/version stamp (GIT_SHA, stale-deployment detector) </span> </a> </li> <li class="md-nav__item"> <a href="#the-jooq-build-time-docker-dependency-important" class="md-nav__link"> <span class="md-ellipsis"> The jOOQ build-time Docker dependency (important) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#3-deployment-topology" class="md-nav__link"> <span class="md-ellipsis"> 3. Deployment topology </span> </a> </li> <li class="md-nav__item"> <a href="#4-database-roles-and-the-bypassrls-requirement-read-this" class="md-nav__link"> <span class="md-ellipsis"> 4. Database roles and the BYPASSRLS requirement (READ THIS) </span> </a> <nav class="md-nav" aria-label="4. Database roles and the BYPASSRLS requirement (READ THIS)"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#why-it-matters-adr-0035-7-adr-00020009" class="md-nav__link"> <span class="md-ellipsis"> Why it matters (ADR-0035 §7, ADR-0002/0009) </span> </a> </li> <li class="md-nav__item"> <a href="#minimum-setup--the-migration-role" class="md-nav__link"> <span class="md-ellipsis"> Minimum setup — the migration role </span> </a> </li> <li class="md-nav__item"> <a href="#current-single-datasource-reality" class="md-nav__link"> <span class="md-ellipsis"> Current single-datasource reality </span> </a> </li> <li class="md-nav__item"> <a href="#two-role-hardening-recommended-for-production" class="md-nav__link"> <span class="md-ellipsis"> Two-role hardening (recommended for production) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#5-configuration-reference" class="md-nav__link"> <span class="md-ellipsis"> 5. Configuration reference </span> </a> <nav class="md-nav" aria-label="5. Configuration reference"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#51-datasource" class="md-nav__link"> <span class="md-ellipsis"> 5.1 Datasource </span> </a> </li> <li class="md-nav__item"> <a href="#52-flyway-schema-migrations" class="md-nav__link"> <span class="md-ellipsis"> 5.2 Flyway (schema migrations) </span> </a> </li> <li class="md-nav__item"> <a href="#53-http--rest-boundary" class="md-nav__link"> <span class="md-ellipsis"> 5.3 HTTP / REST boundary </span> </a> </li> <li class="md-nav__item"> <a href="#54-frontend-quinoa-adr-0032" class="md-nav__link"> <span class="md-ellipsis"> 5.4 Frontend (Quinoa, ADR-0032) </span> </a> </li> <li class="md-nav__item"> <a href="#55-authentication--oidc-adr-001100280033-req-auth-" class="md-nav__link"> <span class="md-ellipsis"> 5.5 Authentication / OIDC (ADR-0011/0028/0033, REQ-AUTH-*) </span> </a> </li> <li class="md-nav__item"> <a href="#56-keycloak-dev-services-testdev-only--ignore-in-prod" class="md-nav__link"> <span class="md-ellipsis"> 5.6 Keycloak Dev Services (test/dev only — ignore in prod) </span> </a> </li> <li class="md-nav__item"> <a href="#57-system-bootstrap-adr-0012--see-7" class="md-nav__link"> <span class="md-ellipsis"> 5.7 System bootstrap (ADR-0012) — see §7 </span> </a> </li> <li class="md-nav__item"> <a href="#58-content-store-adr-0001" class="md-nav__link"> <span class="md-ellipsis"> 5.8 Content store (ADR-0001) </span> </a> </li> <li class="md-nav__item"> <a href="#59-overdue-task-sweep-adr-0037-req-not-004--see-9" class="md-nav__link"> <span class="md-ellipsis"> 5.9 Overdue-task sweep (ADR-0037, REQ-NOT-004) — see §9 </span> </a> </li> <li class="md-nav__item"> <a href="#510-notification-email-adr-0041--see-8" class="md-nav__link"> <span class="md-ellipsis"> 5.10 Notification email (ADR-0041) — see §8 </span> </a> </li> <li class="md-nav__item"> <a href="#511-runtime-postgresql-session-variables-not-config-keys" class="md-nav__link"> <span class="md-ellipsis"> 5.11 Runtime PostgreSQL session variables (not config keys) </span> </a> </li> <li class="md-nav__item"> <a href="#512-spa-cache-headers-stale-bundle-prevention" class="md-nav__link"> <span class="md-ellipsis"> 5.12 SPA cache headers (stale-bundle prevention) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#6-idp-integration-real-deployment" class="md-nav__link"> <span class="md-ellipsis"> 6. IdP integration (real deployment) </span> </a> </li> <li class="md-nav__item"> <a href="#7-bootstrap-admin-flow-adr-0012" class="md-nav__link"> <span class="md-ellipsis"> 7. Bootstrap admin flow (ADR-0012) </span> </a> </li> <li class="md-nav__item"> <a href="#8-email-enablement-adr-0041--backlog-note-adr-0043" class="md-nav__link"> <span class="md-ellipsis"> 8. Email enablement (ADR-0041) + backlog note (ADR-0043) </span> </a> </li> <li class="md-nav__item"> <a href="#9-sweep-tuning-adr-0037" class="md-nav__link"> <span class="md-ellipsis"> 9. Sweep tuning (ADR-0037) </span> </a> </li> <li class="md-nav__item"> <a href="#10-upgrade-path" class="md-nav__link"> <span class="md-ellipsis"> 10. Upgrade path </span> </a> </li> <li class="md-nav__item"> <a href="#11-backup--retention-window-adr-0025--adr-0016" class="md-nav__link"> <span class="md-ellipsis"> 11. Backup & retention window (ADR-0025 / ADR-0016) </span> </a> </li> <li class="md-nav__item"> <a href="#12-verifying-a-deployment" class="md-nav__link"> <span class="md-ellipsis"> 12. Verifying a deployment </span> </a> </li> </ul> </nav> </div> </div> </div> <div class="md-content" data-md-component="content"> <article class="md-content__inner md-typeset"> <a href="https://github.com/nburri/lqms/edit/main/docs/operations/deployment.md" title="Edit this page" class="md-content__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M10 20H6V4h7v5h5v3.1l2-2V8l-6-6H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h4zm10.2-7c.1 0 .3.1.4.2l1.3 1.3c.2.2.2.6 0 .8l-1 1-2.1-2.1 1-1c.1-.1.2-.2.4-.2m0 3.9L14.1 23H12v-2.1l6.1-6.1z"/></svg> </a> <h1 id="lqms-deployment-guide">LQMS Deployment Guide<a class="headerlink" href="#lqms-deployment-guide" title="Permanent link">¶</a></h1> <p>Operator-facing guide for deploying LQMS (Kotlin/Quarkus backend, PostgreSQL/jOOQ, OIDC auth, Quinoa-bundled Angular SPA). It covers the production container, database roles, the security-critical BYPASSRLS requirement, every configuration key, IdP integration, the bootstrap admin flow, email enablement, backup retention, sweep tuning, and upgrades.</p> <p>For a ready-to-run local stack (app + PostgreSQL + Keycloak) see <a href="https://github.com/nburri/lqms/tree/main/deploy"><code>../../deploy/</code></a>: <code>deploy/docker-compose.yml</code>, <code>deploy/README.md</code>, and the <code>deploy/smoke.sh</code> end-to-end check.</p> <blockquote> <p><strong>Scope note.</strong> The bundled <code>deploy/</code> compose stack is a demo/colleague-feedback topology with demo secrets and a single BYPASSRLS datasource. Everything in this guide marked <strong>hardening</strong> is what you additionally do for a real deployment.</p> </blockquote> <hr /> <h2 id="1-prerequisites">1. Prerequisites<a class="headerlink" href="#1-prerequisites" title="Permanent link">¶</a></h2> <ul> <li><strong>Runtime:</strong> Docker (or any OCI runtime / Kubernetes). The image is a Quarkus JVM fast-jar on <code>eclipse-temurin:25-jre-noble</code>; no JDK/Gradle/Node needed at runtime.</li> <li><strong>PostgreSQL 18</strong> reachable from the app, with a role that can bypass RLS for migrations (§4).</li> <li><strong>An OIDC provider</strong> (a corporate IdP, or the bundled Keycloak) — see §6.</li> <li><strong>Persistent storage</strong> for the content blob store (§5, <code>lqms.storage.root</code>) and the database.</li> <li><strong>Build-time only</strong> (to produce the image): Docker + JDK 21 + Node, plus outbound HTTPS to Maven Central, the Gradle distribution service, and the npm registry. See §2.</li> </ul> <hr /> <h2 id="2-building-the-production-image">2. Building the production image<a class="headerlink" href="#2-building-the-production-image" title="Permanent link">¶</a></h2> <blockquote> <p><strong>The reference server deployment does not use this section.</strong> Since 2026-08-06 CI publishes the image to <code>ghcr.io/nburri/lqms</code> on every release tag and the server <em>pulls</em> it — see <a href="../server-deployment/"><code>server-deployment.md</code></a> §4. What follows is the mechanics of building the image by hand: the CI job does exactly this, and it is still the path for an air-gapped target or a registry outage.</p> </blockquote> <p><code>deploy/Dockerfile</code> is multi-stage:</p> <ol> <li><strong>build</strong> — JDK 21 + Gradle (via the wrapper) + Node 22. Runs <code>./gradlew :backend:api:quarkusBuild -Dquarkus.quinoa=true</code>, which compiles the backend, builds the Angular SPA (Quinoa, ADR-0032), and assembles the Quarkus fast-jar with the SPA bundled under <code>META-INF/resources</code>.</li> <li><strong>runtime</strong> — <code>eclipse-temurin:25-jre-noble</code>, runs <code>java -jar /app/quarkus-run.jar</code> as a non-root user.</li> </ol> <div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="c1"># from the repo root</span> <a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>./gradlew<span class="w"> </span>:backend:persistence:generateJooq<span class="w"> </span><span class="c1"># one-time / after migration changes — see below</span> <a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>docker<span class="w"> </span>build<span class="w"> </span>-f<span class="w"> </span>deploy/Dockerfile<span class="w"> </span>--build-arg<span class="w"> </span><span class="nv">GIT_SHA</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>git<span class="w"> </span>rev-parse<span class="w"> </span>--short<span class="w"> </span>HEAD<span class="k">)</span><span class="s2">"</span><span class="w"> </span>-t<span class="w"> </span>lqms:latest<span class="w"> </span>. </code></pre></div> <h3 id="buildversion-stamp-git_sha-stale-deployment-detector">Build/version stamp (<code>GIT_SHA</code>, stale-deployment detector)<a class="headerlink" href="#buildversion-stamp-git_sha-stale-deployment-detector" title="Permanent link">¶</a></h3> <p>The image carries a build stamp — the git short SHA + build timestamp — surfaced by <code>GET /api/version</code> and shown in the SPA's user menu, so an operator (or a colleague on a demo) can see at a glance whether the running build is the expected one. Because <code>.git</code> is excluded from the image build context, the SHA is passed as the <strong><code>GIT_SHA</code> build ARG</strong> (<code>deploy/Dockerfile</code> exports it so both the Gradle backend stamp and the Quinoa-spawned npm SPA stamp pick it up). Omit it and both stamps fall back to <code>"unknown"</code>; the build still succeeds. With the bundled compose stack, wire it on the up/build command:</p> <div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="nv">GIT_SHA</span><span class="o">=</span><span class="k">$(</span>git<span class="w"> </span>rev-parse<span class="w"> </span>--short<span class="w"> </span>HEAD<span class="k">)</span><span class="w"> </span>docker<span class="w"> </span>compose<span class="w"> </span>up<span class="w"> </span>-d<span class="w"> </span>--build </code></pre></div> <h3 id="the-jooq-build-time-docker-dependency-important">The jOOQ build-time Docker dependency (important)<a class="headerlink" href="#the-jooq-build-time-docker-dependency-important" title="Permanent link">¶</a></h3> <p>jOOQ classes are generated from the <strong>real, Flyway-migrated schema</strong> by starting a throwaway PostgreSQL with Testcontainers — which needs a Docker socket. A hermetic <code>docker build</code> has <strong>no</strong> Docker socket, so the image build <strong>cannot</strong> run jOOQ codegen itself. The build therefore consumes <strong>pre-generated</strong> jOOQ sources via <code>-Plqms.jooq.provided</code> (wired in <code>deploy/Dockerfile</code>, shipped into the build context by a <code>.dockerignore</code> exception).</p> <p><strong>Operator obligation:</strong> run <code>./gradlew :backend:persistence:generateJooq</code> (on a machine with Docker) before building the image, and again whenever the migrations under <code>backend/persistence/src/main/resources/db/migration</code> change. If you skip it on a fresh checkout, the image build fails at Kotlin compile with unresolved <code>ch.lqms.persistence.jooq.*</code> symbols.</p> <p><em>(A proxied build network is supported: <code>docker build --build-arg https_proxy=… --build-arg http_proxy=… --build-arg no_proxy=… …</code>; the args are no-ops when unset.)</em></p> <hr /> <h2 id="3-deployment-topology">3. Deployment topology<a class="headerlink" href="#3-deployment-topology" title="Permanent link">¶</a></h2> <div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>browser ──TLS──> [ reverse proxy / TLS term ] ──> LQMS app (:8080) <a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a> │ ├── PostgreSQL 18 (data + RLS) <a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a> │ └── content store (filesystem volume) <a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a> ──OIDC──> IdP (corporate or Keycloak) <─────┘ (discovery, JWKS, token, login redirect) </code></pre></div> <ul> <li>The app serves the SPA and the API same-origin under one port (<code>8080</code>); <code>/api/*</code> is the authenticated API, <code>/</code> triggers OIDC login, static SPA assets are public (ADR-0032).</li> <li>Terminate TLS in front of the app. The session cookie is issued <code>Secure</code> (ADR-0028), so the app must be reached over HTTPS in production, and the IdP redirect URIs must be <code>https://…</code>.</li> </ul> <hr /> <h2 id="4-database-roles-and-the-bypassrls-requirement-read-this">4. Database roles and the BYPASSRLS requirement (READ THIS)<a class="headerlink" href="#4-database-roles-and-the-bypassrls-requirement-read-this" title="Permanent link">¶</a></h2> <h3 id="why-it-matters-adr-0035-7-adr-00020009">Why it matters (ADR-0035 §7, ADR-0002/0009)<a class="headerlink" href="#why-it-matters-adr-0035-7-adr-00020009" title="Permanent link">¶</a></h3> <p>Mandator/project separation is the top quality goal and is enforced in the database with <strong>row-level security</strong>: every content table is <code>FORCE</code> RLS. The cross-tenant fan-out that creates notifications for derived tenants runs through a <code>SECURITY DEFINER</code> function (<code>lqms_fanout_source_event</code>). A DEFINER function bypasses RLS <strong>only if its owner — the role that ran the migrations — is a superuser or has <code>BYPASSRLS</code>.</strong></p> <p>If migrations run as a plain owner, the function still "succeeds" but the caller's own RLS filters the derived scopes away: it returns 0 and <strong>derived tenants are silently never notified</strong>. That fails <em>closed</em> for separation but <em>silent</em> for compliance — the worst kind of bug, because nothing errors at runtime.</p> <p><strong>Enforcement:</strong> the app runs <code>FanoutDeploymentCheck</code> at startup and <strong>refuses to boot</strong> if the function owner cannot bypass RLS. You will see this line in a healthy boot:</p> <div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>Deployment checks passed (fan-out DEFINER owner can bypass RLS). </code></pre></div> <p>and this failure if the migration role lacks the privilege:</p> <div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>the owner of lqms_fanout_source_event is neither superuser nor BYPASSRLS: … Run migrations as a <a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a>BYPASSRLS role or grant it: ALTER ROLE <migration_role> BYPASSRLS. </code></pre></div> <h3 id="minimum-setup--the-migration-role">Minimum setup — the migration role<a class="headerlink" href="#minimum-setup--the-migration-role" title="Permanent link">¶</a></h3> <p>Create the migration role with <code>LOGIN</code> + <code>BYPASSRLS</code> and let it own the schema so every migrated object (including the DEFINER function) is owned by a BYPASSRLS role. <code>deploy/postgres-init.sql</code> does exactly this:</p> <div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="k">CREATE</span><span class="w"> </span><span class="k">ROLE</span><span class="w"> </span><span class="n">lqms_migration</span><span class="w"> </span><span class="k">WITH</span><span class="w"> </span><span class="n">LOGIN</span><span class="w"> </span><span class="n">PASSWORD</span><span class="w"> </span><span class="s1">'…'</span><span class="w"> </span><span class="n">BYPASSRLS</span><span class="p">;</span> <a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="k">ALTER</span><span class="w"> </span><span class="k">SCHEMA</span><span class="w"> </span><span class="k">public</span><span class="w"> </span><span class="k">OWNER</span><span class="w"> </span><span class="k">TO</span><span class="w"> </span><span class="n">lqms_migration</span><span class="p">;</span> <a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a><span class="k">GRANT</span><span class="w"> </span><span class="k">ALL</span><span class="w"> </span><span class="k">PRIVILEGES</span><span class="w"> </span><span class="k">ON</span><span class="w"> </span><span class="k">DATABASE</span><span class="w"> </span><span class="n">lqms</span><span class="w"> </span><span class="k">TO</span><span class="w"> </span><span class="n">lqms_migration</span><span class="p">;</span> <a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="k">GRANT</span><span class="w"> </span><span class="k">ALL</span><span class="w"> </span><span class="k">ON</span><span class="w"> </span><span class="k">SCHEMA</span><span class="w"> </span><span class="k">public</span><span class="w"> </span><span class="k">TO</span><span class="w"> </span><span class="n">lqms_migration</span><span class="p">;</span> </code></pre></div> <p>Point the app datasource at this role. Flyway migrates at startup (§10).</p> <h3 id="current-single-datasource-reality">Current single-datasource reality<a class="headerlink" href="#current-single-datasource-reality" title="Permanent link">¶</a></h3> <p>The application uses <strong>one</strong> datasource, so it <em>connects</em> with the same BYPASSRLS migration role it migrates with — but <strong>runtime RLS is still fully enforced for content access</strong>: every content transaction runs <code>SET LOCAL ROLE lqms_app</code> (a NOBYPASSRLS role) before touching data (<code>RlsScopeContext</code>, ADR-0026), so the FORCE-RLS policies apply and the database backstop is active. This is the test-proven RISK-002 closure (<code>RlsScopeContextTest</code> demonstrates RLS holding even over a superuser datasource). Code paths that deliberately do NOT switch roles (startup bootstrap, the scheduler sweep, notification delivery — system-context by design, ADR-0037/0039) run with the connection's privileges.</p> <p>The residual the two-role hardening below addresses is defense-in-depth, not a live gap: a bug or compromise that <em>skipped</em> the role switch would run privileged. Connecting with a NOBYPASSRLS runtime role would make that class of bug fail closed.</p> <h3 id="two-role-hardening-recommended-for-production">Two-role hardening (recommended for production)<a class="headerlink" href="#two-role-hardening-recommended-for-production" title="Permanent link">¶</a></h3> <p>The design (ADR-0002/0009, <code>V002__row_level_security.sql</code>) intends <strong>two</strong> roles:</p> <table> <thead> <tr> <th>Role</th> <th>Privilege</th> <th>Used for</th> </tr> </thead> <tbody> <tr> <td><code>lqms_migration</code></td> <td><code>LOGIN</code>, <strong><code>BYPASSRLS</code></strong></td> <td>Flyway migrations (and the DEFINER function owner)</td> </tr> <tr> <td><code>lqms_runtime</code></td> <td><code>LOGIN</code>, <strong><code>NOBYPASSRLS</code></strong>, member of <code>lqms_app</code></td> <td>the application's runtime datasource</td> </tr> </tbody> </table> <p>The runtime role must be a member of the <code>lqms_app</code> group role (created by migration <code>V002</code>) and must <strong>not</strong> bypass RLS, so the database enforces separation even if an application query forgets its scope filter. It cannot be created in <code>postgres-init.sql</code> because <code>lqms_app</code> does not exist until migrations run; create it after first migration:</p> <div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="k">CREATE</span><span class="w"> </span><span class="k">ROLE</span><span class="w"> </span><span class="n">lqms_runtime</span><span class="w"> </span><span class="k">WITH</span><span class="w"> </span><span class="n">LOGIN</span><span class="w"> </span><span class="n">PASSWORD</span><span class="w"> </span><span class="s1">'…'</span><span class="w"> </span><span class="n">NOBYPASSRLS</span><span class="p">;</span> <a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a><span class="k">GRANT</span><span class="w"> </span><span class="n">lqms_app</span><span class="w"> </span><span class="k">TO</span><span class="w"> </span><span class="n">lqms_runtime</span><span class="p">;</span> </code></pre></div> <p>Splitting the app onto <code>lqms_runtime</code> (a second datasource used for everything except Flyway) is a code change beyond this packaging work and is <strong>staged for review</strong>, not implemented here. Until then, run the single-datasource stack behind the same separation discipline you would apply to any app-tier-enforced tenant boundary.</p> <hr /> <h2 id="5-configuration-reference">5. Configuration reference<a class="headerlink" href="#5-configuration-reference" title="Permanent link">¶</a></h2> <p>All keys are standard MicroProfile/Quarkus config: set them as environment variables (shown in <code>ENV_VAR</code> form) or <code>-D</code> system properties. Env mapping uppercases and replaces <code>.</code>/<code>-</code> with <code>_</code> (e.g. <code>lqms.storage.root</code> → <code>LQMS_STORAGE_ROOT</code>, <code>quarkus.oidc.auth-server-url</code> → <code>QUARKUS_OIDC_AUTH_SERVER_URL</code>). Defaults below are from <code>backend/api/src/main/resources/application.properties</code>.</p> <h3 id="51-datasource">5.1 Datasource<a class="headerlink" href="#51-datasource" title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Key</th> <th>Default</th> <th>When to change</th> </tr> </thead> <tbody> <tr> <td><code>quarkus.datasource.db-kind</code></td> <td><code>postgresql</code></td> <td>fixed</td> </tr> <tr> <td><code>quarkus.datasource.jdbc.url</code></td> <td><em>(dev services in dev/test)</em></td> <td><strong>required</strong> in prod, e.g. <code>jdbc:postgresql://db:5432/lqms</code></td> </tr> <tr> <td><code>quarkus.datasource.username</code></td> <td>—</td> <td><strong>required</strong> in prod: the migration role (§4), e.g. <code>lqms_migration</code></td> </tr> <tr> <td><code>quarkus.datasource.password</code></td> <td>—</td> <td><strong>required</strong> in prod; use a secret, not a literal</td> </tr> <tr> <td><code>quarkus.datasource.devservices.image-name</code></td> <td><code>postgres:18-alpine</code></td> <td>dev/test only (Testcontainers)</td> </tr> </tbody> </table> <h3 id="52-flyway-schema-migrations">5.2 Flyway (schema migrations)<a class="headerlink" href="#52-flyway-schema-migrations" title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Key</th> <th>Default</th> <th>When to change</th> </tr> </thead> <tbody> <tr> <td><code>quarkus.flyway.migrate-at-start</code></td> <td><code>true</code></td> <td>leave on unless you gate migrations externally (§10)</td> </tr> </tbody> </table> <h3 id="53-http--rest-boundary">5.3 HTTP / REST boundary<a class="headerlink" href="#53-http--rest-boundary" title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Key</th> <th>Default</th> <th>Notes</th> </tr> </thead> <tbody> <tr> <td><code>quarkus.rest.path</code></td> <td><code>/api</code></td> <td>API prefix; SPA lives at <code>/</code> (ADR-0032)</td> </tr> <tr> <td><code>quarkus.http.auth.permission.*</code></td> <td>see below</td> <td>authorization boundary, leave as shipped</td> </tr> <tr> <td><code>quarkus.http.auth.proactive</code></td> <td><code>true</code></td> <td>proactive auth</td> </tr> </tbody> </table> <p>Boundary rules (most-specific path wins): <code>/</code> authenticated (SPA entry → OIDC login); <code>/api/health</code> permit (liveness); <code>/api/version</code> permit (public build stamp — carries no tenant data, §5.12); <code>/api/*</code> authenticated; <code>/logout</code> authenticated (RP-initiated logout, §5.5); <code>/q/*</code> authenticated in prod (permitted in dev); <code>/*</code> permit (SPA static assets). Do not loosen these.</p> <h3 id="54-frontend-quinoa-adr-0032">5.4 Frontend (Quinoa, ADR-0032)<a class="headerlink" href="#54-frontend-quinoa-adr-0032" title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Key</th> <th>Default</th> <th>Notes</th> </tr> </thead> <tbody> <tr> <td><code>quarkus.quinoa</code></td> <td><code>false</code></td> <td><strong>must be <code>true</code> at build time</strong> to bundle the SPA (the Dockerfile passes <code>-Dquarkus.quinoa=true</code>); irrelevant at runtime</td> </tr> <tr> <td><code>quarkus.quinoa.build-dir</code></td> <td><code>dist/webui/browser</code></td> <td>Angular output dir</td> </tr> <tr> <td><code>quarkus.quinoa.enable-spa-routing</code></td> <td><code>true</code></td> <td>client-side routing fallback</td> </tr> </tbody> </table> <h3 id="55-authentication--oidc-adr-001100280033-req-auth-">5.5 Authentication / OIDC (ADR-0011/0028/0033, REQ-AUTH-*)<a class="headerlink" href="#55-authentication--oidc-adr-001100280033-req-auth-" title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Key</th> <th>Default</th> <th>When to change</th> </tr> </thead> <tbody> <tr> <td><code>quarkus.oidc.auth-server-url</code></td> <td><em>(dev services in dev)</em></td> <td><strong>required</strong> in prod: the issuer URL, e.g. <code>https://idp.example.com/realms/lqms</code></td> </tr> <tr> <td><code>quarkus.oidc.client-id</code></td> <td><em>(dev services)</em></td> <td><strong>required</strong> in prod: the LQMS client id at the IdP</td> </tr> <tr> <td><code>quarkus.oidc.credentials.secret</code></td> <td>—</td> <td><strong>required</strong> for a confidential client (BFF); use a secret</td> </tr> <tr> <td><code>quarkus.oidc.application-type</code></td> <td><code>hybrid</code></td> <td>browser BFF + machine bearer in one; leave as-is</td> </tr> <tr> <td><code>quarkus.oidc.authentication.pkce-required</code></td> <td><code>true</code></td> <td>keep on; the IdP client must allow PKCE (S256)</td> </tr> <tr> <td><code>quarkus.oidc.authentication.cookie-same-site</code></td> <td><code>lax</code></td> <td>CSRF posture (ADR-0033); leave as-is</td> </tr> <tr> <td><code>quarkus.oidc.token.refresh-expired</code></td> <td><code>true</code></td> <td>silent refresh (REQ-AUTH-006); leave on</td> </tr> <tr> <td><code>quarkus.oidc.token.audience</code></td> <td><code>${quarkus.oidc.client-id}</code></td> <td>audience hardening (REQ-AUTH-011); the IdP <strong>must</strong> add the LQMS client to the access-token <code>aud</code> (see §6)</td> </tr> <tr> <td><code>quarkus.oidc.authentication.allow-multiple-code-flows</code></td> <td><code>false</code></td> <td><strong>leave off</strong> (finding #18): reuse the single state-cookie name <code>q_auth</code> so repeated code-flow challenges overwrite instead of accumulating <code>q_auth_*</code> cookies into an HTTP 431 (quarkusio/quarkus#40268). Trade-off: no two <em>concurrent</em> interactive logins in separate tabs at the same instant</td> </tr> <tr> <td><code>quarkus.oidc.authentication.java-script-auto-redirect</code></td> <td><code>false</code></td> <td><strong>leave off</strong> (finding #18): an XHR the SPA marks <code>X-Requested-With: JavaScript</code> gets a <code>499</code> (not a 302 the background call can't complete), so no surplus state cookie is minted and the SPA reloads to a clean login. Do <strong>not</strong> treat the 431 by raising <code>quarkus.http.limits.max-header-size</code></td> </tr> <tr> <td><code>quarkus.oidc.logout.path</code></td> <td><code>/logout</code></td> <td>RP-initiated logout: hitting this ends the IdP session and clears the BFF cookie. Register the post-logout URI at the IdP (§6)</td> </tr> <tr> <td><code>quarkus.oidc.logout.post-logout-path</code></td> <td><code>/</code></td> <td>where the IdP redirects after logout (back to the SPA entry → fresh login)</td> </tr> </tbody> </table> <p><strong>After a restore, existing browser sessions are invalid — re-login is expected (and now fails clean).</strong> A restore that replaces the Keycloak realm (e.g. <code>restore.sh … --force</code>) rotates the realm signing keys, so any BFF session cookie a browser still holds becomes unrefreshable. With the two knobs above this fails <strong>clean</strong>: the SPA's next request gets a <code>499</code>, reloads, and lands on a fresh login — the session cookies are reset server-side. Without them (the pre-fix behaviour, finding #18) the same situation wedged the profile: each background XHR minted a new <code>q_auth_*</code> state cookie until the Cookie header exceeded the server limit and <strong>every</strong> request returned HTTP 431. If a user reports a persistent 431 after a restore, the immediate remedy is to clear the site's cookies (or use a fresh profile); the structural fix is these two settings. Never work around it by enlarging the header limit.</p> <h3 id="56-keycloak-dev-services-testdev-only--ignore-in-prod">5.6 Keycloak Dev Services (test/dev only — ignore in prod)<a class="headerlink" href="#56-keycloak-dev-services-testdev-only--ignore-in-prod" title="Permanent link">¶</a></h3> <p><code>quarkus.keycloak.devservices.web-client-timeout</code> (<code>60s</code>) and <code>quarkus.devservices.timeout</code> (<code>180s</code>) only affect the Dev Services containers started during <code>./gradlew test</code>/dev mode. They have no effect on a production deployment that supplies its own <code>quarkus.oidc.auth-server-url</code>.</p> <h3 id="57-system-bootstrap-adr-0012--see-7">5.7 System bootstrap (ADR-0012) — see §7<a class="headerlink" href="#57-system-bootstrap-adr-0012--see-7" title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Key</th> <th>Default</th> <th>Notes</th> </tr> </thead> <tbody> <tr> <td><code>lqms.bootstrap.admin.issuer</code></td> <td><em>(unset → bootstrap skipped)</em></td> <td>the admin identity's OIDC issuer</td> </tr> <tr> <td><code>lqms.bootstrap.admin.subject</code></td> <td><em>(unset)</em></td> <td>the admin's stable OIDC subject (<code>sub</code>)</td> </tr> <tr> <td><code>lqms.bootstrap.admin.email</code></td> <td><em>(unset)</em></td> <td>the admin's email</td> </tr> <tr> <td><code>lqms.bootstrap.admin.display-name</code></td> <td><em>(unset, optional)</em></td> <td>display name</td> </tr> </tbody> </table> <p><code>issuer</code>, <code>subject</code>, and <code>email</code> must <strong>all</strong> be set for the bootstrap to run; otherwise it is skipped (logged as "No bootstrap admin identity configured").</p> <h3 id="58-content-store-adr-0001">5.8 Content store (ADR-0001)<a class="headerlink" href="#58-content-store-adr-0001" title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Key</th> <th>Default</th> <th>Notes</th> </tr> </thead> <tbody> <tr> <td><code>lqms.storage.root</code></td> <td><code>data/content</code></td> <td><strong>set to a persistent, backed-up path/volume</strong> (the image defaults <code>LQMS_STORAGE_ROOT=/app/data/content</code>); document/version blobs live here</td> </tr> <tr> <td><code>lqms.content.attachment.max-bytes</code></td> <td><code>10485760</code> (10 MB)</td> <td>max size of a single image attachment (ADR-0045); rejected above this</td> </tr> <tr> <td><code>lqms.content.attachment.max-count</code></td> <td><code>25</code></td> <td>max number of image attachments per draft version (ADR-0045)</td> </tr> </tbody> </table> <p>Image attachments (ADR-0045, rich content) are PNG/JPEG only — magic-byte-verified on upload, not by extension — and share the <code>lqms.storage.root</code> blob store with document/version content; no separate storage config.</p> <h3 id="59-overdue-task-sweep-adr-0037-req-not-004--see-9">5.9 Overdue-task sweep (ADR-0037, REQ-NOT-004) — see §9<a class="headerlink" href="#59-overdue-task-sweep-adr-0037-req-not-004--see-9" title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Key</th> <th>Default</th> <th>Notes</th> </tr> </thead> <tbody> <tr> <td><code>lqms.tasks.sweep-interval</code></td> <td><code>5m</code></td> <td>how often the scheduler tick runs (also drives email delivery, §8)</td> </tr> <tr> <td><code>lqms.tasks.due-after</code></td> <td><code>P14D</code></td> <td>ISO-8601 period after which an open task is <em>due</em></td> </tr> <tr> <td><code>lqms.tasks.escalate-after</code></td> <td><code>P7D</code></td> <td>grace period after due before <em>escalation</em></td> </tr> </tbody> </table> <h3 id="510-notification-email-adr-0041--see-8">5.10 Notification email (ADR-0041) — see §8<a class="headerlink" href="#510-notification-email-adr-0041--see-8" title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Key</th> <th>Default</th> <th>Notes</th> </tr> </thead> <tbody> <tr> <td><code>lqms.notifications.email.enabled</code></td> <td><code>false</code></td> <td>enable to deliver notifications by email</td> </tr> <tr> <td><code>lqms.notifications.default-locale</code></td> <td><code>en</code></td> <td>language for recipients with no <code>app_user.locale</code></td> </tr> <tr> <td><code>quarkus.mailer.from</code></td> <td><code>lqms@example.com</code></td> <td>sender; set a real address when email is enabled</td> </tr> <tr> <td><code>quarkus.mailer.host</code> / <code>.port</code> / <code>.username</code> / <code>.password</code> / <code>.tls</code></td> <td>—</td> <td>standard quarkus-mailer SMTP settings, supplied per deployment when email is on</td> </tr> </tbody> </table> <h3 id="511-runtime-postgresql-session-variables-not-config-keys">5.11 Runtime PostgreSQL session variables (not config keys)<a class="headerlink" href="#511-runtime-postgresql-session-variables-not-config-keys" title="Permanent link">¶</a></h3> <p><code>lqms.authorized_scope_ids</code> and <code>lqms.current_user_id</code> are <strong>PostgreSQL session GUCs</strong> set by the app per transaction (<code>RlsScopeContext</code>, ADR-0026) — they are not operator configuration and must not be set as app config.</p> <h3 id="512-spa-cache-headers-stale-bundle-prevention">5.12 SPA cache headers (stale-bundle prevention)<a class="headerlink" href="#512-spa-cache-headers-stale-bundle-prevention" title="Permanent link">¶</a></h3> <p>The app sets <code>Cache-Control</code> on the served SPA so a browser never runs an old entry point against a freshly deployed backend (a real bug caught in the demo — a cached <code>index.html</code> served the previous build):</p> <table> <thead> <tr> <th>Key</th> <th>Value</th> <th>Effect</th> </tr> </thead> <tbody> <tr> <td><code>quarkus.http.filter.spa-entry-nocache.matches</code> / <code>.header."Cache-Control"</code></td> <td><code>/\|/index.html</code> → <code>no-cache</code></td> <td>the SPA entry point is <strong>revalidated every load</strong>, so a new deploy is picked up immediately</td> </tr> <tr> <td><code>quarkus.http.filter.spa-hashed-assets.matches</code> / <code>.header."Cache-Control"</code></td> <td>content-hashed <code>*.js</code>/<code>*.css</code> → <code>public, max-age=31536000, immutable</code></td> <td>fingerprinted bundles cache for a year (safe — a new build emits new filenames)</td> </tr> </tbody> </table> <p>Leave these as shipped; they are the counterpart to the <code>GIT_SHA</code> build stamp (§2) for keeping a deployment demonstrably current.</p> <hr /> <h2 id="6-idp-integration-real-deployment">6. IdP integration (real deployment)<a class="headerlink" href="#6-idp-integration-real-deployment" title="Permanent link">¶</a></h2> <p>LQMS authenticates browsers via the OIDC Authorization Code flow with PKCE and a server-side (BFF) session; machine/MCP clients present bearer tokens validated against the same provider (ADR-0011). To integrate a corporate IdP, register an LQMS <strong>confidential</strong> client and ensure it provides:</p> <ol> <li><strong>Authorization Code + PKCE (S256).</strong> <code>pkce-required=true</code> is on; the client must permit PKCE.</li> <li><strong>A confidential client secret</strong> → <code>quarkus.oidc.credentials.secret</code>.</li> <li><strong>Redirect URIs</strong> for the app's public HTTPS origin (e.g. <code>https://lqms.example.com/*</code>), and post-logout redirect URIs as needed.</li> <li><strong>An audience mapper</strong> that adds the LQMS client id to the <strong>access token</strong> <code>aud</code> claim (REQ-AUTH-011 / <code>quarkus.oidc.token.audience</code>). Without it, valid tokens are rejected. In Keycloak this is an <code>oidc-audience-mapper</code> on the client (see <code>deploy/lqms-realm.json</code> and the test realm <code>backend/api/src/test/resources/quarkus-realm.json</code>).</li> <li><strong>An <code>email</code> claim</strong> (and ideally <code>given_name</code>/<code>family_name</code>). The user is JIT-provisioned from token claims; email is used for notification delivery and is refreshable from the IdP (REQ-DPR-009).</li> <li><strong>A stable <code>sub</code></strong> per user — this is the identity key LQMS stores (issuer + subject). It must match the bootstrap admin <code>subject</code> for the break-glass admin (§7).</li> </ol> <p><strong>Set</strong> <code>quarkus.oidc.auth-server-url</code> to the realm/issuer URL and <code>quarkus.oidc.client-id</code> to the registered client. The URL must be reachable from the app (discovery/JWKS/token) <strong>and</strong> resolve to the same issuer for the browser (login redirect). On a single host with the bundled Keycloak, use a hostname reachable from both sides (see <code>deploy/README.md</code>, "Browser vs server url").</p> <hr /> <h2 id="7-bootstrap-admin-flow-adr-0012">7. Bootstrap admin flow (ADR-0012)<a class="headerlink" href="#7-bootstrap-admin-flow-adr-0012" title="Permanent link">¶</a></h2> <p>On startup, if <code>lqms.bootstrap.admin.{issuer,subject,email}</code> are all set, <code>BootstrapRunner</code> idempotently brings up the base hierarchy and grants that identity system administration. It runs on <strong>every</strong> boot (safe, idempotent) — for initial setup and break-glass recovery.</p> <ul> <li>Set <code>subject</code> to the admin user's <strong>stable OIDC <code>sub</code></strong> at your IdP and <code>issuer</code> to the IdP issuer URL — they must match the token the admin will present, or the grant won't apply to the right account.</li> <li>Leave all three unset to skip bootstrap entirely (e.g. once admins are managed in-app).</li> <li>In the bundled stack these are preset to the demo user (fixed <code>sub</code> in the realm), so the stack self-bootstraps on first boot.</li> </ul> <hr /> <h2 id="8-email-enablement-adr-0041--backlog-note-adr-0043">8. Email enablement (ADR-0041) + backlog note (ADR-0043)<a class="headerlink" href="#8-email-enablement-adr-0041--backlog-note-adr-0043" title="Permanent link">¶</a></h2> <p>Notifications are an <strong>outbox</strong>: the notification row is the source of truth, and a delivery pass on the scheduler tick (§9) sends unstamped rows via the channel. Email is <strong>disabled by default</strong> so a deployment without SMTP still delivers in-app notifications (REQ-NOT-007).</p> <p>To enable email:</p> <ol> <li><code>lqms.notifications.email.enabled=true</code>.</li> <li>Configure quarkus-mailer: <code>quarkus.mailer.host</code>, <code>.port</code>, <code>.from</code> (a real address), <code>.username</code>/<code>.password</code>, <code>.tls</code>/<code>.ssl</code> as your SMTP relay requires.</li> <li>Optionally set <code>lqms.notifications.default-locale</code> for recipients without a saved locale.</li> </ol> <p><strong>Backlog semantics you must know (ADR-0043):</strong> while email is disabled, notification rows accrue with <code>emailed_at</code> unstamped <strong>by design</strong>. There is <strong>no age cap</strong> — when you later enable the channel, the <strong>entire accumulated backlog is delivered</strong> on the next ticks. If you enable email on a system that has been running a while, expect a burst of catch-up mail. If that is undesirable, stamp or archive the backlog before enabling (operational step; no config flag exists for it).</p> <hr /> <h2 id="9-sweep-tuning-adr-0037">9. Sweep tuning (ADR-0037)<a class="headerlink" href="#9-sweep-tuning-adr-0037" title="Permanent link">¶</a></h2> <p>The scheduler tick (<code>lqms.tasks.sweep-interval</code>, default <code>5m</code>, advisory-locked so only one instance sweeps) marks overdue tasks, escalates, and — when email is on — runs the delivery pass.</p> <ul> <li><code>lqms.tasks.due-after</code> (<code>P14D</code>): how long an open task may sit before it is <strong>due</strong>.</li> <li><code>lqms.tasks.escalate-after</code> (<code>P7D</code>): grace after due before <strong>escalation</strong>.</li> <li>Tune the interval to your delivery latency vs. load trade-off; the due/escalate periods to your QMS SLA. Values are ISO-8601 durations (<code>PnD</code>, <code>PTnH</code>, …).</li> </ul> <hr /> <h2 id="10-upgrade-path">10. Upgrade path<a class="headerlink" href="#10-upgrade-path" title="Permanent link">¶</a></h2> <ul> <li><strong>Schema:</strong> Flyway runs at startup (<code>quarkus.flyway.migrate-at-start=true</code>) and applies any new <code>V0xx__*.sql</code> migrations automatically. The current baseline is <strong>V001…V066</strong> (latest: V065 <code>blob_quarantine</code>, V066 calendar obligation schedules); a healthy boot log shows Flyway "Successfully applied" / "up to date" and the deployment-check line from §4.</li> <li><strong>Run migrations as the BYPASSRLS migration role</strong> (§4) — the whole point of that role. If you ever regenerate jOOQ or add migrations, rebuild the image with fresh generated sources (§2).</li> <li><strong>Rollout:</strong> deploy the new image; on boot it migrates then runs the deployment/bootstrap checks. Because the sweep is advisory-locked and the session is a stateless cookie (ADR-0028), a rolling restart is safe. Keep only one schema-migrating instance starting at a time if you scale out (Flyway takes a lock, but avoid concurrent first-boot races).</li> <li><strong>Backups:</strong> see §11 — take a database + content-store backup before a migration you cannot cheaply roll back (there is no automated down-migration).</li> </ul> <hr /> <h2 id="11-backup--retention-window-adr-0025--adr-0016">11. Backup & retention window (ADR-0025 / ADR-0016)<a class="headerlink" href="#11-backup--retention-window-adr-0025--adr-0016" title="Permanent link">¶</a></h2> <p>Disposal and erasure are <strong>forward-only</strong> with respect to backups: erasing a record removes it from the live system immediately, but copies persist in existing backups until those backups age out. ADR-0025 therefore makes a <strong>bounded, configurable backup-retention window</strong> an <em>operational requirement</em>: erasure is "effective immediately in the live system, and in backups within the backup-retention window."</p> <p><strong>Operator obligation:</strong> define and enforce a backup-retention window per your data-protection policy, and ensure backups older than that window are actually deleted, so disposed/erased data does not linger indefinitely.</p> <p><strong>There is no application config key for this window today</strong> — it is an operational property of your backup tooling/schedule (e.g. your <code>pg_dump</code>/PITR retention and content-store snapshot retention), not something LQMS enforces. Document your chosen window and the deletion mechanism in your operational runbook. Back up <strong>both</strong> the PostgreSQL database and the content store (<code>lqms.storage.root</code>) together, since a document's metadata and its blobs must be restored consistently.</p> <hr /> <h2 id="12-verifying-a-deployment">12. Verifying a deployment<a class="headerlink" href="#12-verifying-a-deployment" title="Permanent link">¶</a></h2> <p>A healthy boot log contains:</p> <ul> <li>Flyway applying/confirming migrations <strong>V001…V066</strong>;</li> <li><code>Deployment checks passed (fan-out DEFINER owner can bypass RLS).</code> (§4);</li> <li><code>System bootstrap complete for admin subject '…'.</code> when a bootstrap admin is configured (§7).</li> </ul> <p>Then:</p> <ul> <li><code>GET /api/health</code> → <code>200 {"status":"UP"}</code>.</li> <li><code>GET /api/version</code> → <code>200 {"sha":"…","timestamp":"…"}</code> — confirms the running build (public, no auth; <code>sha</code> is <code>unknown</code> if the image was built without the <code>GIT_SHA</code> build ARG, §2).</li> <li><code>GET /</code> (browser) → redirect to the IdP login.</li> <li>An authenticated <code>GET /api/me</code> with a valid bearer token → <code>200</code> with the provisioned user.</li> </ul> <p><code>deploy/smoke.sh</code> automates these against the bundled compose stack.</p> <p><strong>Deploy-image render guard (FWK005).</strong> The smoke's opt-in Stage 5 renders a merged audit-pack on the real Temurin 25-jre runtime and asserts genuine PDF bytes — the only gate that exercises the deployment JVM <em>with content</em>. The FOP FWK005 render fault is a runtime-JVM-only failure that no CI job catches (all CI runs JDK 21; and while the tag-gated <code>publish-image</code> job now <em>builds</em> the deploy image, nothing in CI ever <em>runs</em> it), so this smoke is its durable guard — run it before cutting a release tag. Because it needs seeded released content it is opt-in; <code>deploy/nightly-smoke.sh</code> runs it end-to-end on an isolated stack (build → up → seed → render → teardown) as a single command for the nightly smoke watch.</p> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type="button" class="md-top md-icon" data-md-component="top" hidden> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class="md-footer"> <nav class="md-footer__inner md-grid" aria-label="Footer" > <a href="../genesis-installation/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Genesis: Birthing an LQMS Installation with a Base Library"> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class="md-footer__title"> <span class="md-footer__direction"> Previous </span> <div class="md-ellipsis"> Genesis: Birthing an LQMS Installation with a Base Library </div> </div> </a> <a href="../server-deployment/" class="md-footer__link md-footer__link--next" aria-label="Next: LQMS Server Deployment (single Linux host, public HTTPS)"> <div class="md-footer__title"> <span class="md-footer__direction"> Next </span> <div class="md-ellipsis"> LQMS Server Deployment (single Linux host, public HTTPS) </div> </div> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-copyright"> <div class="md-copyright__highlight"> Built from <code>v0.9.56-4-g06c7f811</code> (commit <code>06c7f811</code>, 2026-09-09) — the same Markdown the repository ships. </div> </div> </div> </div> </footer> </div> <div class="md-dialog" data-md-component="dialog"> <div class="md-dialog__inner md-typeset"></div> </div> <script id="__config" type="application/json">{"base": "../..", "features": ["navigation.instant", "navigation.tracking", "navigation.top", "navigation.footer", "navigation.indexes", "toc.follow", "search.suggest", "search.highlight", "content.code.copy", "content.action.edit"], "search": "../../assets/javascripts/workers/search.6ce7567c.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script> <script src="../../assets/javascripts/bundle.83f73b43.min.js"></script> </body> </html>