Install with Docker Compose

Docker Compose is the recommended way to run Frameleaf. It works on any 64-bit Linux machine with Docker, and it’s the same Compose file the NAS guides use. Check the requirements first.

Use matching release files

Always download the Compose file, example.env and any hardware acceleration files from the same Frameleaf release. The files on the development branch can differ from a published release, and Compose generators made for other software pick different images.

1. Download the Compose file and settings

Create a folder for Frameleaf and download two files from the latest release into it.

mkdir ./frameleaf-app
cd ./frameleaf-app
wget -O docker-compose.yml https://github.com/Frameleaf/frameleaf-app/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/Frameleaf/frameleaf-app/releases/latest/download/example.env

You can also download them in your browser and move them into the folder. If you do, rename example.env to .env.

For hardware acceleration, also download hwaccel.ml.yml and hwaccel.transcoding.yml from the same release before turning on their references in the Compose file. See Hardware acceleration.

Upgrading an existing installation?

Keep your current .env, storage paths, Compose project name and volume names rather than replacing them with the example. Never start a second stack against the same database folder. See Upgrading and, if you’re coming from Immich, Moving from Immich.

2. Edit the .env file

Open .env in a text editor. It looks like this:

# The location where your uploaded files are stored
UPLOAD_LOCATION=./library

# The location where your database files are stored. Network shares are not supported for the database
DB_DATA_LOCATION=./postgres

# To set a timezone, uncomment the next line and change Etc/UTC to a TZ identifier
# TZ=Etc/UTC

# Frameleaf image tag. Release bundles pin this to their matching version.
FRAMELEAF_VERSION=release

# Connection secret for postgres. You should change it to a random password
DB_PASSWORD=postgres

# The values below this line do not need to be changed
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

Change these values:

Setting	What to set
UPLOAD_LOCATION	A folder with plenty of free space. This is where your originals, thumbnails and database backups live. Use an absolute path such as /srv/frameleaf/library if the folder isn’t next to the Compose file.
DB_DATA_LOCATION	A folder on a local disk, ideally an SSD. Never a network share.
TZ	Uncomment it and set your time zone, such as Europe/London or America/Edmonton.
DB_PASSWORD	Your own random password. Use only letters and numbers (A-Za-z0-9) so Docker reads it correctly. The database isn’t exposed outside Docker, so it’s only used locally. A tool such as pwgen makes a good one.

Leave DB_USERNAME and DB_DATABASE_NAME as they are unless you’re connecting to your own Postgres server. FRAMELEAF_VERSION is pinned to the release you downloaded; see Upgrading for other tags.

Every other setting is optional. See Environment variables.

3. Start Frameleaf

From the folder with your docker-compose.yml and .env, run:

docker compose up -d

Docker downloads the images and starts four containers: frameleaf_server, frameleaf_machine_learning, frameleaf_postgres and frameleaf_redis. The first start takes a few minutes.

Check they’re running:

docker compose ps

4. Find the setup code

A new server prints an 8-character setup code (XXXX-XXXX) on its console and in its log until it has an administrator. You’ll need it in the next step. Show it with:

docker logs frameleaf_server

or print just the code:

docker exec -it frameleaf_server frameleaf-admin setup-code

The code changes every time the server starts, and a new one is issued after 5 wrong tries.

5. Create the admin account

Open http://<server-ip>:2283 in a browser from your home network and click Getting Started. A short setup walks you through the admin account (with the setup code), where your library lives, processing, backups and privacy.

The first account you create is the administrator, who can add everyone else. See First steps for the whole setup and what to do next.

Tip

You can also set up a brand-new server from the Frameleaf app on your phone with the same setup code. See iPhone and iPad or Android.

If something goes wrong

• unknown shorthand flag: 'd' in -d or open .env: permission denied: your distribution’s Docker package is too old or incomplete. Follow Docker’s Engine install guide for your distribution, including Uninstall old versions and Install using the apt repository (or rpm), to replace it with Docker’s own packages.
• 'name' does not match any of the regexes: '^x-': you ran the old docker-compose command. Use docker compose (with a space) from a current Docker install.
• can't set healthcheck.start_interval as feature require Docker Engine v25 or later: update Docker, or comment out the start_interval line in the database service.
• The database keeps restarting with an ownership error: the database folder is on a filesystem that doesn’t support Unix permissions, or on a network share. See Requirements.

More fixes are in Troubleshooting.

Next steps

• Work through first steps.
• Put Frameleaf behind a reverse proxy if you want your own domain and HTTPS, or use Frameleaf Cloud remote access.
• Read how to upgrade before the next release comes out.