Skip to main content
Suchi keeps persistent application state under DATA_DIR:

​
What a complete backup needs

Back up a consistent suchi.db snapshot together with blobs/, .decrypt-key, and any operator configuration stored in the directory. The database without blobs/ has metadata but no document bytes. The database without .decrypt-key cannot open sealed mailbox, OAuth, PDF-password, or LLM credentials. rendered/ is generated state and can be rebuilt. A cleanly stopped database does not need its WAL or shared-memory files. An atomic snapshot of a live archive must include the database and its WAL together; never copy them at different times. The generated filing index contains only the current system/tree map and descriptions. Taxonomy exports can also contain representable preset starters; neither preserves documents, user-owned rules, permissions or review/version/link history. They cannot replace a complete backup. Keep the generated index namespace reserved for Suchi; see the filing guide for refresh, recovery and legacy-category diagnostics. A complete backup is whole-instance: systems share SQLite, CAS and credential keys. It preserves membership, ACLs, document/version/link relationships and the global document-ID high-water state. Host/backup operators can access every system and remain trusted; a filing prefix is not backup isolation or per-system encryption. Native takeout manifest v2 selects one system and is deliberately partial; source addresses do not request preservation of IDs when documents are ingested again. The mbsync deployment keeps credentials and Maildir state outside DATA_DIR; back up its deployment directory separately when that path is used.

​
Built-in database snapshots

Every BACKUP_INTERVAL (default 24h), Suchi creates a consistent SQLite snapshot at:
It retains the newest BACKUP_KEEP snapshots, defaulting to seven. BACKUP_INTERVAL=0 disables the loop. These snapshots include only the database. A complete backup also needs document files, the credential key, and configuration. Offline GC consults the live database, not these older snapshots, so it can reclaim bytes that an older snapshot still references. Keep a complete backup for disaster recovery.

​
Backup methods

​
Stop and copy

Stopping Suchi before copying the directory is the simplest consistent method. Stop CLI imports and other archive writers too; do not run GC during the copy:

​
Atomic filesystem snapshot

Filesystem snapshots such as ZFS, btrfs, or LVM are suitable when they capture the whole data directory atomically, including the database WAL, blobs, and keys. Copy from that stable snapshot, not from the changing live directory. Encrypted backup tools such as restic or Borg can archive the snapshot off-host. A database snapshot followed by a live blob-tree copy is not an atomic archive backup. A separate GC process could remove bytes still needed by that snapshot. Do not copy only a live suchi.db, copy WAL files separately, or omit blobs.

​
Restore

  1. Stop the target process.
  2. Move the existing DATA_DIR aside rather than deleting it immediately.
  3. Restore the database, blobs, credential key, and configuration into an empty directory.
  4. Set ownership and restrictive key permissions.
  5. Start Suchi. Newer binaries apply missing migrations automatically.
  6. Check /readyz, open known documents, run a search, and test one sealed integration such as a mailbox connection.
If rendered/ was omitted or the data directory moved, queue link rebuilding with suchi refile --skip-automations; add --system S01 for each additional system. The running server processes those jobs. Startup itself refreshes filing indexes and pending moves, not every document link. The restore drill in the manually dispatched checks workflow verifies a built-in database snapshot, then stops and copies a synthetic archive into a fresh directory. After restart it checks database integrity, key preservation, original document download, and search. Run it locally with make build and bash hack/smoke-restore.sh. It does not validate an operator’s off-host backup or external credentials; restore those into a scratch instance periodically.

​
Upgrade and rollback

Before an upgrade, take a complete backup using one of the methods above and keep the deployment pinned to an explicit version. Pull or install the new version, recreate or restart the single Suchi instance, then verify /readyz and run suchi doctor. Database migrations are one-way. To roll back after a migration, stop Suchi, restore the complete pre-upgrade data directory, install the previous binary or image, and verify readiness again. Do not run an older binary against a database opened by a newer release.

​
Retention and garbage collection

Choose retention based on recovery needs and applicable law. Deleting a document does not remove bytes from existing snapshots or external backups. Trash and its automatic 30-day retention permanently remove document rows and rendered files, but leave original and derived CAS bytes in place. suchi gc reports unreferenced blobs; suchi gc --apply removes them only during offline maintenance. Stop the server and all other archive writers before applying GC, and take a complete recoverable backup first. See CLI. Moving to another host uses the same procedure: create a consistent backup, restore it under the destination DATA_DIR, update ownership and PUBLIC_URL, then point the reverse proxy or DNS to the new instance.