Install with Frameleaf Manager
Install with Manager and bring your Immich library Watch on YouTube
Frameleaf Manager is the easiest way to install Frameleaf. It guides you through choosing storage, installing a verified release, setting up your account and connecting your phone. Afterwards, it gives you start, stop, logs, automatic updates, container settings, drive moves and database recovery in one place, and keeps working even when the photo application is down.
On Synology, download the approved SPK and use Package Center → Manual Install. The Synology guide covers checksum verification, the package wizard, DSM HTTPS and administrator access. Native DSM setup uses your DSM administrator session; the standalone Linux claim-key steps below do not apply to it.
Check Requirements before you begin. If you prefer to manage containers yourself, use Manual Docker Compose installation.
1. Prepare the host
Section titled “1. Prepare the host”Manager’s launcher runs on Linux with Docker, Compose v2, Cosign, findmnt and realpath installed. There are no folders to create first. You give the launcher one parent folder, /srv/frameleaf unless you choose another, and pick the folders for your photos, database and backups in Manager.
Your database goes inside that parent folder, so put it on a disk filesystem outside Docker’s storage directory. Manager refuses network filesystems, RAM disks, loop-mounted disk images and Docker volumes for this location.
On Unraid, install from the template in the Unraid guide instead.
2. Start Manager
Section titled “2. Start Manager”Download launch.sh and cosign.pub from the GitHub latest tag into the same folder. These source files are separate from the release’s downloadable NAS assets:
curl -fL -o launch.sh https://raw.githubusercontent.com/Frameleaf/frameleaf-app/latest/manager/launch.shcurl -fL -o cosign.pub https://raw.githubusercontent.com/Frameleaf/frameleaf-app/latest/cosign.pubReplace the Manager address and LAN address with your own:
sh launch.sh \ ghcr.io/frameleaf/frameleaf-manager:latest \ 'https://server.example:2282' \ /srv/frameleaf \ '<server-lan-ip>'The launcher only accepts ghcr.io/frameleaf/frameleaf-manager:latest. It pulls the image and verifies the signature of the exact image it pulled before starting it. Manager uses port 2282, next to Frameleaf’s 2283.
The second argument is the exact address you’ll open Manager at. Use HTTPS where you can. On a home lab without certificates you can give a plain HTTP address instead, such as 'http://tower.local:2282', and Manager serves HTTP directly. Over HTTP your password and management traffic aren’t encrypted, and you sign in again each time you reload the page.
The third argument is the parent folder. It’s optional, defaults to /srv/frameleaf, and must be an absolute path at least two levels deep. Manager keeps its settings in manager inside it and offers the other folders during setup.
The final argument controls the listening address; omitting it binds Manager to 127.0.0.1. To set it, give the parent folder too.
Open the address you supplied. Manager controls Docker on this host, so keep this administrative address on a trusted network.
Add more drives
Section titled “Add more drives”The parent folder is the only one Manager can use by default. To let Manager use other drives too, for example to put the database or thumbnails on an SSD, list a folder on each drive in MANAGER_EXTRA_FOLDERS, separated by colons:
MANAGER_EXTRA_FOLDERS=/media/ssd/frameleaf:/media/disk2/frameleaf sh launch.sh \ ghcr.io/frameleaf/frameleaf-manager:latest \ 'https://server.example:2282' \ /srv/frameleaf \ '<server-lan-ip>'- Create each folder first. The launcher never creates them, so a drive that isn’t mounted stops the launch instead of filling the wrong disk.
- Each folder must be an absolute path at least two levels deep, such as
/media/ssd/frameleaf, and must not sit inside the parent folder or another extra folder. - It works with this short form only. The long form below names every folder itself.
In setup, Browse then starts with a list of these folders, and you can choose or create folders inside any of them. Manager looks at each drive when it suggests a drive for the database and thumbnails. To add a drive later, remove the Manager container with docker rm --force frameleaf-manager, then run the launcher again with the same arguments and the longer list. Manager’s settings stay in the parent folder, and your photo library keeps running while Manager restarts.
Name every folder yourself
Section titled “Name every folder yourself”To put each folder somewhere specific, use the long form of the launcher. Existing launch commands keep working the same way. Create these four folders first, using absolute paths:
| Folder | Keep here |
|---|---|
| Manager state | Manager settings, its local administrator account and operation history |
| Library | Your original photos and videos, and generated library files |
| Database backups | Encrypted database and recovery configuration backups |
| PostgreSQL appdata | The new database directory Manager will create on a local host disk |
sh launch.sh \ ghcr.io/frameleaf/frameleaf-manager:latest \ /srv/frameleaf/manager \ /srv/frameleaf/library \ /srv/frameleaf/database-backups \ 'https://server.example:2282' \ /srv/frameleaf/appdata \ '<server-lan-ip>'The fifth argument is the address you’ll open Manager at. On Unraid, use auto instead of the appdata path to use Settings → Docker → Default appdata storage location, which Manager shows you to confirm. You can choose a mounted disk in the wizard; it must already be made available to Manager.
3. Create your Manager administrator
Section titled “3. Create your Manager administrator”Manager opens full screen on Secure your Manager.
Manager’s administrator is a separate local account. No Frameleaf Cloud account is needed.
- Open Manager from a device on your home network.
- Enter your name and a password of at least 14 characters.
- Select Create administrator.
There’s no claim key. Setup only works from your home network, and only until Manager has an administrator, so create it soon after starting Manager.
This account manages the installation. You will also create or sign in to your photo library account during setup.
From here, a step rail beside the page shows where you are: Administrator, Choose how to begin, then Set up, which becomes New library, Import library, Import from another app or Restore a backup once you choose, followed by Install, Make it yours and Finish. Each page names its stage and step, such as New library · Step 1 of 3.
4. Review a new installation
Section titled “4. Review a new installation”Choose Set up Frameleaf for a new library. On a server without Immich, the Immich card offers Find installations; when Manager finds an installation, the card offers Review import instead. Select any screenshot in this guide to view it at full size.
Choose how to begin offers these ways in:
- Bring your photo library, when Manager finds an Immich installation on this server. If it didn’t find one, the card offers Find installations to look again.
- Import from another photo app, marked Beta, which lists other photo apps Manager found on this server. See Bring an existing library.
- Set up a new library, for a fresh start.
- Restore a backup, to bring a Frameleaf database back from a Manager backup. See Restore a Manager backup.
Nothing changes until you’ve reviewed it: every route ends in a review page before Manager installs, imports or restores anything.
- Under Set up a new library, select Set up Frameleaf. Manager opens Give your library a home.
- Enter a Library name. It starts as
Home library. - Choose the folder for Photos and videos. A big drive or array is fine. Manager creates it if it isn’t there, and your originals and generated media stay there. If you named every folder yourself, this is Media location, chosen from the mounted folders.
- Choose the Database folder. Under each folder, Manager shows the drive it’s on and how much room is left, such as Cache pool (NVMe SSD) · 180 GB free. When it finds a faster drive with room, it suggests it, and Use puts the database there. See How Manager suggests a drive. If you named every folder yourself, review PostgreSQL appdata location instead. Manager creates a new directory there and preserves existing database directories.
- Under Thumbnails, choose With your photos, the simplest choice, or On a faster drive. With On a faster drive, the Thumbnails folder starts as the folder Manager suggests, and you can choose another one. You can move thumbnails later too.
- Choose the Backups folder for encrypted database backups. Photos and videos aren’t included. If you named every folder yourself, check the Database backup destination. It’s the backup folder you mounted when you started Manager, and you can’t change it here.
- Check the Port (normally
2283) and Release Manager picked. If you named every folder yourself, choose the Frameleaf port and a verified Frameleaf release here. - Choose whether to turn on Faces and smart search. It runs on this server, and you can turn it off later. It starts on when Manager finds a supported NVIDIA, AMD or Intel GPU, and uses it. Without one, it starts off and runs on the CPU if you turn it on. If you named every folder yourself, this is Machine learning under Processing.
- Optionally, open Advanced container settings to add environment variables, extra folders (
/host:/container, with:rofor read-only) or a memory or CPU limit for the server, machine learning or database container. Each extra folder must already exist on the host. Manager keeps these settings through updates, restores and library moves, and you can change them later on the Containers page. - If you named every folder yourself, confirm that Docker or your NAS controls startup and that no additional scheduler will recreate the containers.
- Select Check this server. Manager looks at Docker, your folders, the port, the network and the signed release, and this can take up to a minute. Fix anything it lists, then select Review installation, read the paths and release, and select Install Frameleaf. See Check this server.
You can close the page while Manager works and reopen it any time to see progress. When the installation finishes, Manager shows All done. Carry on to Make it yours, or select Open Manager overview for Manager’s everyday controls. If an installation fails or is interrupted, read the error, then choose Resume safely to pick up where it left off, or cancel it, rather than starting a second installation over the same files.
For an Immich installation, follow Switch from Immich and choose Review import on the Bring your photo library card instead. For other sources, see Bring an existing library.
Check this server
Section titled “Check this server”Check this server is the last step before Manager installs anything. It says Manager is only looking. Nothing is downloaded or changed. while it works, and then shows everything it found at once: what needs fixing first, then what’s worth knowing, then what Looks good.
| Check | What Manager looks at |
|---|---|
| Docker | Docker answers, is version 24 or newer with Compose 2 or newer, and isn’t part of a swarm |
| Room for Frameleaf | Docker’s own storage has room for Frameleaf’s images: about 4 GB without machine learning, about 8 GB with it on the CPU |
| Photos and videos, Database, Thumbnails, Backups | Each folder is on a drive Manager can reach and save to, has room, and doesn’t overlap another one |
| Manager’s own folder | Manager can save there, with room for each database backup before it moves to your backups folder |
| Frameleaf port | No other app on this server is using the port |
| Container settings | Your advanced container settings can be applied |
| Downloads | This server can reach ghcr.io and github.com, where Frameleaf is downloaded from |
| Release signature | The release is signed, verified and has a build for this server’s processor |
| Memory | With faces and smart search on, a server with less than 8 GB gets a warning |
| Unraid Docker tab | On Unraid only: Frameleaf can be edited from Unraid’s Docker tab |
Only a problem stops the install. The heading then reads, for example, 2 things to fix before installing, and each one comes with the steps for your server. Some fixes are a single button: Use port 2284 when the port is taken, Choose another folder for a folder that won’t work, or Turn off faces and smart search on a server with little memory. Fix the rest on the server, then select Check again.
A warning or a Couldn’t check result never stops the install. If everything else is fine, Manager says This server is ready. If you’re stuck on a problem, the page offers a troubleshooting report to download and share when you ask for help. Manager removes passwords, folders and file names from it, but read it before you post it. See Problems Check this server can report for every message and its fix.
How Manager suggests a drive
Section titled “How Manager suggests a drive”Manager looks at the drives under the folders it can use and works out which are fast (SSD or NVMe) and which are hard drives. Then, for the database and for thumbnails, it suggests a fast drive with room:
- NVMe first, then the fast drive with the most free space.
- Room to grow. The drive must hold one and a half times what’s expected. A new library expects about 20 GB for the database and 50 GB for thumbnails. When thumbnails and the database would share a drive, the database’s space counts as taken.
- Only drives it’s sure about. A drive Manager can’t identify, or whose free space it can’t read, is shown but never suggested. Network shares are never suggested.
A suggestion reads like Suggested: Cache pool (NVMe SSD), with the reason, such as It has 180 GB free, and the database needs about 20 GB. When a fast drive is too full, Manager says so and doesn’t suggest it. When there’s no fast drive at all, it says Manager didn’t find an SSD or NVMe drive on this server. Hard drives work, just more slowly.
Detection is a hint, not a promise. You can always choose a different folder.
5. Finish your photo account and phone setup
Section titled “5. Finish your photo account and phone setup”Make it yours confirms the server is ready, then asks for your details and helps you get the app. On Your details, enter your profile and choose Continue with my local account, Create a Frameleaf account or I already have a Frameleaf account. A Frameleaf account is optional, and no subscription starts here. For a local account, select Continue without a Cloud account. Manager never asks for your Frameleaf password: you create or link the account in Frameleaf itself, during first-run setup. On Get the app, select Open local photo account setup, complete the photo application’s setup and connect your phone using the server address shown, then select Continue to library preparation.
Manager shows library verification and phone catalog preparation side by side. Follow any Library Care findings and use Verify the library again when asked, then select Finish setup. If you don’t want to wait for a phone, choose Skip and let the server run; you can come back with Continue setup on Manager’s Overview. Search, faces and thumbnails keep building in the background afterwards, and the processing panel shows their progress.
Keep the app open while its catalog and browsing previews prepare, and reopen it if the phone pauses it. Your originals stay on the server, so this doesn’t fill up your phone.
6. Save your recovery information
Section titled “6. Save your recovery information”Manager’s Overview starts with anything that needs you, then your library, its address and services. Backups opens your database recovery points. See Frameleaf Manager for every page.
In Manager settings, choose Export beside Configuration export, enter your Current Manager password and select Download. Store the file privately away from this server. In Backups, choose Export key and keep the key separately too. It contains recovery secrets, and it’s what gets you back up and running if this server is lost.
Use Make one now on Backups for a database recovery point. Manager’s backup does not contain your photos, videos or external libraries, so set up a media backup too. Back up the complete media tree, including thumbs, which also holds edited versions and develop artifacts that can’t be regenerated. See Backup and restore and First steps.
Several Frameleaf installations on one server
Section titled “Several Frameleaf installations on one server”One host can run several separate Frameleaf libraries, for example one for your household and one for a club or a parent’s house. Each installation has its own Manager, folders, database and photo app port, and nothing is shared between their libraries.
To add one, run the launcher again with a different Manager name and port, and with its own parent folder:
MANAGER_NAME=frameleaf-manager-family MANAGER_PORT=2284 sh launch.sh \ ghcr.io/frameleaf/frameleaf-manager:latest \ 'https://server.example:2284' \ /srv/frameleaf-family \ '<server-lan-ip>'With the long form, give new state, library and database backup folders instead. The appdata folder can be shared, because each installation keeps its own database folder inside it.
The launcher refuses a state or backup folder that another installation already uses, and Manager refuses a library folder or photo app port that another one has. Setup suggests the first free photo app port from 2283 and names the ports already taken. Every Manager on the host lists the other installations in its sidebar, so you can switch between them, and Add installation walks you through adding another.
On Unraid, add the Manager template again with a new name, port and folders. On TrueNAS, install the YAML again as a separate app with its own port and MANAGER_DATA folder.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.





