Unraid
Frameleaf Manager is the easiest way to run Frameleaf on Unraid, and it’s listed in Community Apps as Frameleaf. Installs from before the listing was renamed keep the container name frameleaf-manager. It uses the host Docker engine, picks up your appdata location automatically, and shows you every storage and release choice before it creates anything.
Install with Manager
Section titled “Install with Manager”There’s nothing to prepare first. The template has no folders to fill in, and you choose where Frameleaf keeps everything during Manager’s setup.
- On your Unraid server, open the Apps tab, search for Frameleaf and choose Install. You can also find it in the Community Apps catalog and install it from there.
- Leave Server folders set to
/mnt, leave Manager origin blank and select Apply. You open Manager from the WebUI link, by NAS IP address ortower.local. Only if you use a custom DNS name or plain HTTP, set Manager origin and Advanced View → WebUI to that exact address with its port, such ashttp://tower.local:2282. HTTP isn’t encrypted, so use it only on a trusted network. - Leave State path, Unraid autostart file and Autostart controller path as they are. For an import, Manager finds Docker’s autostart list by itself and uses it so Immich can’t start again at boot. Source folders under
/mntare already available to Manager, so there’s nothing else to map. - Open the WebUI from a device on your home network. Your browser warns that the connection isn’t private, because Manager makes its own certificate for your home network. Continue to the page and follow Create your Manager administrator.
- When you set up a new library, check the folders on Give your library a home. Photos and videos starts as
/mnt/user/frameleaf-photos, on your array. The Database starts in your appdata location, read from Settings → Docker → Default appdata storage location, and moves to a fast pool when Manager finds one with room, such as/mnt/cache/appdata/frameleaf-databases. Backups starts under your appdata location too. Select Browse to use another share or drive. Manager creates any folder that isn’t there yet, but never a share or drive that doesn’t exist. - Under Thumbnails, keep With your photos, or choose On a faster drive to keep them on a pool. Then select Check this server.
Keep these in mind when you choose:
- Put the database on a local disk, ideally a fast pool, outside Docker’s virtual disk and data root. A custom share or pool is used as you set it, and an exclusive share is resolved to its actual disk location.
- Keep photos, the database and backups in separate folders.
- Back up the media independently; Manager’s backup contains only the database and recovery configuration.
Drives and suggestions on Unraid
Section titled “Drives and suggestions on Unraid”Under each folder, Manager shows its drive and how much room is left, such as Cache pool (NVMe SSD) · 180 GB free or Hard drive array. Manager knows the array is hard drives from its path alone, so it never writes to the array to test it and never wakes spun-down disks. Each pool is checked, and Unassigned Devices drives are listed by their name. Network shares under /mnt/remotes show as Network share and are never suggested.
For the database and thumbnails, Manager suggests the fastest pool with room, with a new folder in that pool’s appdata, such as /mnt/cache/appdata/frameleaf-thumbnails. It prefers NVMe, then the pool with the most free space, and only suggests a pool that holds one and a half times what’s expected. See How Manager suggests a drive.
Check this server on Unraid
Section titled “Check this server on Unraid”Check this server looks at Docker, your folders, the port, the network, the signed release and memory before anything is downloaded, and lists every problem at once with steps for Unraid. See Check this server. Two checks matter most on Unraid:
- Room for Frameleaf. Unraid keeps Docker in a fixed-size
docker.img. If it’s too small, open Settings → Docker, set Enable Docker to No, raise Docker vDisk size to at least 40 GB, then turn Docker back on. Your containers stop while Docker is off. - Unraid Docker tab. If Frameleaf won’t be editable from Unraid’s Docker tab shows, Frameleaf still installs and runs. To fix it, follow the Unraid Docker tab steps.
To show photos you already keep somewhere else, add the folder under External folders in Manager, during setup or later on the Services page. Nothing is moved or copied, and folders are read-only by default. Frameleaf only sees the folders you add. Choose a folder inside a share, not a whole share or a folder holding Frameleaf’s own data. Adding one on Services restarts Frameleaf, which pauses photo access for about a minute.
An install from an earlier template keeps its own folder mappings and location variables, and works as before.
To install without Community Apps, use the standalone template from the newest Manager release: download frameleaf-manager.xml and SHA256SUMS, verify the template’s checksum, then add it and follow steps 2 to 6. Keep manager-manifest.json from the same release; the same SHA256SUMS covers it.
The template gives Manager access to the host Docker engine, so keep its administration on a trusted network. Once it’s running, Manager installs the photo application for you from a signed release.
For a launcher installation instead, follow Install with Frameleaf Manager and name every folder yourself. Use auto for its appdata argument to detect Unraid’s setting, or supply an explicit existing folder.
In the setup review, check the database location, media mappings, application port and release. If you use a scheduler or plugin that recreates containers, pause it while an operation runs.
From then on, Manager’s Overview is your home for logs, database backups, start/stop and updates. To change a container’s variables, folders or limits, use Manager’s Containers page: changes made to the Frameleaf containers in Unraid’s Docker tab are replaced on the next update. Keep its exported recovery configuration somewhere private, away from the NAS.
Manual Compose alternative
Section titled “Manual Compose alternative”If you use the Docker Compose Manager plugin, create a stack using the matching Frameleaf release’s Compose file and environment example. Follow Manual Docker Compose installation.
Set absolute host paths for UPLOAD_LOCATION and DB_DATA_LOCATION before starting, so your data doesn’t land in the plugin’s configuration directory on the boot device. Use a new local-disk PostgreSQL folder and the database image supplied by the Compose file.
The release’s named containers include frameleaf_server, frameleaf_postgres and frameleaf_machine_learning. From your home network, open the NAS address on port 2283 and set up the server soon after installing. See First steps.
Already have a Frameleaf stack? Back it up, then update it in place, keeping one stack per database. See Upgrading.
Manual Server and Machine Learning templates
Section titled “Manual Server and Machine Learning templates”Community Apps also lists two templates for people who would rather run the containers themselves, without Manager: frameleaf-server and frameleaf-ml. Manager doesn’t manage or update an installation made this way.
- frameleaf-server is the photo application. Set its Library folder, Web port (normally
2283) and the database host, name, user and password. - frameleaf-ml is the optional machine learning companion for smart search and faces. The server template’s Machine learning URL points at it,
http://frameleaf-ml:3003by default. Give both templates the same Studio worker enrolment folder so Studio works in the browser. - The database isn’t included. Run a separate PostgreSQL container on the same Docker network, named to match the server’s Database host (
frameleaf-postgresby default), using the database image named by the matching Frameleaf release and a new, empty folder on a local disk. A generic PostgreSQL image won’t work.
Then open the NAS address on the web port from your home network and follow First steps. To move an installation like this to a release with a different database image, see Moving to a new database build.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.