Skip to content

Environment variables

Most Frameleaf settings live in the web app. The few that shape the installation itself, such as where your files live and how the database connects, are environment variables, usually in the .env file next to your docker-compose.yml. This page lists them all; feature guides cover a few more. If you use Manager, make lifecycle and storage changes there instead, and set these variables on its Containers page, which keeps them through updates and lists them by what they do.

In the tables, Containers says which container reads the variable: the server, the machine learning container or the database. If you split the server into separate api and microservices workers, give each the variables it needs.

These are used by docker-compose.yml itself and don’t reach the containers directly.

Variable What it does Default
UPLOAD_LOCATION Folder on the host where your photos and videos are stored ./library in the example file
DB_DATA_LOCATION Folder on the host for the database. Network shares aren’t supported ./postgres19 in the example file
FRAMELEAF_VERSION Which application and machine learning image tag to run latest
FRAMELEAF_HOST_PORT The port on the server that the web app and phone apps use, when another service already has 2283 2283
FRAMELEAF_HOST_HTTPS_PORT The port on the server for direct Frameleaf Cloud connections. If you change it, set the same port in Remote access in the app 2443
COMPOSE_PROJECT_NAME Set to immich only for a stack first created by an early Frameleaf release, so Compose keeps using its containers and volumes frameleaf

Use the version and service definitions that come with the release, and keep its internal Compose service names. The containers you’ll see are frameleaf_server, frameleaf_machine_learning and frameleaf_postgres.

Variable What it does Default Containers
TZ Time zone, for example Etc/UTC. Used for log times, scheduled jobs, and photos whose metadata has no time zone server
FRAMELEAF_ENV production or development production server, machine learning
FRAMELEAF_LOG_LEVEL verbose, debug, log, warn, error or fatal log server, machine learning
FRAMELEAF_LOG_FORMAT console or json console server
FRAMELEAF_LOG_REQUESTS Set to false to stop logging a line for every request. The lines then only show at the debug level; server errors are always logged true server
FRAMELEAF_LOG_RETENTION_DAYS How many days of logs the server keeps for Server logs, from 1 to 30 7 server
FRAMELEAF_MEDIA_LOCATION Media folder inside the container. Leave it at the default /data server
FRAMELEAF_CONFIG_FILE Path to a config file inside the container server
FRAMELEAF_HELMET_FILE Path to a JSON file of security header options. true uses the built-in file, false turns it off false server
NO_COLOR Set to true to turn off coloured log output false server, machine learning
CPU_CORES Number of CPU cores available to the server detected server
FRAMELEAF_PROCESS_INVALID_IMAGES When true, make thumbnails for images that fail validation server
FRAMELEAF_TRUSTED_PROXIES Comma-separated addresses or ranges of reverse proxies to trust. Setting it replaces the default Private and link-local addresses; the server itself is always trusted server
FRAMELEAF_IGNORE_MOUNT_CHECK_ERRORS Start even when the storage folder checks fail. Only for troubleshooting server
FRAMELEAF_IMPORT_ROOTS Comma-separated folders administrators may import Google Photos Takeout exports from, besides the built-in Imports folder: ZIP or .tgz files, or an unpacked export server
FRAMELEAF_IMPORTS_HOST_PATH Where the built-in Imports folder is on the server itself, shown to administrators so they know where to copy an export. Manager sets it server
FRAMELEAF_ALLOW_SETUP Set to false to turn off the admin sign-up and start-restore endpoints true server

To choose where your photos are stored, set UPLOAD_LOCATION, not FRAMELEAF_MEDIA_LOCATION. The second is the path inside the container, so a host folder there won’t work.

Every server has an Imports folder, called imports, inside its storage folder. Imports can always read from it, so you only need FRAMELEAF_IMPORT_ROOTS for exports kept somewhere else.

Variable What it does Default Containers
FRAMELEAF_JOB_CAPACITY How many background jobs run at once, from 1 to 32. When set, it wins over the setting in the app Chosen for your server server
FRAMELEAF_SHARP_WORKERS How many thumbnails are made at once, from 1 to 8. More is faster on a server with spare cores and memory 2 server
FRAMELEAF_SHARP_MAX_PIXELS The largest image the server opens, in pixels. Bigger panoramas and scans are skipped instead of using all the memory 200000000 (200 megapixels) server
FRAMELEAF_MEDIA_VALIDATION_TIMEOUT_MS How long the server gives a file check, in milliseconds. Raise it for very large videos on a slow drive 120000 server
FRAMELEAF_RAW_RENDER_TIMEOUT_MS How long the server gives a RAW photo to open, in milliseconds 120000 server

Manager’s Containers page suggests values for these from your server’s cores and memory. For job timing and queues, see Background work.

