> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suchi.page/llms.txt
> Use this file to discover all available pages before exploring further.

# Reingest a Suchi takeout

> Export one system's live documents and reingest them through a configured target watcher; use full backups for exact restoration.

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](/backup-restore)
instead. A portable export does not contain users, settings, audit history, or
every document field.

## Export the source archive

Run the command with the source instance's `DATA_DIR` configuration:

```sh theme={null}
suchi export --out /tmp/suchi-export.zip
```

By default this selects original system 1 and its live documents owned by the first
admin account. Choose the target and owner scope explicitly:

```sh theme={null}
suchi export --out /tmp/user-5.zip --owner-id 5
suchi export --out /tmp/S02-all-users.zip --system S02 --all
```

Trashed documents are excluded. Check the archive before moving it:

```sh theme={null}
unzip -t /tmp/suchi-export.zip
unzip -p /tmp/suchi-export.zip manifest.json
```

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 `"2"` identifies the selected system code/name; `--all` means all
owners there, not all systems. Sidecar format stays 1 with optional `jd_system` and
`jd_address`. Those record the source, not an ID-preserving restore protocol.

## 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. Grant the intended owner entry and configure the watcher for that target.

The watcher can be configured in **Settings**, or with environment variables:

```sh theme={null}
INGEST_FS_OWNER_EMAIL=owner@example.com
INGEST_FS_DIR=/srv/suchi-staging
INGEST_FS_SYSTEM=S02
```

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:

```sh theme={null}
mkdir -p /tmp/suchi-restore /srv/suchi-staging
unzip /tmp/suchi-export.zip -d /tmp/suchi-restore
```

Copy sidecars first, then originals. This prevents the watcher from ingesting
an original during a copy before its metadata file is visible:

```sh theme={null}
find /tmp/suchi-restore/documents -maxdepth 1 -type f -name '*.json' \
  -exec cp '{}' /srv/suchi-staging/ ';'

find /tmp/suchi-restore/documents -maxdepth 1 -type f ! -name '*.json' \
  -exec cp '{}' /srv/suchi-staging/ ';'
```

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 removes successfully consumed originals and sidecars. Follow the
server logs for `fswatch.ingested`, and inspect
`/srv/suchi-staging/errors/` for a rejected file and its `.err` companion.

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

| Data                                                       | Result                                                                       |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Original bytes                                             | Preserved exactly; SHA-256 and MIME are recomputed on the target.            |
| Title and source date                                      | Restored. The target records its own ingest time separately.                 |
| Tags                                                       | Restored from tag slugs; display names can be normalized to their slug form. |
| Correspondents                                             | Restored, including sender, recipient, cc, and other roles.                  |
| Filing category                                            | Restored when the numeric code exists on the target; otherwise Inbox.        |
| Extracted text and thumbnails                              | Regenerated by the target pipeline and its installed tools.                  |
| Sensitivity                                                | Exported for provenance but not currently applied on ingest.                 |
| Notes and per-document custom-field values                 | Not exported in v0.1.                                                        |
| Versions, approvals, audit events, shares, and saved views | Not exported.                                                                |

For those omitted fields, or when the exact taxonomy and user configuration
must survive, restore a complete [`DATA_DIR` backup](/backup-restore).

## Verify the target

Confirm the document count and open samples from each important file type.
Check their title, source date, filing category, tags, and correspondent roles.
Then verify the content-addressed store:

```sh theme={null}
suchi doctor --scrub-cas
```

After verification, remove the extracted working directory and protect or
delete the export according to the archive's data-retention policy.