Configuration keys

Every key below lives in appsettings.json unless noted. Options are bound with validation on start, so an invalid value stops the host rather than surfacing later.

Override any key by environment variable using __ as the section separator:

DmsDataAccess__MaxPoolSize=200
Security__Hsts__MaxAgeDays=90

For the guided version of this material, see Configuration.

ConnectionStrings

Key	Type	Default	Description
`DefaultConnection`	string	placeholder	Required. Must authenticate as a least-privilege `DocsentryAppRole` member, not the deployment or schema-owner principal. Verified at startup. Supply it from the environment or a secret store; startup warns if it comes from a JSON file.

DmsDataAccess

Key	Type	Default	Description
`MaxPoolSize`	int	`100`	Ceiling on concurrent SQL connections. The primary capacity lever.
`CommandTimeoutSeconds`	int	`30`	Timeout applied to every command.
`DefaultPageSize`	int	`50`	Page size when a caller does not specify one.
`MaxPageSize`	int	`200`	Ceiling on a requested page size.

Folders

Key	Type	Default	Description
`MaxDepth`	int	`10`	Maximum folder nesting depth. Validation caps this at 25.

Storage

Key	Type	Default	Description
`RootPath`	string	`App_Data/storage`	Root of the file store.
`ProviderName`	string	`filesystem`	Storage provider.
`TempSubpath`	string	`temp`	In-progress upload data. Storage-root-relative.
`QuarantineSubpath`	string	`quarantine`	Content that failed scanning. Storage-root-relative.
`BlobSubpath`	string	`blobs`	Encrypted content store. Storage-root-relative.
`WorkingCopyPath`	string	`""`	Where renderers, OCR and bulk export get a short-lived decrypted copy. Empty means a folder under the system temp directory. Must be outside `RootPath`; at most 80 characters.

Uploads

Key	Type	Default	Description
`ChunkSizeBytes`	int	`4194304` (4 MB)	Chunk size for resumable uploads.
`MaxFileSizeBytes`	long	`104857600` (100 MB)	Ceiling on a single file.
`AllowedContentTypes`	string[]	PDF, PNG, JPEG, text/plain, Word and Excel open formats	Global upload allowlist.
`SessionLifetime`	timespan	`02:00:00`	How long an incomplete upload session survives.

PreviewOptions

Key	Type	Default	Description
`PreviewSubpath`	string	`previews`	Where artefacts are written. Storage-root-relative.
`MaxWidth`	int	`1600`	Preview width bound.
`MaxHeight`	int	`2000`	Preview height bound.
`ThumbnailMaxEdge`	int	`320`	Thumbnail longest-edge bound.
`ArtifactFormat`	string	`webp`	Output format.
`ImageContentTypes`	string[]	JPEG, PNG, GIF, WebP, TIFF, BMP	Rendered directly.
`PdfContentType`	string	`application/pdf`	Rasterised.
`OfficeContentTypes`	string[]	Word, Excel, PowerPoint and open equivalents	Converted to PDF first.
`SofficePath`	string	`""`	Path to `soffice`. Empty means auto-discover.
`SofficeTimeout`	timespan	`00:01:00`	Bound on one conversion.

BackgroundJobs

Each job block takes at least Enabled (bool), Interval (timespan), and MaxItems (int).

Job	Interval	MaxItems	Extra
`PermissionRebuild`	`00:00:30`	200	-
`ReminderDispatch`	`00:01:00`	200	-
`SignatureExpiry`	`00:05:00`	200	-
`RetentionCleanup`	`01:00:00`	200	-
`FolderEmailIntake`	`00:05:00`	-	`Enabled: false`
`UploadSessionSweep`	`00:15:00`	200	`SessionLifetime` `1.00:00:00`
`OrphanByteReclamation`	`06:00:00`	200	`MinimumAge` `01:00:00`
`WorkflowEscalation`	`00:15:00`	200	`EscalationWindow` `2.00:00:00`
`StorageIntegrity`	`12:00:00`	500	-
`PreviewGeneration`	`00:15:00`	200	`MaxAttempts` 3
`OcrBackfill`	`00:15:00`	100	-
`EmailDelivery`	`00:01:00`	100	`MaxAttempts` 3, `BaseBackoff` `00:01:00`, `LeaseTimeout` `00:05:00`, `HoldingWindow` `3.00:00:00`
`PrivacyRetention`	`1.00:00:00`	500	`ResumeErasuresOlderThan` `00:10:00`
`StorageSidecarBackfill`	`00:15:00`	100	-
`StorageEncryptionBackfill`	`00:15:00`	100	-
`AntivirusBackfill`	`00:05:00`	5000	`TimeBudget` `00:04:00` (must stay below `Interval`)
`StorageReadRemediation`	`00:02:00`	-	`TimeBudget` `00:01:30`, `BatchSize` 500