Variable What it does Default Containers
FRAMELEAF_HOST Address to listen on 0.0.0.0 server, machine learning
FRAMELEAF_PORT Port to listen on 2283 (server), 3003 (machine learning) server, machine learning
Variable What it does Default Containers
DB_URL Full connection string. Replaces the separate values below server
DB_HOSTNAME Database host database server
DB_PORT Database port 5432 server
DB_USERNAME Database user postgres server, database
DB_PASSWORD Database password. Use only letters and numbers postgres server, database
DB_DATABASE_NAME Database name frameleaf server, database
DB_SSL_MODE Database SSL mode server
DB_VECTOR_EXTENSION pgvector only; keep the release default server
DB_SKIP_MIGRATIONS Skip database migrations at startup, for restores false server

DB_USERNAME, DB_PASSWORD and DB_DATABASE_NAME are passed to the database container as POSTGRES_USER, POSTGRES_PASSWORD and POSTGRES_DB. New installations use the database name frameleaf; an existing Frameleaf database keeps the name it was set up with.

DB_URL looks like postgresql://user:password@host:port/database. Use the SSL mode your database requires, with certificate verification for a remote database. When DB_URL is set, DB_HOSTNAME, DB_PORT, DB_USERNAME, DB_PASSWORD and DB_DATABASE_NAME are ignored.

Give the database settings to every server worker. Background queues live in PostgreSQL too, so there’s no Redis or Valkey to run.

Variable What it does Default
FRAMELEAF_CLOUD_URL The Frameleaf Cloud address. Leave it alone; nothing about your library is sent unless you link the server Frameleaf Cloud’s own address
FRAMELEAF_PUSH_URL Overrides the push notification address Frameleaf Cloud publishes. Normally unset
FRAMELEAF_IDENTITY_DIR Folder holding the server’s identity key and the secret that Locked PINs depend on. Must be persistent storage <media>/frameleaf/identity
FRAMELEAF_LINK_TOKEN Single-use token (fll_…) that links the server to your Frameleaf account at startup, without a browser
FRAMELEAF_EDGE_PORT Port for direct remote access 2443
FRAMELEAF_EDGE_BIND Address the direct remote access listener binds to 0.0.0.0
FRAMELEAF_ACME_DIRECTORY_URL Where certificates come from. Only for Let’s Encrypt staging or a test certificate authority Let’s Encrypt
FRAMELEAF_TRUSTED_LAN_CIDRS Extra networks, as comma-separated CIDRs, that count as home besides private ranges
FRAMELEAF_EDGE_SECRET Shared secret between the server and the remote access listener. Set it only when the listener runs in another container, to the same value in both generated each start
FRAMELEAF_LOCAL_URL The server’s address on your home network, offered to visitors on the same network

Create a link token in your Frameleaf account under Servers, then Add server. It works once and expires within an hour. Remove it from .env once the server shows as linked. A malformed token, port or network stops the server at startup. See Frameleaf Cloud account.

Variable What it does Default
FRAMELEAF_RECOVERY_ROOTS Folders Library Care may search for exact copies of missing files, as Label=/path;Label=/path. Only ever read

Each entry is an absolute path inside the container, optionally labelled. A copy found there is copied into library storage before the item is relinked to it.

The web app links to the Frameleaf phone apps in the App Store and on Google Play. These change where those links go.

Variable What it does Default
FRAMELEAF_IOS_APP_URL HTTPS App Store or TestFlight page of the iPhone app Frameleaf in the App Store
FRAMELEAF_ANDROID_STORE_URL HTTPS store listing of the Android app Frameleaf on Google Play

A value that’s set but isn’t an HTTPS address stops the server at startup. The server doesn’t offer Android APK downloads: FRAMELEAF_ANDROID_RELEASE_URL, FRAMELEAF_ANDROID_APP_ID and FRAMELEAF_ANDROID_SIGNING_SHA256 are still accepted in an existing .env, and ignored.

Variable What it does
FRAMELEAF_DOCS_URL HTTPS address of your installation’s documentation
FRAMELEAF_SUPPORT_URL HTTPS address where people get help with your installation
FRAMELEAF_BUG_FEATURE_URL HTTPS address for reporting problems and requesting features
FRAMELEAF_SOURCE_URL HTTPS address of the source code your installation runs

Help, settings and sign-in pages only show these links when they’re set. A value that isn’t an HTTPS address, or that contains a user name or password, stops the server at startup.

Variable What it does
FRAMELEAF_WORKERS_INCLUDE Only run these workers
FRAMELEAF_WORKERS_EXCLUDE Don’t run these workers

See Workers and where jobs run.

Variable What it does Default
FRAMELEAF_SHUTDOWN_GRACE_SECONDS How long running jobs and requests get to finish when the server stops. Jobs still running then go back to waiting 5
FRAMELEAF_SHUTDOWN_DEADLINE_SECONDS When the server exits, whatever is still running. Must be greater than the grace period 9

