Going back to Immich

Frameleaf 3.0 and later can hand your library to a matching, certified release of the official Immich server, and later come back to Frameleaf without losing anything Frameleaf stored. Frameleaf keeps its own data in a separate part of the database (the immich_fork schema), which simply sits unused while the official server runs.

This is a careful, planned procedure for administrators. Don’t just change the image tag.

What you lose while the official server runs

The official server doesn’t know about Frameleaf’s features. In particular, photos hidden only by Frameleaf’s privacy filters, such as Locked items and hidden sensitive content, can become visible through the official server’s timelines, search, albums, downloads, sharing and mobile apps. Review that before you hand over.

Which libraries can go back

Your library	What you can do
Opened by a compatibility-certified Frameleaf 3.x release	Hand over to exactly ghcr.io/immich-app/immich-server:v3.1.0 with the procedure below.
First opened by an older, pre-compatibility Frameleaf release	Don’t point the official server at it. Either restore a matched database and media backup taken before Frameleaf first opened it, or stay on Frameleaf until a compatibility release has upgraded and converted it.
Any other official version, or a library without a completed conversion	Restore from your database and media backups instead.

The only certified official image is currently ghcr.io/immich-app/immich-server:v3.1.0. Never use latest, release or any other moving tag. An official image that isn’t certified may reject the database, or leave it in a state neither server can safely run.

What happens to your data

• Workflows and plugins belong to the official server and stay in its own tables. Frameleaf never copies, changes or deletes them. Workflows you created on Frameleaf, and ones created while the official server runs, are all still there after a return.
• Frameleaf-only data, such as people groups, Studio projects, iCloud Photos Sync connections and Locked records, stays in the database, unused, until you return.
• Locked stacks and Live Photos. Because Frameleaf locks stacks and Live Photos as a whole, the official app shows those stack members and Live Photo movies as Locked too.
• Password-protected shared links. Frameleaf stores shared-link passwords as secure hashes, which the official server can’t check. Each password-protected link stays locked on the official server (it never opens without a password) until you set its password again in the official app. Links whose password was set on the official server and not yet used in Frameleaf keep working. After you return, passwords set on the official server keep working in Frameleaf.

Before you start

• Take matching backups. Make an unchangeable checkpoint of the PostgreSQL database and of every media folder, taken together, and note each one’s real ID from your backup system. You’ll type both IDs into the commands. Keep them until you’ve returned to Frameleaf and checked everything works.
• Plan downtime. The server is in maintenance mode for the whole handoff.
• Let the compatibility process finish. It starts by itself on Frameleaf; frameleaf-admin fork-schema status shows where it is. A part whose last batch failed isn’t retried automatically; fix the cause the log names, then run frameleaf-admin fork-schema resume.
• Rehearse if you can. Try the whole sequence on a copy of your server before doing it for real.

The point of no return

The handoff commits in a single step. If something fails before that, nothing changes. If the official server’s own upgrade fails after it, you must restore both the database and media checkpoints. Never try to fix it by editing migrations or ledger rows by hand.

Hand over to the official server

Run these with frameleaf-admin from one-shot admin containers that use the Frameleaf image.

1. Turn on maintenance mode and stop every other API, microservices and worker container:

   frameleaf-admin enable-maintenance-mode

2. Set your checkpoint IDs, and confirm the compatibility process is complete:

   export DATABASE_BACKUP_ID='backup-immutable-id'
   export MEDIA_SNAPSHOT_ID='media-snapshot-immutable-id'
   
   frameleaf-admin fork-schema status
   frameleaf-admin fork-schema verify

3. Verify storage against your checkpoints. If it’s interrupted, run it again with resume instead of start:

   frameleaf-admin fork-schema-cutover verify-storage start \
     --database-backup-id "$DATABASE_BACKUP_ID" \
     --media-snapshot-id "$MEDIA_SNAPSHOT_ID"

4. Run the pre-flight check, then apply the cutover with its report digest:

   REPORT_DIGEST="$(frameleaf-admin fork-schema-cutover preflight \
     --database-backup-id "$DATABASE_BACKUP_ID" \
     --media-snapshot-id "$MEDIA_SNAPSHOT_ID" \
     --format digest)"
   
   frameleaf-admin fork-schema-cutover apply \
     --database-backup-id "$DATABASE_BACKUP_ID" \
     --media-snapshot-id "$MEDIA_SNAPSHOT_ID" \
     --report-digest "$REPORT_DIGEST"

5. Prepare the checkpoint for the official server:

   frameleaf-admin fork-handoff prepare-official

   If you have password-protected shared links, it stops and tells you how many. Once you’ve planned to reset those passwords, run it again with --acknowledge-shared-link-passwords. Save the JSON it prints; it names the exact official image to use.

6. Stop the Frameleaf server. From a one-shot admin container using the same Frameleaf image, run frameleaf-admin disable-maintenance-mode, then immediately start ghcr.io/immich-app/immich-server:v3.1.0 without changing the tag.

7. The official server applies its own pending upgrades on its first start. Then check it works: sign in, run an existing workflow and create a new one, and upload, download and delete a throwaway photo.

Return to Frameleaf

1. Turn maintenance mode back on and stop the official server.

2. From a Frameleaf admin container using a compatible Frameleaf release, reconcile and reactivate Frameleaf’s data:

   frameleaf-admin fork-handoff prepare-fork --batch-size 100

3. Stop that maintenance-only container. From a one-shot admin container using the same image, leave maintenance mode:

   frameleaf-admin disable-maintenance-mode

4. Start Frameleaf normally, with its API and worker containers, and check:

   frameleaf-admin fork-schema status

On return, Frameleaf checks the official server left the database exactly as expected, tidies away Frameleaf records for things deleted in the meantime, sets defaults for anything new, and only then turns its features back on. Frameleaf schema changes from releases that came out while you were handed over are applied at this point too.

The return has worked when maintenance mode is off, the normal API and worker containers are healthy, and your workflows, both old ones and any made on the official server, still run on a new photo.

If any check fails during the return, leave maintenance mode on and restore the database and media checkpoints together.

Note

Frameleaf refuses to start on a library that a newer Frameleaf release has already opened. Downgrades aren’t supported.

Related

• Moving from Immich, for switching an official server to Frameleaf.
• Backup and restore, for making and restoring the checkpoints.
• iCloud Photos Sync server setup, for what happens to iCloud connections.