Backups that actually restore

A self-hosted 3D printing library restores only if the backup captured three things together and in one consistent moment: the database, the model and G-code files the application owns, and the configuration and key material that make those files readable again. Then keep a copy on a machine the server cannot reach, and restore it somewhere harmless before you need to. An untested archive is not a backup.

In PrintStash that means using its own backup rather than copying files underneath it, because the application is the only thing that can capture the database and the blobs it references at the same instant.

The archive it produces is a transactionally consistent snapshot of the database, including committed WAL data, plus the blob set owned by that same snapshot. A filesystem copy taken while the stack runs has no such guarantee, and the difference only shows up on the day you restore it.

Where backups go

Every backup is first written to the local backup directory. You can also configure an S3-compatible bucket such as Cloudflare R2 or MinIO, and PrintStash mirrors the archive there.

The archive contains the database, stored model and G-code files, documents, thumbnails, and a manifest. The consistency guarantee above arrived in v0.11.3, along with a restore that validates and stages the database and blobs before applying anything, pauses concurrent writers while it works, and rolls storage changes back if it fails partway.

A shared folder indexed in place is different. PrintStash does not own those bytes, so your NAS backup or snapshot policy must cover them. If you want the Docker layer underneath all this, backing up the named volumes covers which volume holds the database, the owned files, and the generated secrets key.

Restoring without SSH

Open Settings -> Storage to list, create, download, and restore backups. Superusers can perform the same jobs through the API.

Restore has a strong confirmation because it replaces the current database and PrintStash-owned files. It is a rollback, not a merge. Stop slicer hooks and other upload automation before starting one.

Download matters too. A backup stored only on the same host does not cover a failed disk, a lost machine, or a broken volume. Keep another copy on a different system or provider.

The manifest trick

Each archive has a small manifest describing its ID, timestamp, version, and contents. The backup list reads that metadata.

The first S3 implementation put the manifest at the end of the archive. Listing backups then required streaming each complete object just to reach a few bytes of metadata. Version 0.6.3 moved the manifest to the first archive entry. PrintStash can now read the header and stop, so the list stays quick even when the bucket contains large backups.

A sensible routine

1. Create a backup before every upgrade or risky storage change.
2. Mirror it off the PrintStash host.
3. Download an archive occasionally and keep it somewhere independent.
4. Restore one into a scratch stack.
5. Check a known model, its files, tags, and history.

That last step is the test. Until then, you have an archive, not a proven recovery procedure. For bucket configuration and scheduling, use the S3 backup guide, and the backup and restore guide has the endpoint-level detail.

Questions that come up

How do I back up a self-hosted 3D printing library?

Capture the database, the files the application owns, and the configuration and secrets that decrypt them, all from the same moment. In practice that means using the application’s own backup rather than copying its files, because only the app can take a database snapshot consistent with the blobs it references. In PrintStash that is a superuser action under Settings, Storage, or the equivalent API call, and each archive holds the database, owned model and G-code files, documents, thumbnails, and a manifest. Then get a copy off the host, because a backup living on the same disk as the data protects you from mistakes and not from hardware. There is no built-in scheduler, so a cron job or systemd timer is what makes it happen on a schedule.

How do I restore a PrintStash backup?

From Settings, Storage: list the backups, pick one, and confirm through a deliberately heavy confirmation step, which is the one piece of friction here that earns its place, or drive the same job through the API as a superuser. Restore replaces the current database and PrintStash-owned files, so it is a rollback rather than a merge, and anything added since that archive was made is gone. Stop slicer hooks and other upload automation first. The restore path validates and stages what it is about to write, pauses concurrent writers, and rolls storage changes back if it fails partway, so a failed restore should leave you where you started rather than halfway.

Does a backup include my NAS folder of models?

No, and that is on purpose. A folder added as a shared volume is indexed in place: PrintStash reads those bytes where they live, never owns them, and never deletes them when you remove a model or the volume. The archive covers the library’s own data, which includes the metadata, revisions, outcomes, and print history for those models, while the meshes themselves stay the NAS’s responsibility. Plan both halves, and remember that restoring the archive without the NAS gives you a library that knows everything about files it can no longer read.

Can I back up to S3, R2, or MinIO?

Yes. Every backup is written to the local backup directory first, and PrintStash mirrors it to an S3-compatible bucket when one is configured, which covers Cloudflare R2, MinIO, and anything else speaking the same API. The bundled S3-compatible service in the default stack is SeaweedFS. Listing remote backups stays fast because each archive puts its manifest in the first entry, so the list reads a header instead of streaming whole objects. The S3 backup guide covers the credentials and the scheduling call.

How do I test that my backup actually restores?

Restore it into a scratch stack rather than over your live one: bring up a second PrintStash with empty volumes, restore the archive there, and then check a model you know well, including its files, tags, revisions, and print history. That last part is the test people skip, and it is the one that catches an archive that restores cleanly while missing something you cared about. Doing it once after setup and again after any storage change is enough for most installations.