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.
Install Manager as a Custom App
Section titled “Install Manager as a Custom App”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.
- From the newest Manager release, download
frameleaf-manager.compose.yamlandSHA256SUMS, and verify the Compose file’s checksum. Keepmanager-manifest.jsonfrom the same release; the sameSHA256SUMScovers it. - In Custom App → Install via YAML, paste the file. In
MANAGER_DATA, replacePOOL_NAMEwith the name of one of your pools, as listed under Storage. For a pool calledtank, the line readsMANAGER_DATA: /mnt/tank/frameleaf/manager. It’s the only value to edit. - Install the app, then from a device on your home network open
https://<nas-ip>:2282, or use your NAS’s.localname. 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. - 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.
- 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.
Drives and suggestions on TrueNAS
Section titled “Drives and suggestions on TrueNAS”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 on TrueNAS
Section titled “Check this server on TrueNAS”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
volumeswith the same path on both sides, add it to the variable the check names, such asMANAGER_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.
Manual custom app
Section titled “Manual custom app”Skip this section if you installed Manager. Running Frameleaf as your own Compose app means preparing the storage yourself.
Prepare datasets
Section titled “Prepare datasets”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.
Install the app
Section titled “Install the app”- Download
docker-compose.ymlandexample.envfrom the same photo application Frameleaf release, rather than a Manager release. Saveexample.envas.envfor Compose substitutions. - Substitute the absolute dataset paths for
UPLOAD_LOCATIONandDB_DATA_LOCATION. - If your app editor doesn’t load
.env, replace eachenv_fileentry with theenvironmentvalues it needs and fill in the Compose substitutions before saving. - Set a random database password. The server’s
DB_PASSWORD,DB_USERNAMEandDB_DATABASE_NAMEmust match the database service’sPOSTGRES_PASSWORD,POSTGRES_USERandPOSTGRES_DB. The new-database example usesframeleafas its name. - Use
FRAMELEAF_VERSION=latestand keep the database image, dependencies, health checks and ports supplied by the Compose file. Keep the PostgreSQL parent mount at/var/lib/postgresql. - In Custom App → Install via YAML, paste the resulting YAML, install the app, then inspect its container logs.
- From your home network, open
http://<nas-ip>:2283and complete First steps soon after installing.
See Manual Docker Compose installation and Environment variables for the full configuration.
Catalogue packages
Section titled “Catalogue packages”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.
Updates and backups
Section titled “Updates and backups”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.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.