# Environment variables

Source: https://frameleaf.app/docs/admin/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](https://frameleaf.app/docs/admin/manager/#settings) page, which keeps them through updates and lists them by what they do.

:::caution
After changing `.env`, recreate the containers with `docker compose up -d`. A plain restart doesn't pick up the new values. If a change still doesn't show, run `docker compose up -d --force-recreate`.
:::

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](https://frameleaf.app/docs/admin/workers/), give each the variables it needs.

:::note[Machine learning has its own file]
In a manual installation, `.env` goes to the server only, so the server's passwords stay out of the machine learning container. Put variables for the machine learning container in an optional `.env.ml` file next to `.env`. In Manager, add them on the **Machine learning** tab of **Containers**.
:::

## 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

| 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**](https://frameleaf.app/docs/admin/monitoring/#read-the-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](https://frameleaf.app/docs/admin/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](https://frameleaf.app/docs/admin/reverse-proxy/) 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](https://frameleaf.app/docs/migrate/google-photos/) 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

| 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](https://frameleaf.app/docs/admin/manager/#suggested-for-this-server) page suggests values for these from your server's cores and memory. For job timing and queues, see [Background work](https://frameleaf.app/docs/admin/jobs/).

:::caution[HTTP-only servers]
If you turn on the built-in security headers (`FRAMELEAF_HELMET_FILE=true`), they tell browsers to upgrade every request to HTTPS, which breaks a server reached over plain HTTP. Use your own helmet file with `"upgrade-insecure-requests": null` if you can't use HTTPS.
:::

## Ports

| 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

| 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

| 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](https://frameleaf.app/docs/using/locked-encryption/#the-servers-pin-secret). 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 | |

:::danger[Keep the identity key]
If the identity key is lost, the server gets a new identity, and every link and licence tied to the old one stops working until you link and activate again.
:::

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](https://frameleaf.app/docs/cloud/account/#link-a-server-with-no-browser).

## Library Care

| Variable | What it does | Default |
| --- | --- | --- |
| `FRAMELEAF_RECOVERY_ROOTS` | Folders [Library Care](https://frameleaf.app/docs/using/library-care/#for-administrators) 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

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

| 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

| 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](https://frameleaf.app/docs/admin/workers/).

## 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

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](https://frameleaf.app/docs/admin/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

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

`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.

## 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](https://frameleaf.app/docs/admin/monitoring/#local-metrics-with-prometheus-and-grafana).

| 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](https://frameleaf.app/docs/admin/monitoring/).

## 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](https://frameleaf.app/docs/admin/manager/#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](https://frameleaf.app/docs/start/install/) and the NAS guides.

## 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](https://frameleaf.app/docs/using/clients-payments/). The variables below are an older way for a server to take [client gallery](https://frameleaf.app/docs/using/client-galleries/) 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

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](https://frameleaf.app/docs/migrate/from-another-library/) rather than reusing its database.

## Feature-specific settings

- [iCloud Photos Sync server setup](https://frameleaf.app/docs/migrate/icloud-photos-server-setup/) covers the on/off switch, where iCloud files are kept, and the optional server-wide limits.
- [Library Care recovery](https://frameleaf.app/docs/admin/media-recovery/) explains recovery mounts.
- [Workers](https://frameleaf.app/docs/admin/workers/) covers restoration workers.
- [Buddy backup](https://frameleaf.app/docs/cloud/buddy-backup/) covers its availability control and recovery.
- [Locked encryption](https://frameleaf.app/docs/using/locked-encryption/#memory-for-working-copies) covers `FRAMELEAF_LOCKED_TMP`, `FRAMELEAF_LOCKED_TMP_ALLOW_DISK` and the `shm_size` the server container needs.
