Skip to content

TrueNAS

Frameleaf’s TrueNAS catalogue listing is still under review. For now, install manually through Custom App → Install via YAML on TrueNAS 24.10.2.2 or later.

The easiest way in is Frameleaf Manager, which installs as a Custom App and then guides you through setting up, backing up and updating your library. If you prefer, you can run Frameleaf as your own custom Compose app instead.

On HexOS, which runs on TrueNAS, use the HexOS guide instead. It installs Manager with a HexOS install script that uses your HexOS locations.

Each Frameleaf Manager release publishes a Custom App file for TrueNAS 24.10.2.2 or later. There’s nothing to create first: you name one of your pools, and Manager creates your folders during setup.

  1. From the newest Manager release, download frameleaf-manager.compose.yaml and SHA256SUMS, and verify the Compose file’s checksum. Keep manager-manifest.json from the same release; the same SHA256SUMS covers it.
  2. In Custom App → Install via YAML, paste the file. In MANAGER_DATA, replace POOL_NAME with the name of one of your pools, as listed under Storage. For a pool called tank, the line reads MANAGER_DATA: /mnt/tank/frameleaf/manager. It’s the only value to edit.
  3. Install the app, then from a device on your home network open https://<nas-ip>:2282, or use your NAS’s .local name. Your browser warns that the connection isn’t private, because Manager makes its own certificate for your home network. Continue to the page and create your Manager administrator.
  4. When you set up a new library, choose a folder for Photos and videos, one for the Database and one for Backups, and choose where Thumbnails go: With your photos, or On a faster drive. Manager shows your pools and creates any folder that isn’t there yet. Each one must be inside a pool rather than the top of it, and they must be separate from each other. Keep the database on local storage, preferably an SSD or NVMe pool.
  5. Select Check this server, fix anything it lists, then select Review installation and Install Frameleaf.

If you’re importing a library, folders on your pools are already available to Manager, so there’s nothing else to map.

Under each folder, Manager shows its pool and how much room is left, such as tank pool (hard drive) · 2.1 TB free. ZFS doesn’t say what kind of disk a pool is on, so Manager times a few small writes to tell an SSD or NVMe pool from a hard-drive pool. For the database and thumbnails, it suggests the fastest pool with room, with a new folder inside it. 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. Your boot pool is never offered. See How Manager suggests a drive.

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 TrueNAS. See Check this server.

  • Docker is too old. Open System → Update and install the latest TrueNAS version.
  • Not enough room in Docker’s storage. Open Apps → Configuration → Choose Pool to see which pool holds your apps, then free some space on it or remove apps you no longer use.
  • Manager can’t reach a folder. A folder outside your pools needs adding to the app. Open Apps, choose Frameleaf Manager, select Edit, add the folder under volumes with the same path on both sides, add it to the variable the check names, such as MANAGER_STORAGE_ROOTS, and save.

For every message and its fix, see Problems Check this server can report.

If the pool name in MANAGER_DATA doesn’t exist, Manager stops with a message in the app’s logs and writes nothing to your boot disk. Correct the name and restart the app.

Manager answers on your NAS’s IP address or .local name with no further setup. To open it by a custom domain name instead, add MANAGER_ORIGIN to the app’s environment with that exact address and port. An existing install keeps the folders it was set up with.

Manager controls the host Docker engine, so keep its administrative address on a trusted network. Once it’s running, Manager installs the photo application for you from a signed release.

Skip this section if you installed Manager. Running Frameleaf as your own Compose app means preparing the storage yourself.

Create separate datasets for the library and PostgreSQL, for example:

  • /mnt/tank/frameleaf/library
  • /mnt/tank/frameleaf/postgres19

Keep the live database on local storage, preferably an SSD pool. Give each dataset the permissions the release’s container user needs, using the UID from that release’s image. If you hit an ownership error, fix the owner rather than making the database world-writable.

If your media dataset uses ACLs, let the application create and rename files and update their permissions, so the storage template works. Back up the dataset before changing ACLs on an existing library.

  1. Download docker-compose.yml and example.env from the same photo application Frameleaf release, rather than a Manager release. Save example.env as .env for Compose substitutions.
  2. Substitute the absolute dataset paths for UPLOAD_LOCATION and DB_DATA_LOCATION.
  3. If your app editor doesn’t load .env, replace each env_file entry with the environment values it needs and fill in the Compose substitutions before saving.
  4. Set a random database password. The server’s DB_PASSWORD, DB_USERNAME and DB_DATABASE_NAME must match the database service’s POSTGRES_PASSWORD, POSTGRES_USER and POSTGRES_DB. The new-database example uses frameleaf as its name.
  5. Use FRAMELEAF_VERSION=latest and keep the database image, dependencies, health checks and ports supplied by the Compose file. Keep the PostgreSQL parent mount at /var/lib/postgresql.
  6. In Custom App → Install via YAML, paste the resulting YAML, install the app, then inspect its container logs.
  7. From your home network, open http://<nas-ip>:2283 and complete First steps soon after installing.

See Manual Docker Compose installation and Environment variables for the full configuration.

Frameleaf is not yet available through the TrueNAS Apps catalogue. Use Manager as a Custom App or the manual custom app above while the listing is under review. A downloadable catalogue package does not mean the app has been accepted into the catalogue.

For either manual method, keep the database image supplied by the matching Frameleaf release. Do not substitute a catalogue PostgreSQL app or point an older PostgreSQL image at the Frameleaf database directory.

With Manager, update Frameleaf from Manager’s Updates page, which installs new versions automatically unless you turn that off. See Upgrading.

For a manual custom app, save a database dump, a media backup and the custom app configuration before updating. Keep the same datasets and credentials when you apply the new release’s YAML, and keep each PostgreSQL data directory with the database image that created it. If the new release names a different database image, follow Moving to a new database build.

Manager’s Make one now on Backups protects the database and recovery configuration. Protect your photos and videos with separate backups or snapshots of the media datasets, and test a restore. See Backup and restore and Upgrading.