Operating a Beep.Reports installation: deployment, configuration, stores and backups, scheduling and delivery, security, and the runbook. For embedding, see EMBEDDING.md; for the operational event contract, see OPERATIONAL_SERVICES.md.

1. Deployment topologies

Topology What runs Use when
Desktop only Designer + viewer in one desktop process, reports and data local Single author or a small team sharing files/stores
Service + desktop Beep.Reports.Server behind a reverse proxy; WPF/WinForms designers connect through HttpBackend Authors need shared reports, versions and audit
Service + web The same service plus Designer.Blazor and Viewer.Blazor Browser-only authors and viewers
Offline Designer with an exported *.beepschema.json/*.beepsample.json snapshot, local engine No network access; reconcile later

Multi-tenancy is a server configuration, not a separate build: every stored document carries a tenant id and every request is authorized for the caller's tenant.

2. Configuration and limits

Configuration is host-supplied (environment variables or the host's configuration provider); the library has no hidden global state.

Area Setting Notes
Definition DefinitionLimits (items, depth, string length, file bytes) Rejected at load/save with a typed diagnostic
Data provider row caps, query timeout, preview rows The engine cancels reads at the cap
Rendering image bytes, page count, per-page primitives Oversized resources are refused, not truncated silently
Preview cache directory and size, parameter defaults, run timeout Cache is disposable; deleting it is always safe
Scripts enabled/disabled, timeout, server policy (ScriptsNotAllowedOnServer) Off by default; see ADR-006
Delivery recipients per run, runs per window, artifact bytes, concurrency SubscriptionQuotaGuard refuses before rendering
Logging level, sinks, retention Structured log + audit + UI notification share one reporter

If a limit is reached the operation fails with a diagnostic that names the limit; raise the limit deliberately and record why.

3. Stores and backups

  • Reports, dashboards, questions, parts, templates, semantic models and subscriptions are stored through the host's IReportStore family. Every write is versioned and ETag-guarded: a stale writer is refused instead of overwriting.
  • Versions are retained by the store's retention policy. The designer's Versions pane compares two versions and can restore the older one (an audited, versioned write).
  • Back up the store by its own mechanism (database backup or file copy of the storage root). The library adds no hidden files except the optional preview cache, which need not be backed up.
  • Restore procedure: restore the store, restart the host, confirm the health endpoint, then open one report and one dashboard.

4. Scheduling, delivery and alerts

  • Schedules are stored subscriptions with a cron-like schedule, culture, parameters, formats and recipients.
  • Recipients resolve from explicit users/groups, dataset-driven addresses (with caps and an allow-list) and external addresses when the policy permits them; duplicates are removed before rendering.
  • Delivery renders once per culture/parameter scope and delivers per recipient with a stable run key; retries are idempotent and failures land on a dead-letter list that can be replayed.
  • Alerts evaluate a metric against a threshold and deliver only on a state change; the evaluation floor and outside-hours policy are configuration.
  • Quotas: recipients, runs per window, artifact bytes and concurrency. A refused run is reported before any rendering work.

5. Security

  • Authentication is the host's (for example ASP.NET Core authentication). The library consumes a ReportPrincipal; it does not implement login, MFA or password reset.
  • Authorization is per action: read, write, certify, approve, deliver, administer. Refusals are diagnostics and audit events, never silent no-ops.
  • Tenants: every stored document and cache key includes the tenant; cross-tenant reads are refused.
  • Scripts: off unless the administrator enables them; server hosts refuse them by default. A script that times out or throws is reported, never ignored.
  • Secrets in connection definitions are masked in logs and audit; never place secrets in report files.
  • Embedding uses short-lived scoped tokens and a CSP/frame policy; the threat model is in SECURITY_REVIEW.md.

6. Observability and health

  • Every operation reports through IOperationReporter (log, audit, UI). Logs and audit are English and culture-invariant.
  • /metrics exposes counters and timings for engine runs, renders, delivery and alerts. Tag keys never contain PII.
  • /health (liveness) and /health/ready (store reachable, data provider reachable) are the probes for the platform.
  • Trace and correlate by the Outcome reference id; the same id appears in the log, the audit entry and the user message.

7. Runbook

Situation First check Action
A report fails to open Error list and diagnostics Fix the definition; the pointer names the band/item/property
A report renders but the wrong data shows Data source/provider, parameters, culture Confirm the provider, filter and parameter values in the run log
A save is refused Stored version/ETag Reload or save as a new report; never force-overwrite
A scheduled run did not happen Schedule enabled, quota, run window Inspect the run history; replay the dead-letter entry after fixing the cause
A delivery failed Delivery log per recipient Fix the address/provider and replay; do not re-render if the artifact is intact
Rendering is slow Page store, provider row caps, image sizes Lower limits, add store capacity, or narrow the selection
Scripts stopped working Script policy and compiler availability Enable scripts deliberately or remove the script

8. Upgrades

  1. Back up the store and the host configuration.
  2. Deploy the new build beside the old one; schema migrations for this project's own format run on load and are additive.
  3. Start the host, confirm /health/ready, then open one report, one dashboard and one subscription run.
  4. Keep the previous build until the smoke checks pass; a stale client receives BR0002 rather than reading a newer file wrongly.

9. Troubleshooting reference

Diagnostic codes and their fixes are generated in DIAGNOSTICS.md. Output capabilities and limits per format are in OUTPUT_FORMATS.md. Language packs, RTL and culture fallback are in LOCALIZATION.md. Release blockers and open decisions are in REMAINING_WORK_AUDIT.md.