Store documents over WebDAV

Use WebDAV when you already operate a reliable DAV service and want Jiandu's blobs in a dedicated collection there. Jiandu supports authenticated RFC 4918-style operations with HTTP Basic authentication. It does not use an interactive login, bearer token, client certificate, or public share URL.

What the server must support

Jiandu uses PROPFIND listing, HEAD, GET, PUT, MKCOL, COPY, and DELETE. The server must allow nested collection creation, overwrite, and recursive PROPFIND (Depth: infinity) beneath the configured collection. It must return stable length and ETag metadata and must not rewrite document bytes.

Create the top-level collection before starting Jiandu. Jiandu creates its internal child collections and objects, but it does not provision an account or top-level share.

:::warning Test the exact service WebDAV implementations and reverse proxies vary. A successful mount or file download does not prove the recursive listing, server-side copy, conditional read, and deletion semantics Jiandu needs. Complete the verification sequence at the end of this page. :::

Common configuration

/etc/jiandu/jiandu.json

{
  "schema_version": 1,
  "data_directory": "/var/lib/jiandu",
  "storage": {
    "backend": "webdav",
    "endpoint": "https://dav.example.net/remote.php/dav/files/jiandu-service/jiandu/",
    "username": "jiandu-service",
    "password_file": "/run/secrets/jiandu-webdav-password",
    "prefix": "primary",
    "work_root": "/var/lib/jiandu/storage-work",
    "allow_http": false
  }
}

Field	Why it is needed
backend	Selects the DAV adapter; legacy owncloud is accepted as an alias, but webdav is clearer for new files
endpoint	Names the already-created private collection used as the storage root
username	Supplies the Basic-auth username separately from the URL
password_file	Keeps the password out of JSON, the environment, process arguments, and diagnostics
prefix	Isolates one Jiandu installation below the collection
work_root	Provides required private local staging and processing space
allow_http: false	Rejects plaintext transport and leaves certificate verification enabled

The endpoint may include a provider-specific path and should end at the collection dedicated to Jiandu. Do not include credentials, an object key, or a public-share token. Use a stable prefix without a leading or trailing slash.

Prepare the password and work directory

On Unix, the password file must be a non-empty regular file with exactly mode 0600, one hard link, and no symlink indirection. It may contain one trailing newline; surrounding whitespace is removed. Materialize it from your secret manager without placing the value in shell history:

sudo install -d -o jiandu -g jiandu -m 0700 /run/secrets
sudo install -o jiandu -g jiandu -m 0600 \
  /protected/input/jiandu-webdav-password \
  /run/secrets/jiandu-webdav-password
sudo install -d -o jiandu -g jiandu -m 0700 /var/lib/jiandu/storage-work
sudo -u jiandu jiandu --config /etc/jiandu/jiandu.json --check-config

--check-config opens and validates the password file but does not contact the server. The file must be visible at the same path inside the running container or service sandbox.

Nextcloud

Nextcloud's authenticated file endpoint is:

https://cloud.example.net/remote.php/dav/files/USERNAME/COLLECTION/

Use a dedicated Nextcloud account and app password. App passwords are independently revocable and are the correct Basic-auth credential when two-factor authentication or external login protects the human account. Do not use /public.php/dav, a share link, or a browser session cookie.

Nextcloud storage block

{
  "backend": "webdav",
  "endpoint": "https://cloud.example.net/remote.php/dav/files/jiandu-service/jiandu/",
  "username": "jiandu-service",
  "password_file": "/run/secrets/jiandu-webdav-password",
  "prefix": "primary",
  "work_root": "/var/lib/jiandu/storage-work",
  "allow_http": false
}

The URL path uses the account's internal username, which may differ from its display name or email address. Nextcloud documents the authenticated endpoint and app-password behavior in its WebDAV guide.

Nextcloud caveats:

• Server-side encryption, external storage mounts, antivirus hooks, and quotas can change latency or failure behavior. Test large files and recovery with the real account and collection.
• A reverse proxy in front of Nextcloud must pass PROPFIND, MKCOL, COPY, and DELETE, not only common browser methods.
• Syncing the same collection to desktops invites accidental edits. Keep the service collection out of ordinary user sync roots.
• File retention or trash features can increase storage use; they still do not coordinate with the Jiandu database.

