Skip to content

Backup & Restore ​

Part of the Settings page — instance-wide backup and restore, superadmin only.

Export ​

Download backup downloads a single ZIP archive containing all tenants: their collections, schemas, rules, hooks, records, and uploaded files, plus the instance's API keys. It's an all-tenant snapshot, not a per-tenant export — there's no way to back up or restore a single tenant in isolation from this page.

API keys are stored as hashes. The archive contains those hashes, not the plaintext, which Paprika never keeps. A restored key therefore keeps working for whoever already has it.

Admin-session revocations are not part of the archive. They describe the sessions in circulation now, not data, so a restore leaves them as they are: a session that is revoked before the restore stays revoked after it.

Restore ​

Uploading a previously exported ZIP restores its contents.

This overwrites everything

Restoring a backup replaces the instance with the archive: tenants, collections, records, API keys, admin-session revocations, and uploaded files. It is not a merge. Anything created since the backup was taken is lost, including a file that is no longer in the archive — those files are deleted. The confirmation dialog spells this out; read it before confirming, especially on a production instance.

What happens before anything is written ​

The archive is read and checked in full first. If an entry is missing or unreadable — no system/users.json, a tenant the manifest lists but does not describe, a file that is not valid JSON — the restore is refused and nothing is written at all. An incomplete archive is treated as a broken archive, never as a set of empty collections.

An archive that contains no superadmin with a password is refused for the same reason: applying it would leave the instance with no way to sign in.

Once the archive has passed, Paprika exports the current state and writes it to pre-import-snapshots/ inside the local directory PAPRIKA_STORAGE before the first write. With the S3 backend that directory holds these snapshots and not the tenant files. The path is shown when the restore finishes and is included in the error message if the restore fails halfway through — restoring that archive puts the instance back. These snapshots are never deleted automatically; prune them yourself as part of your housekeeping.

Only restore archives you produced yourself

A backup contains the superadmin accounts, password hashes included. Restoring an archive somebody else handed you replaces your superadmins with theirs, which gives whoever created it access to this instance. Treat a backup file as a credential, not as a data file: keep it where you keep your secrets, and never restore one from an untrusted source.

How big an instance this works for ​

Export, snapshot and restore all happen in memory and in one piece: the whole archive is built as a single byte array, and a restore holds the uploaded ZIP, every unpacked entry and the parsed documents at the same time. That puts a ceiling on it, and the ceiling is lower than most people expect.

LimitValueWhere it comes from
Upload size of a restore64 MiB (67,108,864 bytes)Undertow's undertow.maxentitysize; a larger request body is refused before Paprika sees it
Upload size through the proxy1 MB unless you change itnginx's client_max_body_size default — set it to 64m, see nginx example
Uncompressed archive contents512 MBChecked while unpacking, as a zip-bomb guard
Entries in the archive10 000Collections plus uploaded files, across all tenants
Download size of an exportno limitOnly your heap

The first row is the one that decides. A restore works as long as the ZIP is at most 64 MiB (67,108,864 bytes) — compressed, so with JSON data that is a fair amount of records, but not many uploaded files. Raising it means replacing the whole bundled config.yaml via -Dapplication.config=…, which is a maintenance burden of its own; treat 64 MiB as the number to plan with.

An export is not proof of a working restore

Nothing limits the size of a download, so an instance that has grown past the upload limit keeps producing backups happily — and none of them can be restored through this page. Check the size of your export after every growth step, and while you are at it, restore it into a staging instance once. A backup you have never restored is a hypothesis.

Memory. Plan for several times the archive size in free heap during a restore: uploaded ZIP, unpacked entries, parsed BSON documents and the pre-import snapshot of the current state are all live at the same time. The packaged install runs with -XX:MaxRAMPercentage=70 and -XX:+ExitOnOutOfMemoryError, so an oversized restore ends the process instead of limping on — and because the snapshot is written before the first write, the state from before is on disk either way. In Docker the JVM defaults to 25 % of the container memory unless you set JAVA_OPTS.

Older archives. An export from before manifest version 2 has no system/api_keys.json. Restoring one still brings back tenants, records and files, and it still deletes tenant files that are not in the archive. It does not replace API keys, because the archive never contained them. A version 2 archive also contains system/token_revocations.json; it is restored without it, for the reason above. A current export is version 3, and a version 2 or 3 archive without system/api_keys.json is refused before anything is written.

Beyond that. For an instance too large for this page, back up at the infrastructure level: mongodump (or your provider's snapshots) for the databases, and a copy of the uploads taken at the same time — the PAPRIKA_STORAGE directory, or the bucket when the backend is S3. That path has no size limit and no memory cost in the application — it just does not give you the one-click restore this page does.

The snapshot directory. pre-import-snapshots/ grows by one full backup per restore, sits inside PAPRIKA_STORAGE with whatever permissions that directory has, and contains superadmin password hashes and every tenant's data. That stays a local directory even when tenant files are in a bucket. Protect it like a backup file and prune it deliberately.

When to use this ​

Because export/restore covers the whole instance, treat it as instance-level disaster recovery (moving to new infrastructure, restoring after data loss) rather than a per-tenant undo button. For everyday mistakes, fixing individual records on a collection's Data tab is safer than restoring a whole backup.