All are enabled by default except FolderEmailIntake. A job checks its Enabled flag at the start of every run, so disabling it also stops runs already queued. See Background jobs.

Email

Key	Type	Default	Description
`Enabled`	bool	`false`	Master switch for outbound mail.
`Host`	string	`""`	SMTP host.
`Port`	int	`587`	SMTP port.
`UseStartTls`	bool	`true`	Upgrade with STARTTLS.
`Username`	string	`""`	SMTP username.
`Password`	string	`""`	SMTP password. Supply as `Email__Password` or from a secret store.
`ApiKey`	string	`""`	API key, where the provider uses one.
`FromAddress`	string	`""`	Sender address.

EmailIntake

Key	Type	Default	Description
`Enabled`	bool	`false`	Master switch for inbound intake.
`Host`	string	`""`	IMAP host.
`Port`	int	`993`	IMAP port.
`UseSsl`	bool	`true`	Use SSL.
`Username`	string	`""`	Mailbox username.
`Password`	string	`""`	Mailbox password. Supply as `EmailIntake__Password` or from a secret store.
`MailboxFolder`	string	`INBOX`	Mailbox folder to read.
`BatchSize`	int	`50`	Messages per pass.

Hangfire

Key	Type	Default	Description
`DashboardPath`	string	`/hangfire`	Dashboard route. Administrators only, after two-factor sign-in.
`SchemaName`	string	`HangFire`	Database schema for job storage.
`SchedulePollingInterval`	timespan	`00:00:05`	Scheduler poll interval.
`RetryAttempts`	int	`3`	Automatic retries for a failed job.

Workflows

Key	Type	Default	Description
`Engine`	string	`Dapper`	`Dapper` or `Elsa`. Elsa requires its deploy script; the host fails fast otherwise.

RateLimiting

Key	Type	Default	Description
`Enabled`	bool	`true`	Master switch. Leave on in production.
`WindowSeconds`	int	`10`	General request window.
`AuthenticatedPermitLimit`	int	`200`	Requests per window for an authenticated caller.
`AnonymousPermitLimit`	int	`50`	Requests per window for an anonymous caller.
`AuthenticationWindowSeconds`	int	`300`	Window for authentication attempts.
`AuthenticationPermitLimit`	int	`100`	Per-address authentication attempts per window.
`AuthenticationAccountPermitLimit`	int	`10`	Per-account authentication attempts per window, across all addresses.
`CredentialVerificationPermitLimit`	int	`10`	Per-user submissions of change password, enable authenticator and delete personal data per authentication window. Must be at least 1.

AuthenticationConcurrency

Key	Type	Default	Description
`Enabled`	bool	`true`	Bound concurrent password verification.
`RetryAfterSeconds`	int	`5`	`Retry-After` value on a shed request.
`PermitLimit`	int	processor count	Concurrent verifications. Code default; override only after measuring.
`QueueLimit`	int	4x processor count	Queued verifications before shedding with 503.

DataProtection

Key	Type	Default	Description
`KeyPath`	string	absent	Required outside Development. Absolute path, outside the content root. The host refuses to start without it.
`CertificateThumbprint`	string	absent	X.509 certificate from the `CurrentUser` or `LocalMachine` `My` store. Required for non-Windows hosts, multi-instance deployments, and restorable backups. Omitted means machine-scoped DPAPI.

ContentIsolation

Key	Type	Default	Description
`ContentOrigin`	string	absent	Origin of the optional cookieless content host, for example `https://content.example.org`. `http` is refused outside Development.
`ApplicationOrigin`	string	absent	The application’s public origin. Required when `ContentOrigin` is set, and must differ from it.
`TokenLifetimeMinutes`	int	`5`	Lifetime of a signed content link. 1 to 60.

PublicSite

Key	Type	Default	Description
`BaseUrl`	string	`""`	Public address used to build links in email. Falls back to `ContentIsolation:ApplicationOrigin`. A path prefix is allowed; a query string or fragment is not.

AccountSecurity

Key	Type	Default	Description
`MaxFailedAccessAttempts`	int	`5`	Failed sign-ins before lockout.
`LockoutMinutes`	int	`15`	Lockout duration.
`MandatoryTwoFactorRoles`	string[]	`["Administrator"]`	Roles that must enrol an authenticator before using the application. Empty disables enforcement.
`SecurityStampValidationMinutes`	int	`2`	Session revalidation interval, and so how quickly revocation takes effect. 1 to 60.
`InvitationLifetime`	timespan	`7.00:00:00`	Validity of an invitation link. 1 hour to 30 days.

