Upgrading
Upgrade Frameleaf with Docker Compose Watch on YouTube
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 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, don’t go back to a Frameleaf version from before it: older versions can’t read encrypted files.
With the Synology app
Section titled “With the Synology app”The Synology package and your photo library update separately:
- 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.
- Open the app from the DSM main menu. In Updates, choose Review update beside an eligible photo-library release.
- Review the release, database checkpoint, storage and service changes, then confirm the update.
- 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 for removing the package and what data it keeps.
With Frameleaf Manager
Section titled “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:
- 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.
- 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.
- On Ready to install, select Install with the version number, then Update Frameleaf in the confirmation dialog.
- 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
Section titled “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.
If an update goes wrong
Section titled “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.
With Docker Compose
Section titled “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 instead of the steps below.
- Make sure your database and media backups are usable.
- Use
FRAMELEAF_VERSION=latest, as the release’sexample.envdoes, for the current release, or an exact release tag such asframeleaf-v<version>when you want a fixed version. See Version tags. - If the new bundle renames the application service to
frameleaf-server, rundocker compose downwith your current Compose file, before you replace it. Leave off--volumesand-vso your database, media and named volumes stay. Keep the project name, and update custom overrides, proxy targets and scripts to useframeleaf-server. - If your stack was first created by an early Frameleaf release and its containers and volumes belong to a Compose project called
immich, addCOMPOSE_PROJECT_NAME=immichto.envso Compose keeps using them. Without it,docker compose upstops with a container-name conflict and changes nothing. - Move any machine learning settings from
.envinto.env.ml. The machine learning container no longer receives.env. - Replace the Compose files with the matching release files, then run these from the existing Compose folder:
docker compose config --imagesdocker compose pulldocker compose up -d --remove-orphansdocker compose psdocker logs frameleaf_serverUpdate 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.
First start after an update
Section titled “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
Section titled “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, 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
Section titled “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.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.


