Preservation packages

A preservation package is an independent copy of your original files together with what your library knows about them. Every file in it is checksummed when it’s written and can be checked again at any time, so you can prove years later that the copy is intact. A package can be restored into your library, on this server or another one.

Find it in Settings, then Import & protection, then Originals & preservation.

Not a server backup

A package doesn’t include accounts, sharing, shared spaces, server settings, pets, memories or Studio projects (Studio projects travel as project bundles). Keep your server backups and a separate copy of your originals as well.

What’s in a package

• your original files
• dates, places, your descriptions, ratings, favourites and archive
• Locked records, with the reason each item was locked
• albums and collections, tags, and named people
• edit recipes, so edited versions can be made again
• Live Photo and stack links
• document corrections and moment notes

Only your own items are ever included, never a partner’s or a shared album’s.

Make a package

1. Choose Preview preservation manifest.
2. Include. Choose what to preserve: the whole library, your favourites, a range of dates the photos were taken, or chosen albums.
   • Include metadata and edit recipes adds the metadata files, albums, people, tags and edit recipes.
   • Include checksums and a manifest is always on.
   • Include Locked items is only available while your session is unlocked.
3. Verify. The server counts and measures your selection and checks that it fits in one package, up to 100,000 items, and in the free space where packages are written. Nothing is written yet.
4. Manifest. See what the package will hold and, category by category, what a restore brings back.
5. Choose Start export.

The export runs in the background and is listed in Activity and in the package list. Closing the page doesn’t stop it. You can pause, resume or cancel it, and a paused export carries on from the next item.

Each original is copied into the package and checked against the checksum your library recorded for it. Nothing is moved or linked, and your library’s files are never changed.

An item that fails is tried once more automatically. Anything still failing is listed in the item report, where Retry failed items tries again. A package whose items didn’t all copy is marked Incomplete.

If an item becomes Locked after you started an export without Locked items, it’s skipped.

Verify a package

Verify files reads the package back: the manifest first, then every original and metadata file against its SHA-256 checksum. Each file is reported as matching, missing or changed, and any file the manifest doesn’t account for is listed too. A package this server wrote is also compared with the record the server kept when writing it, so a rewritten manifest is reported as changed rather than believed.

A package is Not verified until a verification passes. A finished download isn’t proof on its own: verify the copy you keep elsewhere too, by uploading it, or, if you’re an administrator, by pointing the server at it.

Download a package

• Download package saves the whole package as one ZIP file, named like name.frameleaf-preservation.zip.
• Download manifest saves just its manifest.

A package that holds Locked items can only be downloaded while your session is unlocked. While you’re locked, Locked items are left out of the item report, the restore review and every count.

Restore from a package

Choose Restore from a package, or Restore… on a package in the list. A restore has four steps.

1. Package. Pick a package this server wrote, upload a package ZIP (kept for three days), or, if you’re an administrator, name a package folder or ZIP on the server outside its media storage. Choose whether to restore edit recipes, and what should happen where the package and your library disagree.
2. Check. Every file is verified against the manifest and each original is compared with your library. Nothing is written.
3. Review. Each original is shown as new to your library, already in your library or in your trash. For originals you already have, the details that differ (date taken, description, location, rating, archive, edit recipe) are listed side by side. Choose Keep library or Use package for each, or leave the default.
4. Restore. The originals your library doesn’t have are added, and the ones it has are matched.

Download reconciliation report saves a list of every item in the restore and what happened to it.

What a restore never does

• Replace or duplicate an original. Originals are matched by checksum. One already in your library is never replaced or copied twice. One in your trash isn’t added again: restore it from the trash first, then run the restore again.
• Remove anything. A favourite or Locked record in the package is added, but a restore never clears a favourite or unlocks anything. Locked items come back Locked, with the reason they were locked.
• Undo your later changes. Your choices apply to items not yet restored. A restore that’s paused, cancelled or interrupted carries on from the items it hadn’t finished, and never touches an item it already restored.
• Create things twice. Albums, collections and people in the package are found again on a repeated restore: the original album if it’s still yours, one an earlier restore created, or your only album with the same name in the same place. New ones are only created when none of those exists.

Collections stay at the top level, and albums sit inside a collection one level deep.

What comes back

Information	After a restore
Original files, dates, places, your descriptions, ratings, favourites, archive, Locked records, albums and collections, tags, named people and their faces, edit recipes, Live Photos, stacks	Restored
Document corrections, moment notes and transcripts	Restored where your library has none of its own
Generated descriptions and moment captions, model and enrichment details, camera details	Kept as a record of where they came from only
Sharing and shared spaces, pets, memories, Studio projects	Not included

Generated text is never restored as yours. A description a model generated is kept with the restored item as a record, not written as your own description. Camera details come back from the original file itself when it’s read.

Edited versions are made again from their recipes once the originals have been read. Unnamed faces are detected again, and named people come back on their faces.

The package format

A package is plain files you can inspect:

Path	Contents
manifest.json	Format and version, package ID and name, what was selected, counts, completeness, restore support, and a SHA-256 checksum for every index file
assets.jsonl	One line per original: its paths, size, SHA-1 and SHA-256 checksums, and the checksum of its metadata file
albums.json, people.json, tags.json	The albums and collections, named people and tags the originals belong to
originals/<id>.<ext>	The original files
metadata/<id>.json	One metadata file per original

Note

Checksums detect damage and inconsistent copies. They don’t prove a package wasn’t deliberately rewritten, so only restore packages from a source you trust. Frameleaf refuses symbolic links and split archives in a package, and keeps every entry inside the package.