Operations, backups and recovery

Routine checks

• Use /health/live for process liveness and /health/ready for role readiness. A live process is not necessarily ready.
• Inspect worker failures and pending messages. An accepted operation does not mean an external message has already been delivered.
• Monitor disk space, file storage and the web/admin refresh-coordination volumes.
• Use operation references and error codes for support; do not place tokens or complete personal records in tickets.

Create a backup

Production Compose includes a backup profile:

docker compose -f deploy/compose.prod.yaml \
  --env-file deploy/.env.prod --profile backup run --rm backup

Check the destination and retention in the selected example file. Include required file storage and securely managed configuration as well as the database. Test restoration in a separate environment, then verify that an edition, registration and file remain usable.

Upgrade

Read the release notes and upgrade considerations in deploy/README.md. Build or pull matching images; finish the migration role before restarting application roles. Verify user journeys afterwards.

A worker startup may also execute retention cleanup. Check changed retention periods before upgrading, rather than after a cleanup sweep.

Configure retention periods

Retention periods live under Omnia:Retention. Each named period has a fixed unit, decided in code; you can change the length but not the unit.

• Days: Omnia__Retention__Periods__<Name>=<days>, a whole number of 0 or more.
• Calendar months: Omnia__Retention__Periods__<Name>__Months=<months>, a whole number of 1 or more. The period counts from the last day of the edition in the event’s time zone. The data goes at the end of the same calendar day that many months later: 6 months after 15 May is the end of 15 November. If that month has no such day, the month’s last day counts: 6 months after 31 August is the end of 28 February, or 29 February in a leap year.

A period set in the wrong unit, in both units or to an invalid value stops the worker at start with exit code 64 and a message naming the setting to change. The months form is available since the reviewed revision, but no period uses calendar months yet; the specification for the first consumer (omnia-spec #365) is still open.

Put the setting in the worker’s environment. In the production Compose profile that means worker.environment in compose.prod.yaml or an override; a value in .env.prod alone is not passed to the worker. Examples of day-based periods are CfpEmergencyContact (30 days) and McpAuditRecord (60 days).

MCP and assistant connections

The MCP endpoint is only mapped when the API has a valid public origin in OMNIA_API_URL. The protected-resource metadata additionally needs a configured identity provider.

• Abuse budget: MCP has its own per-address group mcp, default 1,000 requests per one-minute window. Override it with Omnia__Network__AbuseBudget__Groups__mcp__PerAddress, …__Window and …__MaxBodyBytes (default 256 KiB). The deploy example files do not list these keys. An exceeded budget returns 429 with Retry-After.
• Audit retention: MCP audit records are kept 60 days by default and removed by the daily worker sweep. Change it with Omnia__Retention__Periods__McpAuditRecord=<days>.

Connections for people and agents are managed through the API only; there is no administration screen.

Person erasure and action-link receipts

Person erasure is off by default (Omnia__Identity__Erasure__Enabled=false). The coordinating mechanism and several participating domains exist, but the production erasure flow is not complete (platform #1821). Do not enable it as an end-user service; see privacy.

Confirmed action-link completions now leave a receipt. Receipts that were never acknowledged are removed after Omnia__Identity__ActionLinks__KeepReceiptsFor (a time span, default 30.00:00:00). A negative value stops startup. This key is not listed in deploy/env.example.

Upgrade notes 13–14 November 2026

These notes cover the platform changes merged on 13 and 14 November 2026. Apply them in addition to the notes in deploy/README.md, which does not yet mention them.

1. Check orders before ConstrainOrderBuyerShape. The migration adds the database constraint ck_orders_buyer_shape. It fails (SQLSTATE 23514) if a row already breaks the rule: a person buyer with a company name or VAT number, or a company buyer without a name. Omnia itself has never written such a row, but check data imported or edited outside Omnia first:

   SELECT id, buyer_kind, buyer_company_name, buyer_vat_identification
   FROM commerce.orders
   WHERE NOT ((buyer_kind = 'Person' AND buyer_company_name IS NULL
               AND buyer_vat_identification IS NULL)
           OR (buyer_kind = 'Company' AND buyer_company_name IS NOT NULL
               AND buyer_company_name ~ '[^ ]'));

   The query must return no rows. Correct any rows it finds before upgrading. The new length limits apply only to new orders; existing rows are not changed.

2. Check order lines before TightenOrderLineAttachment. The constraint ck_order_lines_attachment now requires every option line to name the ticket line it belongs to. This query must return no rows:

   SELECT id FROM commerce.order_lines
   WHERE NOT ((ticket_type_id IS NULL) = (attached_to_line_id IS NOT NULL));

3. Data-only erasure migrations. AddCommerceErasureDomains and AddSponsorsAcceptanceJournalErasureDomain only add pending domain rows to open erasure requests. No settings are needed. With erasure off, nothing is processed.

4. AddActionLinkReceiptSubject. Adds the receipt’s subject person and two indexes, and registers the receipts as an erasure domain. The optional KeepReceiptsFor setting is described above.

5. New setting shape for retention in calendar months. Available, with no period using it yet. Existing day-based settings stay valid.

The workshop-places check merged on 14 November (#2580) has no migration, setting or visible effect.

Recover refresh coordination safely

Do not delete or restore refresh-journal volumes while old sign-in cookies can remain valid. The journal prevents reuse of refresh tokens that were already spent. An older backup may lose that evidence.

The platform procedure first ends the relevant sign-in sessions, for example by changing both OMNIA_WEB_SESSION_SECRET and OMNIA_ADMIN_SESSION_SECRET while the apps are stopped. Follow the specific recovery procedure; docker compose down -v is not a normal recovery step and also deletes data.

Record the incident, cause, recovery steps and verification. Keep archiving and personal-data erasure separate from technical backup management.