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.

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`	Content-addressed blob store. Storage-root-relative.

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`

All are enabled by default except FolderEmailIntake. 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.
`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.
`MailboxFolder`	string	`INBOX`	Mailbox folder to read.
`BatchSize`	int	`50`	Messages per pass.

Hangfire

Key	Type	Default	Description
`DashboardPath`	string	`/hangfire`	Dashboard route. Administrator-only.
`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. Set `false` only for capacity testing.
`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.

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.

AccountSecurity

Key	Type	Default	Description
`MaxFailedAccessAttempts`	int	`5`	Failed sign-ins before lockout.
`LockoutMinutes`	int	`15`	Lockout duration.
`AllowSelfRegistration`	bool	`false`	Enabling this auto-confirms new accounts with no email round trip. Do not enable on an internet-facing deployment.

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

Not present in appsettings.json; these 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.

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.
`DOCSENTRY_TEST_CONNECTION_STRING`	Connection string for the database integration test suite. Without it the entire suite skips and still reports success.