Skip to main content

Store documents on local disk

Local disk is Jiandu's default and the recommended choice for one durable host. It has the fewest dependencies, the lowest request latency, and the simplest recovery story. Choose a remote backend only when its operational benefits outweigh another network and credential boundary.

Before you begin​

Choose a filesystem that is:

  • persistent across service or container replacement;
  • mounted before Jiandu starts;
  • writable only by the Jiandu service account;
  • backed up outside the host; and
  • large enough for originals, derived artifacts, and future growth.

Do not use /tmp, an ephemeral container layer, a user-synchronized folder, or a network filesystem. SQLite and local blobs may share the same durable filesystem, but each keeps its own path.

Configure the blob root​

The minimal explicit configuration is:

/etc/jiandu/jiandu.json
{
  "schema_version": 1,
  "data_directory": "/var/lib/jiandu",
  "storage": {
    "backend": "local",
    "blob_root": "/var/lib/jiandu/blobs"
  }
}

Prepare the parent as the account that will run Jiandu. Replace jiandu:jiandu if your package or container uses a different UID and GID:

sudo install -d -o jiandu -g jiandu -m 0700 /var/lib/jiandu
sudo install -d -o jiandu -g jiandu -m 0700 /var/lib/jiandu/blobs
sudo -u jiandu jiandu --config /etc/jiandu/jiandu.json --check-config

On Unix, an existing blob root must be a real directory with mode 0700; a symlink or broader permissions fail closed. Jiandu creates an absent root privately, but preparing it deliberately makes mount and ownership mistakes visible before startup.

Use data_directory for a compact layout​

If you omit storage.blob_root, the default is <data_directory>/blobs:

{
  "schema_version": 1,
  "data_directory": "/var/lib/jiandu",
  "storage": {
    "backend": "local"
  }
}

This is usually preferable because --data-dir can move the SQLite database, blob root, and owner token together. Use an explicit blob_root only when documents must live on a separate filesystem.

Environment equivalents are useful for immutable container images:

export JIANDU_BLOB_BACKEND=local
export JIANDU_BLOB_ROOT=/var/lib/jiandu/blobs
jiandu --config /etc/jiandu/jiandu.json --check-config

Container mounts​

Mount a named volume or host directory at the configured path. The important property is that the mount belongs to the service rather than the disposable container layer:

services:
  jiandu:
    environment:
      JIANDU_DATA_DIR: /app/jiandu-data
      JIANDU_BLOB_BACKEND: local
    volumes:
      - jiandu-data:/app/jiandu-data

volumes:
  jiandu-data:

Do not add a second replica that mounts the same directory. Jiandu supports one owning application process per installation, even if the volume driver provides multi-attach access.

Capacity and filesystem behavior​

Plan capacity from the source material, not just today's database size. Originals are content-addressed and deduplicated by digest within the installation, while processing and reprocessing also need bounded temporary space. Alert on both free bytes and free inodes.

Prefer a local filesystem with reliable atomic rename, fsync, regular-file, and directory semantics. Consumer sync clients and many network filesystems can reorder writes, replace files behind the process, or expose permissive ownership that violates Jiandu's safety checks.

:::caution A RAID mirror is not a backup Mirroring can improve availability after one disk failure, but it also mirrors deletion, corruption, and operator mistakes. Keep a verified recovery backup on a failure-independent target. :::

Verify the installation​

After starting Jiandu, check readiness through its configured ingress:

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

Then upload, open, download, and delete a disposable document. A readiness response proves the fixed blob directory identity is usable; the document exercise proves the application workflow and available capacity.

Before accepting the storage choice:

  1. create a recovery backup;
  2. copy it off-host;
  3. run verify-backup on the copied archive; and
  4. complete an isolated restore drill.

Avoid these configurations​

  • A Docker bind mount whose host directory is owned by a different UID.
  • A blob root inside the source checkout or application image.
  • A NAS mount treated as local disk; use a proven supported remote protocol instead.
  • Filesystem snapshots taken without coordinating the database and blobs.
  • Manual editing, deduplication, or cleanup beneath blob_root.

Jiandu owns the blob layout. Use the application lifecycle and backup tools rather than manipulating content-addressed paths directly.

Last updated on