# Manual Docker Compose installation Source: https://frameleaf.app/docs/start/manual-install/ 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](https://frameleaf.app/docs/start/install/). :::caution[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](https://github.com/Frameleaf/frameleaf-app/releases)**, and use the database image already specified in that file. :::caution[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](https://frameleaf.app/docs/migrate/from-another-library/) or [backup and restore](https://frameleaf.app/docs/admin/backup-and-restore/). ::: ## 1. Download the release files Choose a published **photo application** release that supplies both files, then replace `` 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: ```bash mkdir frameleaf-app cd frameleaf-app curl -fL -o docker-compose.yml 'https://github.com/Frameleaf/frameleaf-app/releases/download//docker-compose.yml' curl -fL -o .env 'https://github.com/Frameleaf/frameleaf-app/releases/download//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](https://frameleaf.app/docs/admin/upgrading/) instead. ## 2. Set your storage and password Edit `.env` before starting anything: ```dotenv UPLOAD_LOCATION=/srv/frameleaf/library DB_DATA_LOCATION=/srv/frameleaf/postgres19 TZ=America/Edmonton FRAMELEAF_VERSION=latest DB_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](https://frameleaf.app/docs/admin/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](https://frameleaf.app/docs/admin/hardware-acceleration/) or [video transcoding setup](https://frameleaf.app/docs/admin/video-transcoding/#set-it-up). 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 ```bash 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://: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](https://frameleaf.app/docs/start/first-steps/), then configure a [backup](https://frameleaf.app/docs/admin/backup-and-restore/). ## 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](https://frameleaf.app/docs/help/troubleshooting/) for logs and recovery checks.