Unraid

Frameleaf installs on Unraid with the Docker Compose Manager plugin from Community Applications, using the Compose file from a Frameleaf release.

Caution

Templates in Community Applications use community images of other software, not Frameleaf. Use the Compose method below.

Before you start

You need:

• the Docker Compose Manager plugin, installed from the Apps tab
• an Unraid share for your photos, such as images
• a pool for the database, ideally your cache pool on SSD (the appdata share is a good home)
• a CPU that meets the requirements. There has been a report of the machine learning container failing on servers whose CPU doesn’t support AVX (for example a Dell T610).

This guide was written on Unraid 6.12.10.

Install

1. Go to Plugins, then Compose.Manager.
2. Click Add New Stack. When asked for a label, enter Frameleaf and click OK.
3. Click the cog next to Frameleaf and choose Edit Stack.
4. Click Compose File. Delete anything already in the editor and paste the whole Frameleaf Compose file.
5. Click Save Changes. When you’re asked to edit stack UI labels, leave them blank and click OK.
6. Click the cog next to Frameleaf again, choose Edit Stack, then Env File.
7. Paste the whole example.env and, before saving, change:

   • UPLOAD_LOCATION: the absolute path of a folder in your photo share. For example, create a frameleaf folder in your images share; running pwd inside it in the terminal shows /mnt/user/images/frameleaf, which is the value to use.

   • DB_DATA_LOCATION: a folder on your cache pool, such as /mnt/user/appdata/postgresql/data. Create it first:

     mkdir -p /mnt/user/appdata/postgresql/data

     If you leave the default, Postgres tries to write inside the plugin’s folder (/boot/config/plugins/compose.manager/projects/<stack name>/postgres), has no permission, and restarts forever.

   • DB_PASSWORD: your own password, using only letters and numbers.

   • TZ: uncomment it and set your time zone.

8. Click Save Changes, then Compose Up. A window shows the images downloading and the containers starting. This can take several minutes, depending on your internet connection and hardware. When it says Connection Closed, click Done.
9. Go to the Docker page. Find frameleaf_server and its port mapping. For example, if it reads 172.18.0.7:2283/TCP ↔ 192.168.0.25:2283, open http://192.168.0.25:2283.
10. Follow first steps to create the admin account. You’ll need the setup code from the server’s log: click the frameleaf_server icon and choose Logs.

Older Docker versions and start_interval

Unraid 6.12.10 ships Docker Engine 24. Docker 25 or later is needed for the health check option start_interval. If your Compose file’s database service has start_interval (and start_period) lines and the stack won’t start, comment them out. The only downside is that the database’s first health check waits until the normal interval has passed.

Use an existing Postgres container

If you already run a Postgres container you want Frameleaf to use, change the Compose file before step 5:

1. Comment out the whole database service, from the database: line to its last line.
2. For each service that lists - database under depends_on:, comment out that line. If database is the only entry, comment out the depends_on: line too.
3. Comment out the database volume.

Then, in the Env File, set these to match your Postgres container:

Setting	Value
DB_HOSTNAME	Your Postgres container’s host name or IP
DB_USERNAME	Its user
DB_PASSWORD	Its password
DB_DATABASE_NAME	The database Frameleaf should use
DB_PORT	Its port, if not 5432

Frameleaf needs a Postgres server with the vector extensions it uses. See Environment variables and Database.

Group the containers with FolderView

If you use the FolderView plugin, you can group the Frameleaf containers:

1. On the Docker tab, choose New Folder.
2. Label it Frameleaf. For the logo, use https://raw.githubusercontent.com/Frameleaf/frameleaf-app/refs/heads/fork/main/web/static/favicon.png.
3. Turn on the toggle for each Frameleaf container and click Submit.

The Docker page then shows them under one collapsible Frameleaf folder.

Hardware acceleration

Compose Manager works with a single Compose file, so you can’t use the separate hwaccel files with extends. Copy the settings for your hardware into the Compose file instead. See Unraid, Portainer and single Compose files.

Update

Danger

Read the release notes and Upgrading before every update, and make sure your photos and database are backed up.

Containers managed by Compose Manager don’t integrate with Unraid’s own Docker page, so they always show update ready. Ignore that label and update when Frameleaf tells you a new version is out.

1. On the Docker tab, scroll to the Compose section.
2. Click Update Stack next to Frameleaf. You don’t need to click Compose Down first.
3. The window lists each container as it’s pulled and restarted. When it says Connection Closed, click Done.
4. Open the Frameleaf web app and check that it reports the version you updated to.

Note

The container names are frameleaf_*, while the Compose service names (immich-server, database and so on) stay the same for compatibility. Older IMMICH_* variable names in your Env File still work as deprecated aliases, so an existing stack keeps running when you update. See Moving from Immich.