Document storage

Jiandu stores original files and durable processing artifacts as blobs. Search indexes, document metadata, permissions, and work coordination live in the selected database. A usable installation needs both halves, and a recoverable installation protects them at the same logical point in time.

Choose a backend

Backend	Choose it when	Main tradeoff
Local disk	Jiandu runs on one durable host and you want the simplest system	You own disk redundancy, off-host backup, and host recovery
Amazon S3	You already use AWS and can grant a narrow workload identity	Remote requests, cloud cost, IAM, and bucket policy become dependencies
S3-compatible	You operate MinIO or prefer R2, Backblaze B2, or Wasabi	Compatibility details such as endpoint, region, and addressing style differ
WebDAV	You already operate Nextcloud, ownCloud, Synology, or a conforming DAV server	Basic authentication and DAV behavior vary more between servers

Local disk is the recommended default for a single-host household deployment. Remote storage is a good fit when it gives you a recovery or operational capability you already know how to manage; it does not remove Jiandu's need for a private local work directory or a coordinated database backup.

Pick before importing

Changing storage.backend does not copy existing blobs. Jiandu does not currently provide a supported local-to-remote, remote-to-local, or remote-to-remote storage migration. Select and prove the backend before importing documents you care about.

Understand the two storage locations

The local backend has one durable blob_root. Remote backends instead use:

• a durable remote bucket or WebDAV collection containing content-addressed objects, publication records, deletion tombstones, and readiness probes; and
• a private local work_root for bounded upload staging and processing snapshots.

work_root is not a cache that can be placed on a read-only or ephemeral filesystem while Jiandu is running. It must be writable, private to the service account, and large enough for concurrent uploads and processing work. Published documents are not mirrored there.

Namespace one installation

Give one Jiandu installation a dedicated local directory, bucket, WebDAV collection, or remote prefix. A prefix is useful when organizational policy requires a shared bucket:

{
  "schema_version": 1,
  "storage": {
    "backend": "s3",
    "bucket": "household-archive",
    "region": "us-east-1",
    "prefix": "jiandu/primary",
    "work_root": "/var/lib/jiandu/storage-work"
  }
}

prefix is an object-key namespace, not a filesystem path. Use a stable value without a leading or trailing slash. Never point two Jiandu installations at the same bucket-and-prefix or DAV collection-and-prefix combination.

Transport and credentials

HTTPS is required for S3-compatible endpoints and WebDAV unless allow_http is explicitly true. That exception exists only for a trusted local network where a separate protected transport is already in place. It does not disable certificate validation for HTTPS.

Credential handling differs by backend:

• S3 uses the supported standard AWS environment/workload credential chain. Access keys do not belong in jiandu.json.
• WebDAV reads one password or app password from an owner-only file. Inline passwords and password-bearing URLs are not accepted.
• Local storage has no remote credential; operating-system ownership is its security boundary.

Back up the complete installation

A provider's versioning, replication, or snapshots protect only the blob side. A database backup without its referenced blobs is incomplete, and a bucket copy without database state cannot recreate the library. Use Jiandu's backup and restore workflow, then copy the verified backup to failure-independent storage.

Remote retention can conflict with deletion. Object Lock, legal holds, immutable snapshots, or a provider policy that denies delete may be appropriate for a backup target, but Jiandu's live namespace must be able to copy and delete objects as part of document lifecycle and crash recovery.

Validate before real use

Run validation as the service account:

jiandu --config /etc/jiandu/jiandu.json --check-config

Then start Jiandu and request readiness through the same origin users will open:

curl --fail --silent https://documents.example.net/api/v1/health/ready

For remote storage, readiness writes a unique small object, reads it back, and deletes it. That proves current network, credential, and basic object-operation access; it does not prove large multipart uploads, backup completeness, retention behavior, or recovery. Before importing real documents, also:

1. upload a non-sensitive document larger than 8 MiB when using S3, so multipart upload is tested;
2. open and download the original;
3. delete a disposable document and confirm the backend permits lifecycle operations;
4. create and verify a Jiandu recovery backup; and
5. restore that backup into an isolated destination and compare the sample original.

Common failure patterns

Symptom	Likely cause
Configuration validates but readiness is unavailable	The offline check does not contact the remote service; inspect endpoint, DNS, CA trust, and credentials
Small objects work but a larger upload fails	Multipart permissions, proxy body handling, or provider compatibility is incomplete
Reads work but deletion/recovery fails	Credential is read-only or retention/Object Lock blocks live-namespace deletes
HTTPS reports an unknown issuer	Install the private CA in the Jiandu host/container trust store; do not set allow_http to bypass a TLS problem
Existing documents disappear after a configuration change	The new backend or prefix is an empty namespace; restore the previous configuration rather than copying ad hoc

Continue with the guide for local disk, Amazon S3, S3-compatible services, or WebDAV. Every accepted field and environment override is listed in the configuration reference.