Requirements

Hardware

	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.
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) and others are supported. See Hardware acceleration.

Operating system

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

Windows works with Docker Desktop or WSL 2, but expect a rougher experience and read the database notes for Windows below.
macOS works with Docker Desktop for Mac.
Virtual machines. Frameleaf runs well in a full virtual machine. Docker inside an LXC container isn’t recommended; if you hit problems there, move to a VM.
NAS systems. There are step-by-step guides for Unraid, Synology and TrueNAS.

Storage

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 and transcoded videos add roughly 10 to 20% to the size of your library on average.

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
Database	`DB_DATA_LOCATION`	The Postgres database, usually 1 to 3 GB	A local SSD
Model cache	Docker volume `model-cache`	Downloaded machine learning models	The default Docker volume is fine

The database disk

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 the database has to sit on hard drives, uncomment DB_STORAGE_TYPE: 'HDD' in the database service of docker-compose.yml.
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.

Windows

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). If that’s your situation, use a Docker volume for the database instead.

In .env:

DB_DATA_LOCATION=./postgres
DB_DATA_LOCATION=pgdata

At the bottom of docker-compose.yml:

volumes:
  model-cache:
 pgdata:

Software

Frameleaf needs Docker with the Docker Compose plugin.

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.

Ports

Port	Used for
`2283`	The web app, the phone apps and the API
`2443`	Direct connections for Frameleaf Cloud remote access, only if you use it