Requirements
Frameleaf runs happily on a modest home server or NAS. Here’s what you need, and where a little extra makes it faster.
Hardware
Section titled “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. 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 thex86-64-v2microarchitecture level. Most CPUs released since about 2012 have it. In a virtual machine, choose a CPU type that passes it through (for examplehost, orx86-64-v2or 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.
Operating system
Section titled “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. Synology has a native SPK installed with Package Center → Manual Install for DSM 7.2.2-72806 or later with Container Manager 1432 or later. There are separate setup guides for Unraid, TrueNAS and HexOS.
Storage
Section titled “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, 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.
The database disk
Section titled “The database disk”A fast, stable connection to the database matters more than anything else for a smooth Frameleaf.
- Put
DB_DATA_LOCATIONon 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.
Windows
Section titled “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). 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=./postgresDB_DATA_LOCATION=pgdataAt the bottom of docker-compose.yml:
volumes: model-cache: pgdata:Software
Section titled “Software”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 |
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.