Moving from Immich

An existing Immich server can switch to Frameleaf and keep its database, media, users and settings. You change the server image, start it, and Frameleaf takes over the library on its first start.

Before you start

Your Immich server must be on v3.1.0. Frameleaf only takes over a library from exactly that official release. If you’re on an older release, upgrade with the official server to v3.1.0 first, then switch.
Stop the official server. Frameleaf won’t take over the library while another server or client is still connected to the database.
Check you have disk space for a full copy of the database in your backups folder.

What stays the same

Compose service names. Frameleaf keeps the same service names, such as immich-server and database, so your existing docker-compose.yml layout, database and storage paths carry over. Only the displayed container names change, to frameleaf_*.
Your .env file. Every old IMMICH_ variable still works as an alias for its new FRAMELEAF_ name, including IMMICH_VERSION. If you set both names of a pair to different values, the server refuses to start and names the pair. At startup, one warning lists the old names you’re using and their new names.
The database name. DB_DATABASE_NAME still defaults to immich.
Command names. immich-admin and immich-healthcheck in the server image, and the immich command line tool, still work as aliases of frameleaf-admin, frameleaf-healthcheck and frameleaf.

The old names keep working for the whole of the current major version, and stop working in the next major release. No date is set for that release.

Switch the server

Back up your database and media.
Optional: on the official server, create a fresh database dump (Job Queues, then Create job, then Create Database Dump). If Frameleaf finds a complete backup less than 24 hours old, it uses that instead of making its own copy, so the first start is quicker.
Stop every official server container.
Change the server image to the Frameleaf image from your Frameleaf release, keeping your .env file and storage paths.
Start the stack.

The first start

The safety copy

Before it changes anything, Frameleaf makes a full copy of the database. While it works, every page shows a Getting Ready… screen explaining what’s happening, and the apps and API get a “service unavailable” answer asking them to try again. When the copy is saved, Frameleaf starts normally and the screen moves on to sign-in by itself.

Where it goes. In your backups folder, UPLOAD_LOCATION/backups, next to the official server’s own backups. It’s named like immich-db-backup-<date>T<time>-pre-upgrade-v<version>-pg<version>.sql.gz and marked Before upgrade in the backups list. Both Frameleaf and the official server can list it, and you can restore it from Administration, then Maintenance like any other backup.
How long it’s kept. It doesn’t count toward your backup retention limit, on Frameleaf or on the official server, and it’s never removed automatically. Delete it yourself once you no longer need it.
When it’s skipped. If the newest database backup in that folder is complete and less than 24 hours old, Frameleaf uses it instead, and the screen names it for a few seconds.
If it fails. Frameleaf checks for room first. If there isn’t enough, or the copy fails, nothing is upgraded: the screen says what went wrong, the database stays exactly as the official server left it, and the next start tries again. Free up space or fix what the log reports, then restart the container.

The copy covers the database only, which is why you back up your media yourself.

Taking over the library

Straight after the safety copy, before the API accepts requests or any background job runs, Frameleaf adds its own part of the database and takes over the library in a single step. If anything fails, nothing is applied and it tries again at the next start.

If another server or client is still connected to the database, for example an official server container that’s still running, Frameleaf doesn’t take over. It logs a warning naming the connected clients and starts without Frameleaf features such as people groups, media operations, Studio projects, Takeout imports and preservation packages. Until it succeeds, the official server can still start on the library with no handoff. Stop the other server and restart Frameleaf; it tries again at every start.

After the takeover, a compatibility process runs in the background. You don’t need to do anything, and restarting the server while it runs is safe. To see where it is, run:

docker compose exec immich-server frameleaf-admin fork-schema status

What changes in your library

Taking over updates some existing data so Frameleaf’s features work properly:

Locked folder. Everything in the official Locked folder moves into Frameleaf’s Locked feature. Nothing that was private becomes visible, and nothing disappears. Stacks and Live Photos lock as a whole: if one photo in a stack is locked, the rest of the stack is too, and so is the movie half of a locked Live Photo.
Album covers and face thumbnails. An album whose cover is a locked photo gets its newest unlocked photo as its cover, or no cover. A person whose featured face is on a locked photo gets another face, or none, and the thumbnail is made again.
Albums without an owner are deleted, and from now on an album is deleted when its last owner leaves.
Memories no longer link to other people’s photos.
People. Each person becomes part of a person group that keeps the same ID, ready for Frameleaf’s people features.
Removed faces. Faces you removed in the official app are kept as your own “remove” decisions in Frameleaf’s face history.
Shared-link passwords are stored securely as hashes. Every link keeps working in Frameleaf with the same password. If you ever go back to the official server, password-protected links stay locked there until you set their passwords again.
Text recognition results are sent to the mobile apps again on their next sync.

Moving to the Frameleaf app

The Frameleaf phone app and the Immich phone app are separate apps. You can install both on the same phone, and both can connect to the same server at once.

What carries over

Everything stored on the server is shared, because both apps sign in to the same account:

photos, videos, albums, people, memories, favourites and the trash
sharing, partners and shared links
account settings stored on the server, such as Locked rules

What doesn’t carry over

The Frameleaf app starts fresh on your phone:

Sign-in. Sign in again. It’s a new session, listed separately under signed-in devices in your account settings, and signing out of one app never signs you out of the other.
Access tokens and API keys. Nothing is copied from the Immich app. Revoking one app’s session doesn’t affect the other.
Phone permissions. Grant photo library, notification and background access again.
App settings. Choose your backup albums again, and set Wi-Fi and battery rules. Thumbnails and other caches are per app.
Locked PIN entry. Your PIN is the same, but unlocking in one app doesn’t unlock the other.

See iPhone and iPad and Android to set the app up.

Running both apps for a while

The server still accepts the Immich app, its sign-in and its API, so nobody has to switch on a set date. If both apps back up the same phone, turn backup off in one of them. The server won’t store a file twice for the same account, but two backups still waste battery and data.

If you sign in with OAuth, each app has its own callback address, so neither app opens for the other’s sign-in:

App	Without the mobile redirect override	With the override
Frameleaf	`frameleaf-auth:///oauth-callback`	`https://<server>/api/oauth/frameleaf-mobile-redirect`
Immich	`app.immich:///oauth-callback`	`https://<server>/api/oauth/mobile-redirect`

Allow both with your identity provider. Settings, then Access & security, then Sign-in methods shows the exact addresses for your server under Mobile app callbacks, and warns you if the configured override can’t be used by the Frameleaf app.