Both must be positive, and the grace period must end before the deadline, or the server won’t start. Docker kills the container when its stop timeout ends, so stop_grace_period in docker-compose.yml must be longer than the deadline. The supplied Compose files and NAS packages use 10 seconds, which fits the defaults.

These server variables set the starting machine learning settings. Once settings are saved, change them in the web app.

Variable What it does Default
FRAMELEAF_MACHINE_LEARNING_ENABLED Seeds whether machine learning is enabled; false disables the default true
FRAMELEAF_MACHINE_LEARNING_URL Seeds the default library-analysis worker address The release’s internal machine learning service
FRAMELEAF_ML_AUTH_TOKEN Token required by an ML worker. Store the matching token on its processing destination Unset

The machine learning container reads the variables below. Restoration workers have their own settings; see Workers.

Variable What it does Default
MACHINE_LEARNING_MODEL_TTL Seconds of inactivity before a model is unloaded from memory. 0 or less turns this off 300
MACHINE_LEARNING_MODEL_CACHE_MAX_ENTRIES How many models stay loaded at once. Lower it on a server with little memory 32
MACHINE_LEARNING_MODEL_DOWNLOADS Set to false to stop models downloading when they’re needed. Only for a model folder you filled yourself true
MACHINE_LEARNING_MODEL_TTL_POLL_S Seconds between checks of the model TTL 10
MACHINE_LEARNING_CACHE_FOLDER Folder models are downloaded to /cache
MACHINE_LEARNING_MODEL_SOURCE_URL Where smart search, face and text recognition models download from https://models.frameleaf.cloud
MACHINE_LEARNING_MODEL_SOURCE_TOKEN Token sent to a custom model source that needs one. Never logged
MACHINE_LEARNING_REQUEST_THREADS Threads handling requests. Start here when tuning number of CPU cores
MACHINE_LEARNING_MODEL_INTER_OP_THREADS Model operations run in parallel; 0 uses runtime selection 0
MACHINE_LEARNING_MODEL_INTRA_OP_THREADS Threads for each model operation; 0 uses runtime selection 0
MACHINE_LEARNING_WORKERS Worker processes. Each one loads its own copy of the models, so only raise this with plenty of memory 1
MACHINE_LEARNING_HTTP_KEEPALIVE_TIMEOUT_S HTTP keep-alive time in seconds 2
MACHINE_LEARNING_WORKER_TIMEOUT Seconds a worker may be unresponsive before it’s restarted 300 (900 with ROCm)
MACHINE_LEARNING_PRELOAD__CLIP__TEXTUAL Smart search text models to load at startup, comma-separated
MACHINE_LEARNING_PRELOAD__CLIP__VISUAL Smart search image models to load at startup
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__RECOGNITION Face recognition models to load at startup
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__DETECTION Face detection models to load at startup
MACHINE_LEARNING_PRELOAD__OCR__RECOGNITION Text recognition models to load at startup
MACHINE_LEARNING_PRELOAD__OCR__DETECTION Text detection models to load at startup
MACHINE_LEARNING_DEVICE_IDS GPU IDs to use on a multi-GPU machine. Needs MACHINE_LEARNING_WORKERS above 1; each worker gets one device in turn 0
MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITION Faces processed at once none (1 with OpenVINO)
MACHINE_LEARNING_MAX_BATCH_SIZE__OCR Text boxes processed at once 6
MACHINE_LEARNING_MODEL_ARENA Pre-allocates CPU memory to avoid fragmentation true
MACHINE_LEARNING_ANN Use ARM NN acceleration if supported True
MACHINE_LEARNING_ANN_FP16_TURBO Faster, less precise FP16 maths (ARM NN only) False
MACHINE_LEARNING_ANN_TUNING_LEVEL ARM NN GPU tuning: 1 rapid, 2 normal, 3 exhaustive 2
MACHINE_LEARNING_RKNN Use RKNN acceleration if supported True
MACHINE_LEARNING_RKNN_THREADS RKNN runtime threads 1
MACHINE_LEARNING_OPENVINO_PRECISION FP16 for faster, very slightly less exact results on Intel graphics, or FP32 FP32
MACHINE_LEARNING_SEMANTIC_MASK_DEVICE Where Studio’s masks run: cpu, cuda (needs an NVIDIA card) or auto cpu
MACHINE_LEARNING_TRANSCRIPTION_MAX_MEMORY_MB Memory for turning speech in videos into text, in megabytes 1536
FRAMELEAF_STUDIO_WORKER Set to false to stop the worker that lets Studio open and export in the browser. The server reads it too: false there stops the server enrolling the worker true
HF_ENDPOINT Your own model mirror. Also used for AI description and NSFW models
HF_HUB_OFFLINE Set to 1 to stop downloads once you’ve filled the model cache yourself

