Skip to content

Frameleaf Manager

Frameleaf Manager installs your library, keeps it running and looks after it: backups, updates, drives and the settings of each container. It runs in its own container, so your photo library keeps running if Manager stops.

These are Manager’s pages on Unraid, TrueNAS, HexOS and Docker. The Synology app has its own pages; see Synology.

Page What it’s for
Overview What needs you, your library at a glance, Frameleaf’s address and the services
Services Start, stop and restart, logs, troubleshooting and external folders
Containers Settings, folders and limits for each container, and everything Manager sets
Storage Your drives, where each part of the library is, and moving it
Backups Recovery points of the database, the recovery key and restoring
Updates New versions of Frameleaf and automatic updates
Activity Every setup, update, backup and move Manager has run
Manager settings Manager’s own account, sign-in and configuration export

Manager Overview: Everything is running, one suggestion for this server, photo count, free space on the photos drive, the last recovery point, Frameleaf’s address and the services with Edit.

The Overview starts with anything that needs you. Select the image to enlarge it.

The first card says Everything is running or how many things need you, worst first. Each one has a button to the page that fixes it:

  • a service that has stopped or isn’t answering;
  • a drive that’s 90% full or nearly full;
  • no recovery point for more than a week;
  • settings someone changed in Docker or Unraid, which the next update would remove;
  • a new version of Frameleaf;
  • settings that would suit your server better than the defaults.

Below it are your photo and video count, the free space on the photos drive, the last recovery point (such as Last night, 2:00 AM), Frameleaf’s address with Copy for setting up phones, and each service with its settings and Edit. The panel on the right shows this server: processor cores, memory, graphics card and Docker version.

Services starts, stops and restarts the whole stack, and shows each service and its state, such as Ready. Choose Logs beside a service to read its recent output, or Check connections under Troubleshooting to test Docker, the database, machine learning, network discovery, the internet and your drives. Download report saves a troubleshooting report with those checks and the last day of logs from every service, ready to attach when you ask for help. Manager removes passwords, folder paths, file names and email addresses from it, but read it before you post it. Edit beside a service opens its settings on Containers. Add folders Frameleaf can show without moving them under External folders; see Try Frameleaf without moving your photos.

Your library runs as three containers: Frameleaf server, Machine learning and Database. Manager writes their settings itself and writes them again on every update, restore and library move. Anything you change on a container in Docker or the Unraid Docker tab is lost the next time. Change it on Containers instead, and it’s kept.

Open Containers, or choose Edit beside a service on Overview or Services. There’s a tab for each container.

Manager Containers page for Frameleaf server: How Manager runs it, a suggestion for this server, and the settings added, each with its plain name, variable, default and control.

Each container’s tab shows how Manager runs it, then your settings. Select the image to enlarge it.

The first card shows what Manager has set up for the container, so you know what’s already there before you add anything:

  • Container name, the name to use with docker logs or docker exec.
  • Image, the version it runs. It changes with each update.
  • Address, where the Frameleaf app answers, such as 0.0.0.0:2283 → 2283.
  • Restarts, Starts after, Health check and Time to stop: how Docker keeps it running.
  • Shared memory. The server gets 2 GB, because Locked files are opened in memory and never written to disk.
  • Database tuning: the memory settings Manager gives PostgreSQL for this server, applied again on every start.
  • Graphics card, when Manager found one for machine learning.

Choose View in compose.json to see the container exactly as Manager wrote it, your settings included, and Copy it. Passwords never appear there: the database password is kept in a file only the containers can read.

Settings are the container’s environment variables. The ones Frameleaf reads are shown by what they do, such as Thumbnail workers for FRAMELEAF_SHARP_WORKERS, with their default and a control to match: a list, an on/off switch or a number in everyday units, like seconds or GB.

Choose Add a setting… to add one. Search by what you want, such as log, iCloud, proxy or memory, and choose it from the list. To add a variable that isn’t listed, type its name and value under A variable that isn’t listed. Manager checks the name as you type:

  • An old IMMICH_ name gets Use FRAMELEAF_… to switch to the name Frameleaf reads now.
  • A name that’s nearly right, such as FRAMELEAF_TRUSTED_PROXY, gets Did you mean FRAMELEAF_TRUSTED_PROXIES?.
  • A name Manager sets itself, such as DB_HOSTNAME, is refused, so the stack keeps working after updates.
  • Any other name is passed to the container as it is.

Don’t put passwords or tokens here: anyone who can open Manager can read these settings.

If you’d rather type, choose Edit as text and write one NAME=value per line. Lines starting with # are ignored. Choose Done to go back; a line Manager can’t accept is named, and stays until you fix it.

For what each variable does, see Environment variables.

Manager knows your server’s processor cores, memory and graphics card. When a default doesn’t suit them, Suggested for this server lists the setting, its current value, the suggested one and why. Choose Use, Use all or Not now. Each setting also shows its suggestion, or Suits this server when it already matches.

