# Install with Frameleaf Manager

Source: https://frameleaf.app/docs/start/install/

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](https://frameleaf.app/docs/nas/synology/).** 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](https://frameleaf.app/docs/start/requirements/) before you begin. If you prefer to manage containers yourself, use [Manual Docker Compose installation](https://frameleaf.app/docs/start/manual-install/).

:::caution[Manager and photo application releases]
[Frameleaf Manager](https://github.com/Frameleaf/frameleaf-app/releases?q=manager) is published for Linux **amd64 and arm64**. Its container is `ghcr.io/frameleaf/frameleaf-manager:latest`, which always follows the newest Manager release. The literal GitHub `latest` tag points to the same source commit. Each Manager release includes an Unraid template, a TrueNAS Custom App Compose file and a HexOS install file; use the [Unraid](https://frameleaf.app/docs/nas/unraid/), [TrueNAS](https://frameleaf.app/docs/nas/truenas/) or [HexOS](https://frameleaf.app/docs/nas/hexos/) guide for those platforms.

Manager and the photo application are separate releases. Install the photo library from the matching signed application release that Manager offers. Keep PostgreSQL 19 images and storage apart from a PostgreSQL 14 installation. Synology's native app and SPK are distributed separately; see [Synology](https://frameleaf.app/docs/nas/synology/).
:::

## 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](https://frameleaf.app/docs/nas/unraid/) instead.

## 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:

```sh
curl -fL -o launch.sh https://raw.githubusercontent.com/Frameleaf/frameleaf-app/latest/manager/launch.sh
curl -fL -o cosign.pub https://raw.githubusercontent.com/Frameleaf/frameleaf-app/latest/cosign.pub
```

Replace the Manager address and LAN address with your own:

```sh
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

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:

```sh
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](#how-manager-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

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
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

Manager opens full screen on **Secure your Manager**.

[![Frameleaf Manager's full-screen Secure your Manager page, with Administrator name and Password fields and a Create administrator button.](https://frameleaf.app/shots/docs/manager-secure-2026-10.jpg)](https://frameleaf.app/shots/docs/manager-secure-2026-10.jpg)

*Manager's administrator is a separate local account. No Frameleaf Cloud account is needed.*

1. Open Manager from a device on your home network.
2. Enter your name and a password of at least 14 characters.
3. 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

[![Frameleaf Manager's Choose how to begin page. A step rail lists Administrator, Choose how to begin, Set up, Install, Make it yours and Finish. An Immich card reports that no supported Immich installation was found and offers Find installations, above Set up a new library and Restore a backup.](https://frameleaf.app/shots/docs/manager-choose-how-to-begin-2026-10.jpg)](https://frameleaf.app/shots/docs/manager-choose-how-to-begin-2026-10.jpg)

*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](https://frameleaf.app/docs/migrate/from-another-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](https://frameleaf.app/docs/admin/backup-and-restore/#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.

1. Under **Set up a new library**, select **Set up Frameleaf**. Manager opens **Give your library a home**.
2. Enter a **Library name**. It starts as `Home library`.
3. 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.
4. 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](#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.
5. 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](https://frameleaf.app/docs/admin/move-data-to-another-drive/) too.
6. 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.
7. 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.
8. 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**.
9. Optionally, open **Advanced container settings** to add environment variables, extra folders (`/host:/container`, with `:ro` for 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](https://frameleaf.app/docs/admin/manager/#containers) page.
10. If you named every folder yourself, confirm that Docker or your NAS controls startup and that no additional scheduler will recreate the containers.
11. 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](#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](https://frameleaf.app/docs/migrate/from-immich/) and choose **Review import** on the **Bring your photo library** card instead. For other sources, see [Bring an existing library](https://frameleaf.app/docs/migrate/from-another-library/).

### 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](https://frameleaf.app/docs/help/troubleshooting/#problems-check-this-server-can-report) for every message and its fix.

### 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

**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](https://frameleaf.app/docs/start/first-steps/#add-a-frameleaf-account). 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

[![Manager Overview: Everything is running, the photo count, free space on the photos drive, the last recovery point, Frameleaf's address and the services with Edit.](https://frameleaf.app/shots/docs/manager-overview-2026-11.jpg)](https://frameleaf.app/shots/docs/manager-overview-2026-11.jpg)

*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](https://frameleaf.app/docs/admin/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](https://frameleaf.app/docs/admin/backup-and-restore/) and [First steps](https://frameleaf.app/docs/start/first-steps/).

## 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:

```sh
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.
