# Backup and restore

Source: https://frameleaf.app/docs/admin/backup-and-restore/

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.

:::caution
Frameleaf backs up its database for you automatically. Your photo files need a backup tool of your choice, such as the [Borg script](#a-template-backup-script-with-borg) below. For an off-site copy you don't have to manage, see [Cloud backup](https://frameleaf.app/docs/cloud/cloud-backup/) and [Buddy backup](https://frameleaf.app/docs/cloud/buddy-backup/).
:::

## 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](https://frameleaf.app/docs/nas/synology/#protect-your-library) 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](#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.

[![Manager Backups page: Last recovery point Last night, 2:00 AM with Make one now, where they're kept with a same-drive warning, the recovery key, and the list of recovery points with Restore.](https://frameleaf.app/shots/docs/manager-backups-2026-11.jpg)](https://frameleaf.app/shots/docs/manager-backups-2026-11.jpg)

*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

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.

1. On **Restore your database**, select **Choose a recovery point**.
2. Check the selected recovery point, choose the **PostgreSQL appdata location**, then choose **Review restore**.
3. 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**.
4. Complete the photo application setup and review the library verification results.

To restore onto an empty Manager installation, such as a replacement server:

1. Make the original library paths available to Manager.
2. Under **Restore a backup**, choose **Choose a backup**.
3. Enter your **Recovery key** and select **Unlock backups**.
4. 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

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

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

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

Back up the complete `UPLOAD_LOCATION` tree. These folders hold your originals and are critical:

- `UPLOAD_LOCATION/library`
- `UPLOAD_LOCATION/upload`
- `UPLOAD_LOCATION/profile`
- `UPLOAD_LOCATION/locked-keys`, which holds each person's [Locked encryption](https://frameleaf.app/docs/using/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](https://frameleaf.app/docs/using/locked-encryption/#the-servers-pin-secret): 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).

:::caution
If you moved any of these folders onto a different drive, such as `profile/`, point your backup tool at the new location too.
:::

### 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/`.

:::danger
Never change or remove files inside these folders yourself, except to take a backup. View, change and delete photos only through the apps or the web. Editing the folders directly leaves the database pointing at files that aren't there, and shows up as missing or untracked files in the [integrity checks](https://frameleaf.app/docs/admin/system-integrity/).
:::

## 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

### On an existing server

1. In **Settings**, open **Backup**, then **On this server**. You can also go to the **Restore** tab and choose **Only albums, people and edits**.
2. Find the backup under **Saved snapshots**. Each backup shows its version, creation date and size.
3. Click **Restore** next to the backup you want.
4. Read the summary, type `RESTORE` to 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](https://frameleaf.app/docs/admin/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

1. Set up `.env` and `docker-compose.yml` as in [Manual Docker Compose installation](https://frameleaf.app/docs/start/manual-install/).
2. Move the old server's `backups`, `encoded-video`, `library`, `profile`, `thumbs` and `upload` folders into the new `UPLOAD_LOCATION`, along with `locked-keys` and `frameleaf` if they exist.
3. If you used [external libraries](https://frameleaf.app/docs/admin/external-libraries/), mount them the same way in the new Compose file, moving files to match if needed.
4. Run `docker compose up -d`.
5. 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**.
6. Check the folder report. It shows whether the server can reach each photo folder, and how many files it holds.
7. Click **Next**, choose a backup from the list or upload a `.sql.gz` file, 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:

```text
/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/upload
```

:::tip
Before you restore, make sure the folders hold the same files that existed when the backup was made. The folder report helps you spot a folder you forgot to copy.
:::

### 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

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](#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

With [Cloud backup](https://frameleaf.app/docs/cloud/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

After you've rehearsed a restore into an isolated destination, such as the [command-line rehearsal](#restore-from-the-command-line) 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

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:

```bash
set -o pipefail
docker 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:

```bash
set -o pipefail
docker 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=on
```

This 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

[Borg](https://www.borgbackup.org/) 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.

:::note
This adds to Frameleaf's [automatic database backups](#automatic-database-backups) by keeping the dump in a versioned media archive. Keep automatic dumps on until you've tested a restore from this backup.
:::

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 `docker` group.
- 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:

```bash
UPLOAD_LOCATION="/path/to/frameleaf/directory"   # as set in your .env file
BACKUP_PATH="/path/to/local/backup/directory"

mkdir "$UPLOAD_LOCATION/database-backup"
borg init --encryption=none "$BACKUP_PATH/frameleaf-borg"

# Remote set-up
REMOTE_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.

```bash
#!/bin/sh

# Paths
UPLOAD_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 database
docker 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 repository
borg create "$BACKUP_PATH/frameleaf-borg::{now}" "$UPLOAD_LOCATION" --exclude "$UPLOAD_LOCATION"/encoded-video/
borg prune --keep-weekly=4 --keep-monthly=3 "$BACKUP_PATH"/frameleaf-borg
borg 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-borg
borg compact "$REMOTE_HOST:$REMOTE_BACKUP_PATH"/frameleaf-borg
```

The 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:

```bash
BACKUP_PATH="/path/to/local/backup/directory"
mkdir /tmp/frameleaf-mountpoint
borg mount "$BACKUP_PATH"/frameleaf-borg /tmp/frameleaf-mountpoint
cd /tmp/frameleaf-mountpoint
```

For 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

[Cloud backup](https://frameleaf.app/docs/cloud/cloud-backup/) and [Buddy backup](https://frameleaf.app/docs/cloud/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](https://frameleaf.app/docs/admin/server-commands/#restore-from-a-cloud-backup-bucket). 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](https://frameleaf.app/docs/admin/server-commands/#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](https://frameleaf.app/docs/using/locked-encryption/#backups) 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

This applies to [Cloud backup](https://frameleaf.app/docs/cloud/cloud-backup/#when-your-backup-grows) 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.
