Manual Docker Compose installation

Prefer to manage the containers yourself? This guide takes you from the release files to your first sign-in in five steps. For a guided setup with updates and recovery built in, use Frameleaf Manager.

Release compatibility

Keep the server, machine learning and database images from one matching release. Use the photo application’s supplied Compose files; the separately published Manager release does not supply them.

PostgreSQL 19 and PostgreSQL 14 have different physical database layouts, so keep each database directory with its own major version. Bring existing data across with the migration or restore workflow, and use the database image specified by the matching Compose file.

Download docker-compose.yml and example.env from the same published Frameleaf release, and use the database image already specified in that file.

New database required

These files create a new Frameleaf database. To bring in existing data, from another application or an older PostgreSQL major version, use library migration or backup and restore.

1. Download the release files

Choose a published photo application release that supplies both files, then replace <photo-application-release-tag> below. Use the release tag rather than /releases/latest/download/, because the latest GitHub release may be a Manager component release. In a new installation folder:

mkdir frameleaf-app
cd frameleaf-app
curl -fL -o docker-compose.yml 'https://github.com/Frameleaf/frameleaf-app/releases/download/<photo-application-release-tag>/docker-compose.yml'
curl -fL -o .env 'https://github.com/Frameleaf/frameleaf-app/releases/download/<photo-application-release-tag>/example.env'

For a specific release, download both files from that release’s asset list. For an upgrade, preserve your current .env and follow Upgrading instead.

2. Set your storage and password

Edit .env before starting anything:

UPLOAD_LOCATION=/srv/frameleaf/library
DB_DATA_LOCATION=/srv/frameleaf/postgres19
TZ=America/Edmonton
FRAMELEAF_VERSION=latest
DB_PASSWORD=<your-random-alphanumeric-password>
DB_USERNAME=postgres
DB_DATABASE_NAME=frameleaf

Replace the example storage paths and database password. FRAMELEAF_VERSION=latest selects the current application and machine learning images. Choose a long random database password containing letters and numbers, as required by the release example. The Compose file supplies the compatible database image, so your images always come from one matching release and there’s no digest to copy.

• UPLOAD_LOCATION is the host folder containing originals and generated files. Allow room for previews, transcoded video and backups.
• DB_DATA_LOCATION is a new folder on local disk, preferably an SSD. Network shares are not supported for PostgreSQL.
• The PostgreSQL parent folder is mounted at /var/lib/postgresql. Retain the versioned database directory inside it.
• DB_DATABASE_NAME=frameleaf is the current example default. Preserve the configured name when restoring an existing Frameleaf installation.

The release starts frameleaf_server, frameleaf_postgres and frameleaf_machine_learning. Background jobs use PostgreSQL; Redis and Valkey are not required.

3. Configure optional settings

Most settings belong in the web app after setup. See Environment variables for host settings, database connections, machine learning, setup, logging and worker controls.

Compose reads .env for substitutions and passes the variables to services with an env_file entry, so a variable takes effect in each container that receives it. After changing .env, recreate containers with docker compose up -d; a restart alone doesn’t reload their environment.

For acceleration, the optional hwaccel.ml.yml and hwaccel.transcoding.yml release helpers supply GPU device mappings and runtime settings. Follow machine learning acceleration or video transcoding setup. The video guide also includes an inline Quick Sync option that does not need a helper download. Tip: get the CPU installation running first, then add acceleration.

4. Start and check the containers

docker compose config --images
docker compose up -d
docker compose ps
docker logs frameleaf_server

The first start takes a little while to download images and prepare the database. If a service fails, its logs tell you why; check them before changing storage paths or recreating data.

5. Create the administrator

Open http://<server-ip>:2283 from your local network and select Getting Started. Setup only works from your home network and only until the server has an administrator, so do it soon after installing. Finish First steps, then configure a backup.

Troubleshooting

• Use docker compose with a space, provided by Compose v2.
• For database ownership or mount errors, check that the database folder is on a supported local filesystem and writable by the database container.
• A new empty library after changing folders usually means a different host path was mounted. Stop and check the original paths before uploading more files.
• Keep docker compose down --volumes away from a library you want to keep: it removes volumes.

See Troubleshooting for logs and recovery checks.