Administrator guide
Deploy, configure, back up, schedule and run it.
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
IReportStorefamily. 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. /metricsexposes 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
Outcomereference 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
- Back up the store and the host configuration.
- Deploy the new build beside the old one; schema migrations for this project's own format run on load and are additive.
- Start the host, confirm
/health/ready, then open one report, one dashboard and one subscription run. - Keep the previous build until the smoke checks pass; a stale client receives
BR0002rather 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.