Skip to main content
Use suchi export when you want a portable archive of document originals and the metadata supported by Suchi sidecars. For disaster recovery or an exact instance migration, use a complete DATA_DIR backup instead. A portable export does not contain users, settings, audit history, or every document field.

​
Export the source archive

Stop the source server, then run the command with that instance’s DATA_DIR configuration. A running server owns the archive lock, so a concurrent export fails with archive_in_use instead of reading changing state:
Without a scope flag, Suchi selects the only owner with live documents. For an empty selected system, it falls back only when the instance has one enabled admin. Every other case stops and requires --owner-id or --all:
The destination must be outside DATA_DIR. Suchi writes a mode-0600 temporary archive beside the destination, syncs and closes it, then publishes it atomically. An existing destination is preserved unless --force is present. Missing original blobs fail the export and leave no partial output; use --allow-incomplete only for deliberate recovery, then inspect the manifest’s skipped count. Trashed documents are excluded. Check the archive before moving it:
The zip contains original files and matching JSON sidecars under documents/. The files under taxonomy/ are reference dumps; they are not automatically installed by the restore process. Manifest version "3" identifies the selected system code/name; --all means all owners there, not all systems. Sidecar format stays 1 with optional title_owner, jd_system, jd_address, custom_fields, and archive_serial_number. jd_address is an informational category address and can repeat across sidecars; intake routes with jd_system and files with jd_category, not the address. These fields preserve naming precedence, typed values, the available physical identifier, and source-system context; they are not an ID-preserving restore protocol. custom_fields leaves out document-link values, whose target IDs change, and extraction-managed invoice_* fields, which intake reads again from the original.

​
Prepare the fresh instance

  1. Start the target and complete first-run account setup.
  2. Apply the target filing tree before ingesting documents. For a named export, introduce the same target code through a prefixed taxonomy import first. Sidecar jd_system must match the watcher target; it cannot create or route a system. Category codes resolve there; an absent code falls back to its Inbox.
  3. Recreate the custom-field definitions listed in taxonomy/custom_fields.json with the same names, types, and choices; skip the invoice_* fields, which Suchi creates itself. A sidecar that names an undefined field rejects that document.
  4. Grant the intended owner entry and configure the watcher for that target.
The watcher can be configured in Settings, or with environment variables:
When using environment variables, restart Suchi after the owner account exists. At startup, the watcher must be able to resolve INGEST_FS_OWNER_EMAIL to an enabled user. Omit INGEST_FS_SYSTEM only when intentionally targeting the original system. Documents may receive new IDs and addresses. Memberships, ACLs and relationships are not reconstructed by sidecars; exact restoration requires a whole-instance backup.

​
Restore the documents

Extract outside the active staging directory:
Copy sidecars first, then originals. This prevents the watcher from ingesting an original during a copy before its metadata file is visible:
Do not use suchi import --from for this zip. That command consumes a Paperless-compatible Django manifest, not the native Suchi export format. The watcher is read-only: it leaves successfully ingested and rejected source files and sidecars in place. Follow server logs for fswatch.ingested; bounded failures are recorded in Suchi-owned observation state and audit. Dropping the same export again into the same system for the same owner is document-safe: live documents deduplicate by SHA-256. Another system receives distinct document rows even if immutable CAS bytes are shared. A duplicate drop does not update metadata; edit existing records through Suchi.

​
What survives the round trip

For those omitted fields, or when the exact taxonomy and user configuration must survive, restore a complete DATA_DIR backup.

​
Verify the target

Confirm the document count and open samples from each important file type. Check their title, source date, filing category, tags, correspondent roles, and ASNs. Then verify the content-addressed store:
After verification, remove the extracted working directory and protect or delete the export according to the archive’s data-retention policy.