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.
The basics
Section titled “The basics”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.
General
Section titled “General”| 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.
Speed and limits
Section titled “Speed and limits”| 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 |
Database
Section titled “Database”| 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.
Frameleaf Cloud
Section titled “Frameleaf Cloud”| 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.
Library Care
Section titled “Library Care”| 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.
App links
Section titled “App links”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.
Help links
Section titled “Help links”| 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.
Workers
Section titled “Workers”| 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.
Stopping
Section titled “Stopping”| 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.
Machine learning
Section titled “Machine learning”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.
Where models come from
Section titled “Where models come from”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.
Keep secrets in files
Section titled “Keep secrets in files”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
_FILEto the name, for exampleDB_PASSWORD_FILE, and set it to the path of a file that contains the value, or - set
CREDENTIALS_DIRECTORYto a folder of files named after the variables. With Docker secrets,CREDENTIALS_DIRECTORY=/run/secretsuses every secret present.
No telemetry
Section titled “No telemetry”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.
Set by Manager
Section titled “Set by Manager”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.
Online checkout for photographers
Section titled “Online checkout for photographers”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.
Existing variable names
Section titled “Existing variable names”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.
Feature-specific settings
Section titled “Feature-specific settings”- iCloud Photos Sync server setup covers the on/off switch, where iCloud files are kept, and the optional server-wide limits.
- Library Care recovery explains recovery mounts.
- Workers covers restoration workers.
- Buddy backup covers its availability control and recovery.
- Locked encryption covers
FRAMELEAF_LOCKED_TMP,FRAMELEAF_LOCKED_TMP_ALLOW_DISKand theshm_sizethe server container needs.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.