Searching needs only the smart search text model. If your first searches are slow because uploads are loading the other models at the same moment, preload the image, face and text models too, if you have the memory.

Smart search, face and text recognition models download from MACHINE_LEARNING_MODEL_SOURCE_URL if it’s set, otherwise from HF_ENDPOINT if that’s set, otherwise from Frameleaf’s model mirror at https://models.frameleaf.cloud. The container logs which source it uses at startup. The source uses the Hugging Face folder layout, so you can point it at your own mirror or an offline copy. If the source doesn’t have a model you choose, loading fails with an error naming the model and the source; it never falls back to another host. A Hugging Face token (HF_TOKEN) is only sent to huggingface.co.

AI description and NSFW detection models download from huggingface.co unless you set HF_ENDPOINT. To keep them off huggingface.co, point HF_ENDPOINT at your own mirror, or fill the model cache yourself and set HF_HUB_OFFLINE=1.

No usage statistics are sent to any host.

DB_HOSTNAME, DB_DATABASE_NAME, DB_USERNAME, DB_PASSWORD, DB_URL can be read from files instead, using Docker secrets or systemd credentials. Either:

  • add _FILE to the name, for example DB_PASSWORD_FILE, and set it to the path of a file that contains the value, or
  • set CREDENTIALS_DIRECTORY to a folder of files named after the variables. With Docker secrets, CREDENTIALS_DIRECTORY=/run/secrets uses every secret present.

Frameleaf sends no telemetry, and older telemetry options have no effect. You can turn on local metrics for your own Prometheus to collect; they’re off by default and stay on your server unless you collect them. See Local metrics.

Variable What it does Default Containers
FRAMELEAF_METRICS_ENABLED Set to true to offer metrics for the server and background work false server
FRAMELEAF_METRICS_PORT The server’s metrics port. Background work uses the next port 8081 server
FRAMELEAF_METRICS_TOKEN A bearer token Prometheus must send to read the server’s metrics server
FRAMELEAF_ML_METRICS_ENABLED Set to true to offer machine learning metrics at /metrics on its usual port false machine learning

For health checks and logs, see Monitoring.

Manager writes some variables itself, so the stack keeps working after every update: the database connection (DB_* and POSTGRES_*), FRAMELEAF_MEDIA_LOCATION, FRAMELEAF_CONFIG_FILE and everything starting with FRAMELEAF_MANAGER_. Its Containers page refuses those names and lists each one with its value under Set by Manager. The Manager container’s own variables, such as MANAGER_DATA, MANAGER_ORIGIN and MANAGER_EXTRA_FOLDERS, are covered in Install with Frameleaf Manager and the NAS guides.

Photographers take card payments by connecting their studio’s own Stripe account in Clients under Payments, with no variables to set. See Payments, payment links and bookings. The variables below are an older way for a server to take client gallery order payments for one studio, and are only needed by servers that already use them.

Variable What it does
FRAMELEAF_CLIENTS_STRIPE_STUDIO_OWNER_ID The ID of the one Frameleaf account whose orders use the checkout. Other accounts keep recording payments by hand.
FRAMELEAF_CLIENTS_STRIPE_SECRET_KEY The Stripe secret key, starting sk_test_ or sk_live_.
FRAMELEAF_CLIENTS_STRIPE_WEBHOOK_SECRET The signing secret of the Stripe webhook that tells Frameleaf about payments.
FRAMELEAF_CLIENTS_CHECKOUT_SUCCESS_URL The https:// page a client returns to after paying.
FRAMELEAF_CLIENTS_CHECKOUT_CANCEL_URL The https:// page a client returns to if they leave the checkout.

These replace the PHOTOGRAPHY_STRIPE_* and PHOTOGRAPHY_CHECKOUT_* names. The old names still work for one more release, and startup warns while they’re set: rename each one by replacing PHOTOGRAPHY_ with FRAMELEAF_CLIENTS_, or better, connect the studio’s account under Payments and remove them.

With all five set, a client sees Pay securely on an accepted order and pays on Stripe’s hosted checkout page; Frameleaf marks the order paid when Stripe confirms it. In Stripe, point the webhook at https://your-server/api/photography/payments/stripe, so the server must be reachable from the internet at that address. Send it the checkout session events (completed, async payment succeeded, async payment failed and expired), charge.refunded and charge.dispute.created. Treat the two secrets like passwords, and restart the server after changing any of these.

Use the FRAMELEAF_ names above. Supported older names still work, and startup tells you the new name to switch to. If both names of a setting are set to different values, the server won’t start, so keep one value under the current name. To bring a library from another application, import it rather than reusing its database.