Other ways to install

Every supported way to run Frameleaf uses the Compose file and example.env from a Frameleaf release. Docker Compose is the recommended route. This page covers the alternatives.

Method	Status
Docker Compose	Recommended
Unraid, Synology, TrueNAS	Supported, using the same Compose file
Portainer	Supported, using the same Compose file
Install script	Experimental
Rootless containers	Supported, using docker-compose.rootless.yml
Cloud server	Supported on a Linux VM with Docker
Kubernetes	Not supported yet
All-in-one image	Not available

Portainer

Install Frameleaf with Portainer’s Stacks feature.

1. Go to Stacks in the left sidebar and click Add stack.
2. Name the stack, for example frameleaf, and choose Web editor as the build method.
3. Paste the contents of the release’s docker-compose.yml into the editor.
4. Find every env_file: entry and change .env to stack.env.
5. In the Environment variables section, click Advanced mode.
6. Paste the contents of the release’s example.env.
7. Switch back to Simple mode and review the values:
   • Change DB_PASSWORD, using only letters and numbers.
   • Set DB_DATA_LOCATION to an absolute path on a local disk where the database will live.
   • Set UPLOAD_LOCATION to an absolute path where your photos and videos will be stored.
8. Click Deploy the stack.

When it’s running, open http://<server-ip>:2283 and follow first steps.

Before updating, read the release notes and Upgrading. If you pin FRAMELEAF_VERSION, change it in the stack’s environment variables before you redeploy so the new images are pulled.

Note

Portainer uses a single Compose file, so the hardware acceleration files can’t be referenced with extends. See Unraid, Portainer and single Compose files.

Install script

Caution

The install script is experimental and isn’t recommended for production. For a server you rely on, use Docker Compose.

The script needs Linux with Docker and the Compose plugin already installed. From the folder you want Frameleaf in, run:

curl -o- https://raw.githubusercontent.com/Frameleaf/frameleaf-app/refs/heads/fork/main/install.sh | bash

It:

1. Creates a frameleaf-app folder in the current directory.
2. Downloads docker-compose.yml and example.env (as .env) from the latest release.
3. Replaces the default database password with a random one.
4. Starts the containers with docker compose up -d.

When it finishes it prints the address, http://<machine-ip>:2283. Your library is stored in ./frameleaf-app/library, because UPLOAD_LOCATION stays at its default. Then follow first steps.

Run as a non-root user

Each release also includes docker-compose.rootless.yml, which runs the containers as a non-root user. Use it instead of the regular docker-compose.yml, not alongside it.

wget -O docker-compose.yml https://github.com/Frameleaf/frameleaf-app/releases/latest/download/docker-compose.rootless.yml

The rootless file runs every service as user and group 1000:1000, and uses folders next to the Compose file instead of Docker volumes: ./ml-model-cache for the machine learning models and ./redis for Redis. It also adds the hardening options shown below. Create those folders and make sure they, UPLOAD_LOCATION and DB_DATA_LOCATION belong to that user, or change user: to match your own.

You can also set the user option on each service in your own Compose file. Either way:

• The user and group need read and write access to every mount, including UPLOAD_LOCATION and the machine learning /cache folder.
• Redis needs a mount for /data.
• Docker Compose’s top-level volumes: don’t support non-root access, so use local folder mounts (bind mounts) for all of these.

For a more hardened setup in your own Compose file, add this to every service:

security_opt:
  # Prevent escalation of privileges after the container is started
  - no-new-privileges:true
cap_drop:
  # Prevent access to raw network traffic
  - NET_RAW

On a cloud server

No cloud marketplace offers Frameleaf as a one-click app yet, and the marketplace apps that exist install other software. To run Frameleaf on a cloud server, create a Linux virtual machine, install Docker, and follow Install with Docker Compose.

Remember that the server must be able to store your whole library. If you want off-site protection for a server at home rather than running it in the cloud, see Cloud backup.

Kubernetes

Frameleaf doesn’t support Kubernetes yet. There’s no Frameleaf Helm chart, and charts made for other software pull images that aren’t Frameleaf’s. Use Docker Compose, or one of the NAS guides, instead.

All-in-one images

There’s no all-in-one container image for Frameleaf. Community all-in-one images install other software. Use the release’s Compose file instead.

NAS app catalogues

The Unraid Community Applications templates and the TrueNAS apps catalogue entry install other software, not Frameleaf. Use the Compose-based guides for Unraid and TrueNAS instead.