Skip to content
DocsentryDocsentry

Backup

What has to be backed up

Section titled “What has to be backed up”

Three things, and losing any one of them makes the others less useful:

Component Why Losing it means
The database Every document record, version, permission, workflow, and audit entry. Everything.
The storage root The content-addressed blobs - the actual file contents. Documents are listed but cannot be retrieved.
The Data Protection key ring Protects authentication cookies and stored secrets such as the antivirus API key. Every session is invalidated and stored secrets become unreadable.

The key ring is machine-scoped when protected with DPAPI, which means a DPAPI-protected key ring cannot be restored onto a different machine. If your recovery plan involves new hardware, use certificate protection instead - DataProtection:CertificateThumbprint. Discovering this during a recovery is a bad time to discover it.

The backup tool

Section titled “The backup tool”

tools/Docsentry.Backup produces a backup set containing the database backup, the storage tree, a signed manifest, and a secret inventory - all inside an encrypted envelope.

The manifest is canonical JSON listing every part with its hash, signed separately from the envelope, so a tampered or truncated set is detectable rather than merely unlikely.

The database backup is taken with COPY_ONLY and then verified. COPY_ONLY is unconditional: without it, this tool would insert itself into whatever differential or log backup chain the database team already runs and silently break their restore sequence.

Command reference: Backup CLI.

The restore gap

Section titled “The restore gap”

The practical consequence: a successful backup is not a tested recovery. Rehearse a restore into a scratch environment before you need one, and write down what you did.

Restoring: what to expect

Section titled “Restoring: what to expect”

Two things reliably surprise people.

Orphaned database users

Section titled “Orphaned database users”

Restoring a database onto a different SQL Server instance leaves its users orphaned - the user exists inside the database but no longer maps to a server login. The application then fails to authenticate at startup.

The fix is to remap them:

ALTER USER [DocsentryApp] WITH LOGIN = [DocsentryApp];

This is invisible until the application tries to start, so check it as part of the restore rather than waiting for the failure.

The key ring

Section titled “The key ring”

If the key ring was not restored, or was DPAPI-protected on a different machine, every existing authentication cookie is invalid and stored secrets cannot be decrypted. Users are signed out - recoverable - and the antivirus API key must be re-entered - also recoverable, but only if someone knows it.

What not to rely on

Section titled “What not to rely on”
  • Database backups alone. They contain no file content.
  • Storage backups alone. Blobs are named by hash; without the database there is no mapping from a document to its bytes.
  • The recycle bin. It is a user convenience with a retention period, not a backup.
  • Content-addressed deduplication. It saves space; it is not redundancy. One corrupted blob affects every document referencing it.

Verifying backups

Section titled “Verifying backups”

Run docsentry-backup selftest after installing the tool on a new host and after any change to key provisioning. It exercises the cryptographic round-trip and manifest signing - the part of the pipeline that fails silently.

Use docsentry-backup list to confirm sets are actually arriving at their destination. A backup job whose failures are not surfaced is a backup job that is not running.

Then, periodically, do the thing that actually matters: restore a set into a scratch environment and sign in.

Section titled “Related”