ownCloud

Current ownCloud server deployments commonly use the same authenticated DAV path shape:

https://cloud.example.net/remote.php/dav/files/USERNAME/COLLECTION/

For an installation mounted below /owncloud, retain that prefix:

ownCloud storage block

{
  "backend": "webdav",
  "endpoint": "https://cloud.example.net/owncloud/remote.php/dav/files/jiandu-service/jiandu/",
  "username": "jiandu-service",
  "password_file": "/run/secrets/jiandu-webdav-password",
  "prefix": "primary",
  "work_root": "/var/lib/jiandu/storage-work",
  "allow_http": false
}

Use the authenticated user-files endpoint, not the legacy /remote.php/webdav compatibility path or a public-share endpoint. backend: "owncloud" remains accepted for older Jiandu configuration files and has the same runtime behavior; use webdav for a new deployment.

ownCloud caveats are similar to Nextcloud: verify the actual server version, storage layer, proxy method allowlist, quota, and app-password policy. An upgrade that changes DAV behavior deserves the same upload/download/delete/backup exercise as a storage configuration change.

Synology WebDAV Server

Synology WebDAV Server normally listens on port 5006 for HTTPS. Create a dedicated DSM user with read/write access only to a dedicated shared-folder path, then point Jiandu at that collection:

Synology storage block

{
  "backend": "webdav",
  "endpoint": "https://nas.example.net:5006/archive/jiandu/",
  "username": "jiandu-service",
  "password_file": "/run/secrets/jiandu-webdav-password",
  "prefix": "primary",
  "work_root": "/var/lib/jiandu/storage-work",
  "allow_http": false
}

The exact path begins with the DSM shared-folder name (archive above). Confirm it with a DAV client using the service account before starting Jiandu. Synology documents 5006 as the default HTTPS port in its WebDAV Server reference.

Synology caveats:

• Replace a default/self-signed NAS certificate with one trusted by the Jiandu runtime, or install your private CA there. Jiandu will not skip certificate verification.
• Do not fall back to port 5005 HTTP across a household LAN; Basic authentication would expose the password and document traffic.
• Snapshot Replication and recycle bins can improve recovery from accidental deletion, but capacity, database coordination, and restore drills remain your responsibility.
• DSM permission inheritance must leave the dedicated user able to create, list, copy, and delete nested collections.

Generic Apache or RFC 4918 server

Use a dedicated TLS virtual host and collection, for example:

{
  "backend": "webdav",
  "endpoint": "https://dav.example.net/jiandu/",
  "username": "jiandu-service",
  "password_file": "/run/secrets/jiandu-webdav-password",
  "prefix": "primary",
  "work_root": "/var/lib/jiandu/storage-work",
  "allow_http": false
}

Basic authentication must be enabled over HTTPS and the account must have full DAV access only beneath that collection. Disable anonymous writes, directory indexing for browsers, and unrelated methods at the edge without blocking the DAV methods listed above. If a WAF or proxy cannot pass a Destination header for COPY, that server is not usable for Jiandu's live storage.

Verify the complete behavior

1. Run --check-config as the service account.
2. Start Jiandu and request /api/v1/health/ready through the public Jiandu origin. Readiness writes, reads, and deletes a unique probe object.
3. Upload a non-sensitive multi-megabyte document, then open and download its original.
4. Delete a disposable document and confirm lifecycle completion.
5. Create and verify a recovery backup.
6. Restore the backup to an isolated local destination and hash-compare the sample original.

Diagnose failures

Status or symptom	What to inspect
401	Internal username, app password, Basic authentication, and whether a login proxy blocks non-browser clients
403	Collection ACL, quota, read-only mount, WAF method rules, or retention policy
404	Provider-specific endpoint path, username path segment, existing top-level collection, or reverse-proxy rewrite
405 or 501	Missing PROPFIND, MKCOL, COPY, or DELETE support
409 during writes/copy	Parent collection creation or Destination header handling
TLS issuer/hostname error	Server certificate chain, endpoint DNS name, and runtime trust store
Readiness works but cleanup fails later	Recursive listing, copy, delete, retention, or provider behavior under deeper paths

Do not change endpoint or prefix to make an error disappear on an existing installation. That selects another namespace and leaves the original documents behind.