Skip to content

Requirements

Frameleaf runs happily on a modest home server or NAS. Here’s what you need, and where a little extra makes it faster.

Minimum Recommended
Memory 6 GB 8 GB
CPU 2 cores 4 cores
Platform amd64 or arm64
  • Memory. Frameleaf needs at least 6 GB for a smooth experience, especially while uploads are being processed. With only 4 GB it can run with machine learning turned off, which means no face recognition or smart search. With faces and smart search turned on, Manager’s Check this server warns on a server with less than 8 GB, because they can run out of memory.
  • CPU. On amd64, the machine learning container needs a CPU with the x86-64-v2 microarchitecture level. Most CPUs released since about 2012 have it. In a virtual machine, choose a CPU type that passes it through (for example host, or x86-64-v2 or newer, in Proxmox).
  • GPU (optional). A GPU isn’t required, but it makes a big difference to face recognition, smart search, AI descriptions and video on larger libraries. Intel (OpenVINO and Quick Sync), NVIDIA (CUDA and NVENC), AMD and others are supported. Manager finds a supported NVIDIA, AMD or Intel card and sets it up for you. See Hardware acceleration.

64-bit Linux, such as Ubuntu or Debian, is strongly recommended. It gives the best Docker experience and is what Frameleaf is tested on.

Use a Unix filesystem that supports file ownership and permissions, such as EXT4, ZFS, Btrfs, XFS or APFS.

Plan for more space than your originals take up. Thumbnails, previews, editing outputs and transcoded videos add to it, depending on your formats and settings, and processing and backups need room too.

Folder Set by What’s in it Where to put it
Library UPLOAD_LOCATION Your originals, plus thumbnails, transcoded video, profile pictures and database backups Anywhere with plenty of space, including a NAS share or hard drives
Thumbnails (optional) Manager’s Thumbnails choice The small images the timeline shows, when you keep them on a drive of their own A local SSD or NVMe drive
Database DB_DATA_LOCATION The Postgres database, size varies with library and indexes A local SSD or NVMe drive
Model cache Docker volume model-cache Downloaded machine learning models The default Docker volume is fine

Fast drives for the database and thumbnails

Section titled “Fast drives for the database and thumbnails”

Your photos and videos are fine on big, slow hard drives. Two things Frameleaf reads all the time are not:

  • The database. Browsing and search read it constantly, so an SSD or NVMe drive makes them noticeably faster.
  • Thumbnails. The timeline loads hundreds of small images at once, so large libraries scroll faster from an SSD or NVMe drive.

Thumbnails normally live with your photos and videos, which is the simplest choice and works well for most libraries. With Frameleaf Manager, you can give them a folder of their own on a faster drive when you set up, or move them there later. If that drive ever fails, your photos are untouched and Frameleaf can make new thumbnails from them.

For a new library, plan on about 20 GB for the database and about 50 GB for thumbnails, and more as your library grows. Manager only suggests a drive that has room for one and a half times that. Both folders need a drive inside the server: thumbnails can’t go on a network share, and neither can the database.

Manager finds the fast drives on your server for you, and Check this server tells you if the database ended up on hard drives while a faster drive has room.

A fast, stable connection to the database matters more than anything else for a smooth Frameleaf.

  • Put DB_DATA_LOCATION on local storage, ideally an SSD. Never use a network share (NFS, SMB/CIFS or similar) for the database.
  • If you set Docker resource limits, give the database container at least 2 GB of memory.
  • Corruption is most often caused by sudden power loss, network shares, SD cards or failing disks. See Check your database for corruption.

The database folder must be on a filesystem with Unix ownership and permissions. It won’t work on NTFS or exFAT/FAT32, and it won’t work under WSL on a folder mounted from Windows (usually under /mnt). For manual installations in that situation, keep the database in Linux-managed storage, such as a Docker volume. (Manager uses a supported Linux host disk rather than named database volumes.)

In .env:

DB_DATA_LOCATION=./postgres
DB_DATA_LOCATION=pgdata

At the bottom of docker-compose.yml:

volumes:
model-cache:
pgdata:

Manual installations need Docker with the Compose plugin. Frameleaf Manager additionally requires a Linux host, Cosign, findmnt and realpath for its launcher.

On Synology, install Container Manager in Package Center, then upload the released Frameleaf Manager SPK using Manual Install. The package runs the Manager service for you, so there’s no Linux launcher to run. Prepare the four storage folders and HTTPS hostname described in the Synology guide.

  • Docker Engine is the version for Linux servers (and Windows through WSL 2). Install it from Docker’s own repository rather than your distribution’s packages.
  • Docker Desktop is available for Windows and macOS. It isn’t recommended on Linux.

Both install the Compose plugin. You can also install it separately.

Frameleaf needs Docker 24 or newer, with Docker Compose 2 or newer, and room in Docker’s own storage for its images: about 4 GB without machine learning, and about 8 GB with machine learning on the CPU. Machine learning builds for a graphics card need more: about 10 GB in all for Intel, 14 GB for NVIDIA and 34 GB for AMD. The server also needs to reach ghcr.io and github.com, where Frameleaf is downloaded from. Manager checks all of this before it downloads anything.

Port Used for
2283 The web app, the phone apps and the API. Manual installations can publish another port with FRAMELEAF_HOST_PORT
2282 Standalone Manager HTTPS administration
9443 Synology only: Manager’s listener, local to the NAS; the native app uses DSM HTTPS instead
5001 Default DSM HTTPS port for the native Synology app; use the actual DSM port configured on your NAS
2443 Direct connections for Frameleaf Cloud remote access, only if you use it
5353 (UDP) Bonjour, so the phone apps can find the server on your Wi-Fi. It doesn’t cross VLANs