TrueNAS

This guide covers TrueNAS Community Edition 24.10.2.2 (Electric Eel) and later, which run apps with Docker. On an older version, upgrade first; the TrueNAS release notes list breaking changes and how to upgrade.

Caution

Frameleaf isn’t in the TrueNAS apps catalogue. The catalogue’s community app installs other software, so don’t use it. Install Frameleaf from its Compose file as a custom app.

1. Create the datasets

Frameleaf needs two datasets: one for your photos and one for the database. You can name them to suit you; this guide uses a parent frameleaf with two children, /mnt/tank/frameleaf/data and /mnt/tank/frameleaf/pgData. See TrueNAS’s guide to creating datasets.

1. Create the parent dataset frameleaf with the default Generic preset.
2. Create data inside it with the Apps dataset preset. This gives the apps user (UID 568) the modify permission it needs.
3. Create pgData inside it with the Generic preset, then make the user netdata (UID 999) its owner. Postgres won’t start otherwise.

Dataset	Preset	Permission needed
frameleaf	Generic
data	Apps	Modify for the user that runs the app (apps, UID 568, by default)
pgData	Generic	Owned by netdata (UID 999)

Tip

Put pgData on an SSD pool if you have one; the database is much faster there. Advanced users can also keep thumbnails on SSD, but it isn’t required.

The app can run as any user and group; the default is apps (UID 568, GID 568). If you choose a different user, keep the Generic preset for data and give that user the modify permission instead.

If the data dataset uses ACLs

Skip this if you created data with the Apps preset.

If data is shared over the network (its ACL Type is SMB/NFSv4) and you plan to use a storage template, set its ACL Mode to Passthrough. When the template moves files from upload to library inside the dataset, the server runs chmod and must be allowed to.

1. Go to Datasets and select the dataset.
2. Click Edit next to Dataset Details, then open Advanced Options.
3. Under ACL Mode, choose Passthrough and click Save. If it’s greyed out, set ACL Type to SMB/NFSv4 first.

2. Prepare the Compose file

1. Download docker-compose.yml and example.env from the latest Frameleaf release.
2. In docker-compose.yml, replace ${UPLOAD_LOCATION} with the path of your data dataset (for example /mnt/tank/frameleaf/data) and ${DB_DATA_LOCATION} with the path of pgData (for example /mnt/tank/frameleaf/pgData).
3. TrueNAS doesn’t read a separate .env file. Remove the two env_file: entries, then copy the values you need from example.env into an environment: section of each service, and replace the matching ${...} references in the file. You need at least DB_PASSWORD, DB_USERNAME, DB_DATABASE_NAME and FRAMELEAF_VERSION, plus TZ if you want your time zone. Choose your own database password, using only letters and numbers.

For example, the database service ends up like this:

  database:
    container_name: frameleaf_postgres
    image: ghcr.io/frameleaf/frameleaf-postgres:14-vectorchord0.4.3-pgvectors0.2.0
    environment:
      POSTGRES_PASSWORD: yourpassword
      POSTGRES_USER: postgres
      POSTGRES_DB: immich
      POSTGRES_INITDB_ARGS: "--data-checksums"
    volumes:
      - /mnt/tank/frameleaf/pgData:/var/lib/postgresql/data

and immich-server gets the same values as DB_PASSWORD, DB_USERNAME and DB_DATABASE_NAME:

  immich-server:
    container_name: frameleaf_server
    image: ghcr.io/frameleaf/frameleaf-server:release
    environment:
      DB_PASSWORD: yourpassword
      DB_USERNAME: postgres
      DB_DATABASE_NAME: immich
      TZ: Europe/London
    volumes:
      - /mnt/tank/frameleaf/data:/data
      - /etc/localtime:/etc/localtime:ro

Use the image tag from your release’s example.env (FRAMELEAF_VERSION) in place of release if you want to pin the exact version. Keep the rest of each service (ports, depends_on, health checks) as it is in the release file.

3. Install

1. In TrueNAS, go to Apps and click Discover Apps.
2. Open the menu next to Custom App and choose Install via YAML.
3. Name the app frameleaf, paste your edited Compose file and click Save.
4. When it’s running, open http://<truenas-ip>:2283 from your home network and follow first steps. The setup code is in the logs of the frameleaf_server container.

Update

1. Read the release notes and Upgrading, and make sure your library is backed up.
2. Download the new release’s docker-compose.yml and make the same edits as before.
3. Replace the app’s YAML with it and save.