There is no self-registration setting; accounts are created by administrators.

BreachedPasswords

Key	Type	Default	Description
`Source`	enum	`None`	`None`, `OfflineFile` (recommended), or `HibpRange`.
`OfflineFilePath`	string	`null`	Absolute path to a Pwned Passwords “SHA-1, ordered by hash” file.
`OnlineEndpoint`	string	`https://api.pwnedpasswords.com/range/`	Range API endpoint for `HibpRange`.
`OnlineTimeoutSeconds`	int	`3`	Timeout for the range API.
`OnSourceUnavailable`	enum	`Permit`	`Permit` (accept and log a warning) or `Reject`.

Security

Key	Type	Default	Description
`Csp:Mode`	string	`Enforce`	Content Security Policy mode. Reporting mode is for validating a change, not a deployment state.
`Csp:ReportUri`	string	`""`	Where violation reports are sent.
`Hsts:MaxAgeDays`	int	`365`	HSTS max-age.
`Hsts:IncludeSubDomains`	bool	`true`	Apply to subdomains.
`Hsts:Preload`	bool	`false`	Preload list. Effectively irreversible - enable deliberately.
`ForwardedHeaders:KnownProxies`	string[]	`[]`	Trusted proxy addresses.
`ForwardedHeaders:KnownNetworks`	string[]	`[]`	Trusted proxy networks.
`ForwardedHeaders:ForwardLimit`	int	`1`	Proxies in the chain.
`ReferrerPolicy`	string	`strict-origin-when-cross-origin`	Referrer-Policy header.
`PermissionsPolicy`	string	camera, microphone, geolocation, interest-cohort disabled	Permissions-Policy header.

Forwarded-header handling is fail-closed: with no known proxy or network configured, forwarded headers are not trusted at all.

Antivirus

Only VirusTotalRequestsPerMinute is present in appsettings.json; the rest are code defaults.

Key	Type	Default	Description
`Enabled`	bool	`true`	Master switch.
`ScannerKind`	enum	`Eicar`	`Eicar`, `ClamAv`, or `VirusTotal`. Change from the default before production.
`Host`	string	`localhost`	ClamAV host.
`Port`	int	`3310`	ClamAV port.
`TimeoutSeconds`	int	`30`	Bound on one scan.
`VirusTotalBaseUrl`	string	`https://www.virustotal.com/api/v3/`	Service endpoint.
`VirusTotalApiKey`	string	-	Stored encrypted.
`VirusTotalUnknownPolicy`	enum	`FailClosed`	`FailClosed` or `TreatAsClean` for a hash the service has not seen.
`VirusTotalCacheMinutes`	int	`10`	Verdict cache lifetime.
`VirusTotalRequestsPerMinute`	int	`4`	Pace of the background re-scan sweep’s VirusTotal lookups.

Ocr

Not present in appsettings.json; these are code defaults.

Key	Type	Default	Description
`Enabled`	bool	`true`	Master switch.
`Languages`	string	`eng+ara`	Trained models, joined with `+`.
`TimeoutSeconds`	int	`120`	Bound on one document.
`MaxImagePixels`	int	40,000,000	Raster cap, per page.
`ImageExtensions`	string[]	image extensions	Which files are treated as images.
`TesseractPath`	string	-	Engine executable.
`TessdataPrefix`	string	-	Language data directory.

Bulk

Key	Type	Default	Description
`MaxItemsPerRequest`	int	`200`	Cap on one bulk operation.

Logging and Serilog

Key	Type	Default	Description
`Logging:SlowRequestThresholdMs`	int	`1000`	Requests above this are logged as slow.
`Logging:LogLevel:Default`	string	`Information`	Default level.
`Serilog:MinimumLevel`	object	`Information`, ASP.NET Core at `Warning`	Structured logging levels.
`Serilog:WriteTo`	array	Console	Sinks.

AllowedHosts

Key	Type	Default	Description
`AllowedHosts`	string	`docsentry.example.com`	Placeholder. Leaving it unchanged makes host filtering reject every request with a bare 400 and no explanatory log entry. Development overrides it to `*`.

Bootstrap

Supplied by user secrets or environment, not appsettings.json.

Key	Type	Description
`Bootstrap:AdminEmail`	string	First administrator’s email. Both keys must be present or seeding is skipped.
`Bootstrap:AdminPassword`	string	First administrator’s password. Must meet the password policy.

Environment variables

Variable	Purpose
`ASPNETCORE_ENVIRONMENT`	Selects the environment. Anything but `Development` enables the strict startup checks.