# Unraid

Source: https://frameleaf.app/docs/nas/unraid/

[Frameleaf Manager](https://frameleaf.app/docs/start/install/) is the easiest way to run Frameleaf on Unraid, and it's [listed in Community Apps](https://ca.unraid.net/apps?q=frameleaf) 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

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.

1. On your Unraid server, open the **Apps** tab, search for **Frameleaf** and choose **Install**. You can also find it in the [Community Apps catalog](https://ca.unraid.net/apps?q=frameleaf) and install it from there.
2. Leave **Server folders** set to `/mnt`, leave **Manager origin** blank and select **Apply**. You open Manager from the WebUI link, by NAS IP address or `tower.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 as `http://tower.local:2282`. HTTP isn't encrypted, so use it only on a trusted network.
3. 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 `/mnt` are already available to Manager, so there's nothing else to map.
4. 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](https://frameleaf.app/docs/start/install/#3-create-your-manager-administrator).
5. 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.
6. 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

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](https://frameleaf.app/docs/start/install/#how-manager-suggests-a-drive).

### 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](https://frameleaf.app/docs/start/install/#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](https://frameleaf.app/docs/help/troubleshooting/#frameleaf-wont-be-editable-from-unraids-docker-tab).

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](https://github.com/Frameleaf/frameleaf-app/releases?q=manager): 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](https://frameleaf.app/docs/start/install/) 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](https://frameleaf.app/docs/admin/manager/#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

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](https://frameleaf.app/docs/start/manual-install/).

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

Already have a Frameleaf stack? Back it up, then update it in place, keeping one stack per database. See [Upgrading](https://frameleaf.app/docs/admin/upgrading/).

## 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:3003` by 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-postgres` by 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](https://frameleaf.app/docs/start/first-steps/). To move an installation like this to a release with a different database image, see [Moving to a new database build](https://frameleaf.app/docs/admin/database/#moving-to-a-new-database-build).