Your server Suggestion
Any Thumbnail workers: about one for every 2 cores and 4 GB of memory, from 1 to 8. A server with 8 cores and 32 GB gets 4
8 GB of memory or less A smaller Largest image to open, fewer Models kept loaded, and models unloaded sooner
32 GB of memory or more Machine learning keeps models loaded longer, so search answers faster
Intel graphics Intel graphics precision FP16, which is faster there
NVIDIA card Run Studio masks on cuda

These are starting points. If thumbnails or search feel slow or the server runs short of memory, change the number and watch how it goes.

Folders are folders on your server that a container can see. Frameleaf only sees the folders you add.

  1. Choose Add a folder… and pick the folder on your server.
  2. Check Inside Frameleaf, the path the container sees, such as /external/archive. Manager suggests one; you can change it.
  3. Choose what it’s Used for:
    • Show in the library, for photos Frameleaf shows without moving them.
    • Imports, for a folder an import reads, such as a Google Photos export. Manager adds it to FRAMELEAF_IMPORT_ROOTS for you.
    • Recovering missing files, for an old copy of your library. Manager adds it to FRAMELEAF_RECOVERY_ROOTS, so Library care can find good copies there.
    • Something else.
  4. Leave Read-only on unless Frameleaf needs to write there.

Manager never gives a container the server’s own system folders, Docker’s folder or Manager’s settings, and refuses paths it uses itself, such as /data.

Memory and Processor stop a container from using more of the server than you want. Manager only offers what your server has, and warns when a limit is too small. For example, the server needs about 3.5 GB with 4 thumbnail workers, so a 2 GB limit could stop it from starting.

Under your settings and folders, Set by Manager lists everything Manager puts in the container: each variable and folder with a plain name, its value and what it’s for.

Set by Manager on the Frameleaf server tab: the database address, port, account and password file, the library ID, Manager’s address and access file, each with its value, what it’s for and a lock or Change button.

Manager’s own settings, shown so you know the whole container. Select the image to enlarge it.

  • Change appears on values you can override here, such as the log level chosen at setup. It adds the setting to your list with its current value.
  • A page name, such as Storage, appears where another page changes it: the photos folder and the database folder are moved on Storage.
  • A lock means Manager needs that value to keep the stack working, such as how Frameleaf finds its database.

When someone has added a variable or folder to a running container outside Manager, Containers shows Changed outside Manager with each one, and the Overview lists it too. The next update would remove them.

Changed outside Manager: IMMICH_LOG_LEVEL=debug and a Scans folder added in Docker or Unraid, with Keep them here and Let the update remove them.

Settings added in Docker or Unraid, offered back so updates keep them. Select the image to enlarge it.

Choose Keep them here to add them to your settings, then save. Variables the image sets itself, such as PATH, aren’t counted as changes.

Changes wait until you save them. The bar at the bottom shows how many there are and which containers restart. Choose Discard to undo them all, or Review and save…:

  1. The review lists every change for each container, such as Time zone: America/Edmonton → Europe/London, and what pauses while it restarts. Photos pause for about a minute when the server restarts.
  2. Choose Save and restart. Manager records your current settings, writes the new ones and restarts only the containers whose settings changed.
  3. If a container doesn’t start, the progress page offers to put the previous settings back.

Manager Storage page: a Drives summary with each drive’s free space and what’s on it, the photos, database and thumbnails cards, and Also on this server.

Drives at the top shows each drive, how full it is and what of your library is on it, such as Photos and videos 1.8 TB · Thumbnails 86 GB · Backups. Below are your photos and videos, the database and thumbnails, each with Move…, and Also on this server: the backups folder, the machine learning models and the extra folders added on Containers. To move something, see Move data to another drive.

Manager Backups page: Last recovery point Last night, 2 AM with Make one now, where they’re kept with a same-drive warning, the recovery key, and the list of recovery points with Restore.

Backups keeps recovery points of the database: albums, people, edits and settings. Photos and videos aren’t copied. The page starts with the last recovery point and Make one now. Manager also makes one before every update, restore, import and database move. It warns when backups are on the same drive as your photos, since a failing drive would take both. See Backup and restore.

Manager Updates page: 1.2.18 is ready, what’s new in it, the four steps installing it takes, and Install updates automatically.

Updates shows the version you’re on and when Manager last checked. When a new one is ready, it shows what’s new and what installing it does, then Review this update. Install updates automatically is on from the start: Manager checks every few hours and installs one version at a time, each after a recovery point. Turn it off and updates wait for you here. See Upgrading.

Activity lists every setup, update, backup, restore and move Manager has run, newest first, with the step it reached. Choose Details to open one. If an operation was interrupted, its page offers Resume safely, and where it’s still safe, a way to cancel.

Manager settings holds Manager’s own administrator: change the name or password here, which signs out every other Manager session. Export beside Configuration export downloads Manager’s recovery configuration; keep it with your recovery key, away from the server. See Accounts, passwords and where they’re kept.

When more than one Frameleaf installation runs on the server, each Manager lists the others in its sidebar, and Add installation walks you through adding another. See Several Frameleaf installations on one server.