# Upgrading

Source: https://frameleaf.app/docs/admin/upgrading/

Each Frameleaf release brings new features and fixes, and upgrading takes a few minutes. Frameleaf Manager installs new versions for you automatically, after saving a recovery point of the database each time. The Synology app checks the release, takes a database checkpoint and walks you through each step.

Before you start, read the [release notes](https://github.com/Frameleaf/frameleaf-app/releases) and back up both your database and your media. A database backup on its own can't undo changes to your media, so you need both.

If anyone on the server uses [Locked encryption](https://frameleaf.app/docs/using/locked-encryption/#dont-go-back-to-an-older-frameleaf-version), don't go back to a Frameleaf version from before it: older versions can't read encrypted files.

## With the Synology app

The Synology package and your photo library update separately:

1. Get the newer **Frameleaf Manager** SPK from Frameleaf, with its checksum. Verify the file, then upload it with **Package Center → Manual Install**. The upgrade keeps your storage folders, HTTPS hostname and ports, so leave those folders in place.
2. Open the app from the DSM main menu. In **Updates**, choose **Review update** beside an eligible photo-library release.
3. Review the release, database checkpoint, storage and service changes, then confirm the update.
4. Check **Activity** for the result. Then open your library and check that sign-in, a few originals, videos and background processing all work.

If an operation is interrupted, use the recovery action recorded in **Activity**. Keep everything in the Synology app: don't create a separate Container Manager project or switch database images on upgraded files. See [Synology](https://frameleaf.app/docs/nas/synology/#update-the-package-and-the-photo-library) for removing the package and what data it keeps.

## With Frameleaf Manager

**Install updates automatically** is on from the start. Manager checks for a new version every few hours and installs one version at a time, each after a recovery point. Photos pause for a few minutes while it restarts Frameleaf. If an automatic check didn't start an update, **Updates** says when and why. A new version that's waiting also shows on Manager's **Overview**.

To choose when updates happen yourself, open **Updates** and turn **Install updates automatically** off. Updates then wait for you there. To install one by hand:

1. Open Manager and choose **Updates**. It shows the version you're on. When a newer one is ready, it says so, such as **1.2.18 is ready**, with what's new and what installing it does. Otherwise it shows **You're on the latest version**; choose **Check now** to look again.
2. Select **Review this update**. Manager checks the version is signed by Frameleaf and made for your server, and that every part of the update is there.
3. On **Ready to install**, select **Install** with the version number, then **Update Frameleaf** in the confirmation dialog.
4. When it finishes, open Frameleaf and check sign-in, albums, several originals and background processing.

Other newer versions are listed under **Other versions you can install**.

Manager downloads compatible images and creates a database checkpoint before it applies the release. If an operation fails, its error tells you why; fix the cause and select **Resume safely**.

### When an update brings a new database engine

Now and then a release comes with a newer build of PostgreSQL that can't open the existing database folder. Manager handles this as part of the update, and the review says so first: **New database engine**, with the old and new versions and how much free space the copy needs.

Manager saves a recovery point, copies the database into a new folder beside the current one, checks that every table arrived, and then starts the new version on the new folder. The old folder is kept exactly as it was. If the copy fails, or the new version doesn't start, Manager puts the previous version back on the old folder with nothing lost.

Make sure the database drive has room for a second copy of the database before you update. Manual installations do this by hand; see [Moving to a new database build](https://frameleaf.app/docs/admin/database/#moving-to-a-new-database-build).

### If an update goes wrong

**Cancel update and restart** is offered while it's still safe to go back to the previous release. Once the new release may have changed the database or media, recovery continues forward, because switching back to an older image isn't a safe rollback. To return to an earlier state, restore a database recovery point from **Backups**; Manager restores it with its matching release. See [Restore a Manager backup](https://frameleaf.app/docs/admin/backup-and-restore/#restore-a-manager-backup).

## With Docker Compose

Keep the same project folder, `.env`, storage paths, external-library mounts and volume names. Download the matching release files and look over their changes before you replace your Compose file. Keep your own changes in a `docker-compose.override.yml` so they survive the replacement.

Check the `database` image in the new file against the one you run now. If it's the same, update normally. If the new file names a different database image, the new database can't open your existing folder: follow [Moving to a new database build](https://frameleaf.app/docs/admin/database/#moving-to-a-new-database-build) instead of the steps below.

1. Make sure your database and media backups are usable.
2. Use `FRAMELEAF_VERSION=latest`, as the release's `example.env` does, for the current release, or an exact release tag such as `frameleaf-v<version>` when you want a fixed version. See [Version tags](#version-tags).
3. If the new bundle renames the application service to `frameleaf-server`, run `docker compose down` **with your current Compose file, before you replace it**. Leave off `--volumes` and `-v` so your database, media and named volumes stay. Keep the project name, and update custom overrides, proxy targets and scripts to use `frameleaf-server`.
4. If your stack was first created by an early Frameleaf release and its containers and volumes belong to a Compose project called `immich`, add `COMPOSE_PROJECT_NAME=immich` to `.env` so Compose keeps using them. Without it, `docker compose up` stops with a container-name conflict and changes nothing.
5. Move any machine learning settings from `.env` into `.env.ml`. The machine learning container no longer receives `.env`.
6. Replace the Compose files with the matching release files, then run these from the existing Compose folder:

```bash
docker compose config --images
docker compose pull
docker compose up -d --remove-orphans
docker compose ps
docker logs frameleaf_server
```

Update any separate machine learning container to the matching release too. The app download page and release notes list which app versions work with the new server.

:::caution
Run only one stack against a PostgreSQL directory, and never use `docker compose down --volumes` during an upgrade.
:::

## First start after an update

On a large library, database migrations and indexes can take a while. Leave the server running while it makes progress without errors. Machine learning downloads any new models the first time they're used.

The server also checks the library after each upgrade against how it was just before: how many photos and videos each person has, and whether the files are still in their folders. The result goes in the server log. **Library check after upgrading … everything is where it was** means nothing changed. If something did, the same line names what and where, so you can look into it before anyone notices a gap.

Then open a few photos, videos and albums, and check the jobs page for failures. That tells you your library has finished processing, which a healthy container alone doesn't.

## Version tags

| Tag | Use |
| --- | --- |
| Exact release tag, such as `frameleaf-v<version>` | Repeatable installs |
| `latest` | Follows stable releases |
| `edge` | Development builds, for testing rather than a library you rely on |

An exact tag is the release's name and tag on [Frameleaf's GitHub releases](https://github.com/Frameleaf/frameleaf-app/releases), starting with `frameleaf-v`. There are no tags without the `frameleaf-v` prefix. The release bundle's `example.env` sets `FRAMELEAF_VERSION=latest`; change it to the exact tag to stay on that release.

Hardware-specific machine learning tags add a suffix such as `-cuda` or `-openvino`, as in `frameleaf-v<version>-cuda`. Keep the suffix when you change the release version.

## Recover after a failed update

Keep the failed installation as it is and read the release's recovery instructions. An older server can't always read a database that a newer release has changed.

With Manager, use the recorded operation's recovery action. To recover by hand, restore the pre-update database and its matching media checkpoint into a separate location with the matching release, check that it works, then point your apps at it. See [Backup and restore](https://frameleaf.app/docs/admin/backup-and-restore/).
