Backup and restore
Library care, verified repairs and backups Watch on YouTube
Library care, verified repairs and backups
Frameleaf Manager: backups, updates and recovery in one place
The Overview and Library analytics: your server at a glance
Back up Frameleaf: database snapshots, your photo files and restoring
Restore Frameleaf from a backup, and use maintenance mode
Move a Frameleaf library to a new server: resumable and checksum-verified
A good backup means you never lose a photo or the work you’ve put into your library. A Frameleaf backup has two parts: the database and your files, and you need both. The database records where every file is and everything you’ve added (albums, people, descriptions, edits and settings), and Frameleaf doesn’t rebuild it by scanning your folders.
A 3-2-1 strategy is a good rule: three copies of your data, on two kinds of storage, with one copy off-site.
Back up with Manager
Section titled “Back up with Manager”In the native Synology app, open Database backups → Create backup, then Export recovery key. Use Settings → Export protected configuration for the protected configuration export. To recover, unlock the repository and choose Review restore beside a checkpoint. Follow the Synology backup steps for the DSM interface; the standalone Manager controls below use different labels.
In Manager, open Backups and choose Make one now. Manager saves the database and recovery configuration as an encrypted recovery point. It also makes one before every update, restore, import and database move. Since Manager installs updates automatically, a new recovery point usually arrives with each new version, but there’s no schedule of its own, so make one after big changes to your library. Frameleaf’s own automatic database backups run every night as well. Photos, videos and external libraries need their own backup. If Backups says they’re On the same drive as your photos, copy the backups folder to another drive now and then.
Then choose Export key beside Recovery key on the same page, and in Manager settings choose Export beside Configuration export. In the Export recovery key and Export configuration dialogs, enter your Current Manager password and select Download. Store both somewhere private, away from the server. They hold your recovery secrets. Keep the Manager state folder and your media backups too.
Make a recovery point with Make one now, or choose Restore… beside one. These backups cover the database; your media still needs its own backup. Select the image to enlarge it.
Restore a Manager backup
Section titled “Restore a Manager backup”On a running installation, open Backups and choose Restore… beside a recovery point. The existing recovery key unlocks your backups, so you don’t enter it again.
- On Restore your database, select Choose a recovery point.
- Check the selected recovery point, choose the PostgreSQL appdata location, then choose Review restore.
- On Review your database restore, check the release, new database location and preserved media mappings. Tick I understand this restores database records and stops the current installation. Media is not restored., then select Restore database.
- Complete the photo application setup and review the library verification results.
To restore onto an empty Manager installation, such as a replacement server:
- Make the original library paths available to Manager.
- Under Restore a backup, choose Choose a backup.
- Enter your Recovery key and select Unlock backups.
- Select a recovery point and continue from step 2 above.
Manager creates a new database directory and keeps earlier ones, so you can always go back. A recovery checkpoint from another photo application restores through import, not as an ordinary Frameleaf database. Restore any missing media from your media backup to complete the library.
Interrupted Manager operations
Section titled “Interrupted Manager operations”Manager records every step, so an interrupted operation can resume safely. Keep the Manager state folder, recovery key, media mappings and previous database directories. After a restart or a Manager replacement, check the operation’s recorded step, then choose Resume safely. If a database restore was interrupted part-way, the retry uses another empty directory and leaves the earlier target as it was.
You can cancel a failed database backup without stopping Frameleaf. If an update failed before applying its release, cancelling restarts the previous release. Once an update has started changing the database or media, Resume safely moves forward on the new release; switching only the container image back is not a safe rollback. For the same reason, a restore can’t be cancelled once replacement workers have started changing media.
Automatic database backups
Section titled “Automatic database backups”Frameleaf backs up its database automatically to UPLOAD_LOCATION/backups. The app calls these backups snapshots. By default it takes one daily at 2:00 AM and keeps the last 14. In Settings, open Backup:
- Schedule sets when backups run. It’s one schedule for every kind of backup, which run one after another.
- On this server, opened from the Overview, has the Snapshots settings: Take a snapshot with every backup turns automatic snapshots on or off, and Keep the last sets how many to keep.
| Setting | Default |
|---|---|
| Take a snapshot with every backup | On |
| Schedule | Every day at 2:00 AM |
| Keep the last | 14 snapshots |
Database backups contain metadata only, never photos or videos, so pair them with a copy of your files.
Make a backup now
Section titled “Make a backup now”Any of these creates a backup straight away:
- In Settings, then Backup, open On this server and choose Take a snapshot now.
- In Settings, then Computers & background work, then Background work, switch to Advanced, choose Create a job, then Back up the database, then Review job.
The backup appears in UPLOAD_LOCATION/backups and counts toward your retention limit. From the Saved snapshots list on the same page you can also download or delete a backup.
Which files to back up
Section titled “Which files to back up”Back up the complete UPLOAD_LOCATION tree. These folders hold your originals and are critical:
UPLOAD_LOCATION/libraryUPLOAD_LOCATION/uploadUPLOAD_LOCATION/profileUPLOAD_LOCATION/locked-keys, which holds each person’s Locked encryption key file. Without it, nobody can open encrypted Locked files, even with a recovery key. Encrypted files are backed up as they are; your backup tool never needs to decrypt them.UPLOAD_LOCATION/frameleaf/identity, which holds the server’s identity key. If it’s lost, the server gets a new identity, and its Frameleaf account link and licence have to be set up again. It also holds the secret that Locked PINs depend on: without it, people who use Locked encryption with a PIN need their recovery key.
Also back up UPLOAD_LOCATION/thumbs. Thumbnails can be regenerated, but this folder also holds your edited versions and the edit masks and Clean Up fills the Frameleaf apps upload (files named *_develop_artifact_*.png), and those can’t be regenerated.
encoded-video holds re-encoded copies of videos and can be rebuilt, so you can leave it out of your backup and rerun the video transcoding job after a restore. You can also leave out logs (the server’s own logs), exports (downloads people asked for, which expire) and imports (the folder you copy exports into before importing them).
Where everything is stored
Section titled “Where everything is stored”Each person has a folder named after their user ID inside most of these locations. You can find your user ID in Account settings, then Account.
| What | Where | Can it be rebuilt? |
|---|---|---|
| Originals uploaded from the web, apps or CLI (storage template off, the default) | UPLOAD_LOCATION/upload/<userID> |
No |
| Originals, when the storage template is on | UPLOAD_LOCATION/library/<userID> |
No |
| Profile pictures | UPLOAD_LOCATION/profile/<userID> |
No |
| Thumbnails, previews and face thumbnails | UPLOAD_LOCATION/thumbs/<userID> |
Yes |
| Edited versions and develop artifacts | UPLOAD_LOCATION/thumbs/<userID> |
No |
| Re-encoded videos (the original is kept) | UPLOAD_LOCATION/encoded-video/<userID> |
Yes |
| Video seek-bar previews and Studio timeline filmstrips | UPLOAD_LOCATION/thumbs/<userID>/<xx>/<yy>/.<assetID>-timeline |
Yes |
| Automatic database backups | UPLOAD_LOCATION/backups |
Only from the live database |
| Locked encryption key files | UPLOAD_LOCATION/locked-keys |
No |
| The server’s identity key | UPLOAD_LOCATION/frameleaf/identity |
No |
| Server logs | UPLOAD_LOCATION/logs |
Not needed |
| The database itself | DB_DATA_LOCATION |
No, back it up as a dump |
When the storage template is on, Frameleaf moves originals into library/, using the person’s storage label instead of the user ID if an administrator set one (the first administrator’s label is admin). Files from the mobile apps land in upload/<userID> first and move to library/ once the upload finishes. If you turn the storage template off again, existing files stay in library/ and new uploads go to upload/.
Keep the database and files in step
Section titled “Keep the database and files in step”For a perfectly matched backup, stop the application writers first so nothing changes while it runs.
If you need to keep the server running, back up the database first and the files second, and keep file history so a photo deleted mid-backup still has a copy. Then test a restore, including edited items and files that changed during the backup.
Restore a database backup
Section titled “Restore a database backup”On an existing server
Section titled “On an existing server”- In Settings, open Backup, then On this server. You can also go to the Restore tab and choose Only albums, people and edits.
- Find the backup under Saved snapshots. Each backup shows its version, creation date and size.
- Click Restore next to the backup you want.
- Read the summary, type
RESTOREto confirm, and choose Restore backup. You can choose Create a safety backup of the current database first to keep a copy of what you have now.
Restoring replaces the current database. Metadata, albums, people, edits and settings return to the state in the backup, and changes made since are lost unless you create the safety backup first. Original files on disk aren’t touched.
The restore runs in four steps: Frameleaf enters maintenance mode, restores the database, runs any migrations and verifies the library. When it finishes, the server opens again on its own, and anyone who signed in after the backup was made needs to sign in again. If the restore fails, the server stays in maintenance mode so you can read what happened, and you choose End maintenance once you’ve read the details. Keep a separate, verified database and media backup elsewhere too, so you always have a way back.
To restore a backup file from elsewhere, click Select from computer beside Upload database backup file in the same list and choose a .sql.gz file. It appears in the list with an uploaded- prefix.
On a fresh installation
Section titled “On a fresh installation”- Set up
.envanddocker-compose.ymlas in Manual Docker Compose installation. - Move the old server’s
backups,encoded-video,library,profile,thumbsanduploadfolders into the newUPLOAD_LOCATION, along withlocked-keysandframeleafif they exist. - If you used external libraries, mount them the same way in the new Compose file, moving files to match if needed.
- Run
docker compose up -d. - Open the server from your home network. On setup’s welcome page, choose Restore from a backup. Frameleaf enters maintenance mode and opens Restore your library.
- Check the folder report. It shows whether the server can reach each photo folder, and how many files it holds.
- Click Next, choose a backup from the list or upload a
.sql.gzfile, and click Restore.
For example, if the old server had UPLOAD_LOCATION=/my-broken-instance/media and the new one has UPLOAD_LOCATION=/a-brand-new-instance/data, move:
/my-broken-instance/media/backups -> /a-brand-new-instance/data/backups/my-broken-instance/media/encoded-video -> /a-brand-new-instance/data/encoded-video/my-broken-instance/media/library -> /a-brand-new-instance/data/library/my-broken-instance/media/profile -> /a-brand-new-instance/data/profile/my-broken-instance/media/thumbs -> /a-brand-new-instance/data/thumbs/my-broken-instance/media/upload -> /a-brand-new-instance/data/uploadVersion compatibility
Section titled “Version compatibility”The backup list marks each backup as matching your current version, made with a different version, or of unknown version.
- Older backup: the restore brings it up to date with the database migrations.
- Newer backup: made by a newer server than the one you’re running. Update the server before restoring it.
- Unknown version: if its migrations fail, the server rolls back to the current database.
For the smoothest restore, use a backup that matches your current version.
Recovery readiness
Section titled “Recovery readiness”A finished backup is only half the job: you also want proof that it restores. Frameleaf proves an off-site backup for you with restore drills, and the Recovery readiness panel at the bottom of the Restore tab keeps a record of the tests you run yourself. It shows when you last proved a restore of the Database and of your Original files, and when the Next test is due. A new test is due every 90 days.
Restore drills
Section titled “Restore drills”With Cloud backup on, Frameleaf proves the backup restores by itself. A restore drill takes a random sample of up to 500 photos and videos back from your backup into a scratch copy, unlocks it with your recovery key, rebuilds the library data and compares the sample with your originals. It changes nothing in your library, and usually takes a few minutes.
The Restore drill card is on the Restore tab of Settings, then Backup:
- Your backup restored correctly shows when the last drill passed and how many sample photos and videos matched. See the report opens the full report, which you can Print or save with Download report. The downloaded file is signed, so anyone you send it to can check that it came from your server and wasn’t changed.
- Your backup hasn’t been proven to restore yet means no drill has run. Choose Run a drill now, or wait: a drill runs every 30 days, after the night’s backup.
- Your backup didn’t restore names the step that failed: fetching the sample, unlocking it with the recovery key, rebuilding the library data or comparing the photos. Your backups keep running, but until it’s fixed Frameleaf can’t prove they would restore. If the recovery key didn’t unlock the backup, choose Check the recovery key. A failed drill is tried again the next day.
Record your own restore test
Section titled “Record your own restore test”After you’ve rehearsed a restore into an isolated destination, such as the command-line rehearsal below, choose Record a restore test. Tick what restored correctly, the database, the original files with verified checksums, or both, and choose Record restore test. This records your statement; Frameleaf doesn’t run the test for you.
Restore from the command line
Section titled “Restore from the command line”For scripted recovery you can back up and restore with pg_dump, gunzip and psql. Run these from your Compose folder, next to its .env file. The database service name works whatever the container is called. Replace <DB_USERNAME> and <DB_DATABASE_NAME> with the values in your .env (the new-installation defaults are postgres and frameleaf).
Back up:
set -o pipefaildocker compose exec -T database pg_dump --clean --if-exists \ --dbname=<DB_DATABASE_NAME> --username=<DB_USERNAME> \ | gzip > "/path/to/backup/dump.sql.gz"To rehearse a restore and prove your backup works, use a separate recovery host, the matching release’s Compose file and a new .env. Choose a fresh, empty DB_DATA_LOCATION and separate media paths, and keep the live installation’s database and media directories out of the rehearsal’s mounts. Start only PostgreSQL, wait for its healthcheck, then load the archive:
set -o pipefaildocker compose up -d database# Continue only after the database healthcheck reports healthy.gzip -dc "/path/to/backup/dump.sql.gz" \ | docker compose exec -T database psql --dbname=<DB_DATABASE_NAME> --username=<DB_USERNAME> --single-transaction --set ON_ERROR_STOP=onThis checks the archive in an isolated database. Keep application and upload writers stopped during the rehearsal. For a real restore, use Frameleaf’s recovery interface, which validates the backup and cleans up recovery state before writers resume.
On Windows, mount an uncompressed .sql file into the rehearsal’s database service, open a shell with docker compose exec database bash, and load it with psql using the same database, user and failure-handling options.
If the destination has already run Frameleaf, keep it and choose another empty database directory. After a real restore, review jobs marked Needs attention and retry them: work with external effects, such as emails, isn’t replayed automatically. Once migrations, original files, a few representative users, Locked access and sharing all check out, you can retire your previous recovery point.
A template backup script with Borg
Section titled “A template backup script with Borg”Borg is a deduplicating backup tool with built-in versioning. This script dumps the database into your upload folder, then backs up the folder, database dump included, to a second drive and to a remote computer. Files can still change while the script runs, so stop application writers for a perfectly matched recovery point, or keep file history and test a restore. Run it as often as suits how much new data you’re willing to redo.
It assumes a second drive on the server for the on-site copy and SSH access to a remote computer for the off-site copy. Remove the remote lines if you don’t need them.
Before you start:
- Install Borg on the server and on the remote computer.
- To run the script as a non-root user, add that user to the
dockergroup. - To run it unattended, set up passwordless SSH from the server to the remote computer, from the account that will run the script.
Set up the Borg repositories once:
UPLOAD_LOCATION="/path/to/frameleaf/directory" # as set in your .env fileBACKUP_PATH="/path/to/local/backup/directory"
mkdir "$UPLOAD_LOCATION/database-backup"borg init --encryption=none "$BACKUP_PATH/frameleaf-borg"
# Remote set-upREMOTE_HOST="remote_host@IP"REMOTE_BACKUP_PATH="/path/to/remote/backup/directory"
borg init --encryption=none "$REMOTE_HOST:$REMOTE_BACKUP_PATH/frameleaf-borg"Edit this script and add it to your crontab. It assumes your paths contain no :, @ or " characters.
#!/bin/sh
# PathsUPLOAD_LOCATION="/path/to/frameleaf/directory"BACKUP_PATH="/path/to/local/backup/directory"REMOTE_HOST="remote_host@IP"REMOTE_BACKUP_PATH="/path/to/remote/backup/directory"
### Local
# Back up the Frameleaf databasedocker exec -t frameleaf_postgres pg_dump --clean --if-exists --dbname <DB_DATABASE_NAME> --username=<DB_USERNAME> > "$UPLOAD_LOCATION"/database-backup/frameleaf-database.sql# Compressing makes deduplication less effective. If you use another tool or prefer to compress anyway:# docker exec -t frameleaf_postgres pg_dump --clean --if-exists --dbname <DB_DATABASE_NAME> --username=<DB_USERNAME> | /usr/bin/gzip --rsyncable > "$UPLOAD_LOCATION"/database-backup/frameleaf-database.sql.gz
# Append to the local Borg repositoryborg create "$BACKUP_PATH/frameleaf-borg::{now}" "$UPLOAD_LOCATION" --exclude "$UPLOAD_LOCATION"/encoded-video/borg prune --keep-weekly=4 --keep-monthly=3 "$BACKUP_PATH"/frameleaf-borgborg compact "$BACKUP_PATH"/frameleaf-borg
### Remote
borg create "$REMOTE_HOST:$REMOTE_BACKUP_PATH/frameleaf-borg::{now}" "$UPLOAD_LOCATION" --exclude "$UPLOAD_LOCATION"/encoded-video/borg prune --keep-weekly=4 --keep-monthly=3 "$REMOTE_HOST:$REMOTE_BACKUP_PATH"/frameleaf-borgborg compact "$REMOTE_HOST:$REMOTE_BACKUP_PATH"/frameleaf-borgThe script skips encoded-video, which can be rebuilt. It keeps thumbs, because that folder also holds edited versions and develop artifacts that can’t be regenerated.
To restore, mount a repository and copy back what you need:
BACKUP_PATH="/path/to/local/backup/directory"mkdir /tmp/frameleaf-mountpointborg mount "$BACKUP_PATH"/frameleaf-borg /tmp/frameleaf-mountpointcd /tmp/frameleaf-mountpointFor the remote copy, mount "$REMOTE_HOST:$REMOTE_BACKUP_PATH"/frameleaf-borg instead. Each snapshot is a separate folder. When you’re done, run borg umount /tmp/frameleaf-mountpoint.
Cloud backup and Buddy backup
Section titled “Cloud backup and Buddy backup”Cloud backup and Buddy backup keep an encrypted off-site copy of your originals, edits, settings and a verified database dump, with nothing to manage, and you can run both together. If the server itself is lost, bring it back from a cloud backup bucket without the web app using frameleaf-admin cloud-backup restore. See Server commands. Both servers need a Server licence to start a new Buddy Backup pairing. A Frameleaf Cloud plan is needed only when the servers can’t connect directly and use the relay. Buddy backup has its own recovery instructions on the Buddy backup page. For Cloud Backup, see Export and recover without Cloud access. Keep your deployment configuration and connector encryption keys with the matching media and database: encrypted connections need them, not just the database dump.
Both copy Locked encryption files as they are, still encrypted, together with each person’s key file. A run that finds encrypted files whose current key file it didn’t capture, for example because someone turned encryption on or off while it ran, stops, and the next run includes the key file. Items restored with an older key only produce a warning in the server log; they’re copied as they are and don’t stop the backup.
Cloud backup: plan full
Section titled “Cloud backup: plan full”This applies to Cloud backup plans bought in the iPhone or Android app, which come in fixed sizes. Plans bought on the web add storage automatically instead.
When the backups no longer fit the plan and the owner keeps it, the backup storage becomes read-only and Backup paused: plan full shows on the server and in the Frameleaf app. Your library is untouched and restores keep working. New items wait until the plan is upgraded or the backup gets smaller, then backups carry on by themselves.
If the server is linked and push notifications are set up:
- Your plan has outgrown its tier goes only to the server’s owner, because it shows plan and usage details. The owner is the administrator who signs in with the Frameleaf account the server is linked to.
- Backup paused: plan full goes to every administrator, without plan details, each time the plan fills up. A Family Sharing member is asked to contact their family organiser.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.

