Config file

Instead of changing settings in the Command Center, you can keep them in a file on disk. This suits people who manage their server as code, or want the same settings on several servers.

The file takes over

Once FRAMELEAF_CONFIG_FILE is set, the settings it manages can’t be edited in the web app. The file doesn’t need every key; anything you leave out keeps its default.

1. Create the file

The easiest start is to copy your current settings: open Settings, then Server & updates, then Configuration transfer, and choose Copy to clipboard or Export as JSON. Paste it into a file such as frameleaf-config.json next to your docker-compose.yml, and remove anything you don’t want to manage from the file.

JSON and YAML are both supported.

Credentials

Exports never include the OAuth client secret or the SMTP password. If you manage settings with a file, add those values to the file yourself (oauth.clientSecret and notifications.smtp.transport.password). While a config file is in use, credentials come from the file and can’t be replaced in the Command Center.

2. Tell the server where it is

Set FRAMELEAF_CONFIG_FILE in your .env to the file’s path inside the container, then mount the file at that path. Reusing the variable in docker-compose.yml keeps the two in step:

.env

FRAMELEAF_CONFIG_FILE=/config/frameleaf-config.json

docker-compose.yml

services:
  immich-server:
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - ./frameleaf-config.json:${FRAMELEAF_CONFIG_FILE}:ro

Then run docker compose up -d.

UPLOAD_LOCATION and DB_DATA_LOCATION are paths on the host, but FRAMELEAF_CONFIG_FILE is a path inside the container.

If you run separate worker containers, mount the file and set the variable on them too. The older IMMICH_CONFIG_FILE name still works; see Environment variables.

What the file looks like

Here is a shortened example with common settings at their defaults:

{
  "backup": {
    "database": { "enabled": true, "cronExpression": "0 02 * * *", "keepLastAmount": 14 }
  },
  "ffmpeg": {
    "transcode": "required",
    "targetVideoCodec": "h264",
    "targetAudioCodec": "aac",
    "targetResolution": "720",
    "acceptedVideoCodecs": ["h264"],
    "acceptedAudioCodecs": ["aac", "mp3", "opus"],
    "acceptedContainers": ["mov", "ogg", "webm"],
    "preset": "ultrafast",
    "crf": 23,
    "maxBitrate": "0",
    "accel": "disabled",
    "accelDecode": true
  },
  "image": {
    "colorspace": "p3",
    "extractEmbedded": false,
    "thumbnail": { "format": "webp", "size": 250, "quality": 80 },
    "preview": { "format": "jpeg", "size": 1440, "quality": 80 },
    "fullsize": { "enabled": false, "format": "jpeg", "quality": 80 }
  },
  "library": {
    "scan": { "enabled": true, "cronExpression": "0 0 * * *" },
    "watch": { "enabled": false }
  },
  "logging": { "enabled": true, "level": "log" },
  "machineLearning": {
    "enabled": true,
    "urls": ["http://immich-machine-learning:3003"],
    "clip": { "enabled": true, "modelName": "ViT-B-16-SigLIP-384__webli" },
    "duplicateDetection": { "enabled": true, "maxDistance": 0.01 },
    "facialRecognition": {
      "enabled": true,
      "modelName": "buffalo_l",
      "minScore": 0.7,
      "maxDistance": 0.5,
      "minFaces": 3
    }
  },
  "map": {
    "enabled": true,
    "lightStyle": "https://tiles.frameleaf.cloud/v1/style/light.json",
    "darkStyle": "https://tiles.frameleaf.cloud/v1/style/dark.json"
  },
  "newVersionCheck": { "enabled": false, "channel": "stable", "frequency": "daily" },
  "nightlyTasks": {
    "startTime": "00:00",
    "databaseCleanup": true,
    "generateMemories": true,
    "syncQuotaUsage": true,
    "missingThumbnails": true,
    "clusterNewFaces": true
  },
  "notifications": {
    "smtp": {
      "enabled": false,
      "from": "",
      "replyTo": "",
      "transport": {
        "host": "",
        "port": 587,
        "secure": false,
        "ignoreCert": false,
        "username": "",
        "password": ""
      }
    }
  },
  "oauth": {
    "enabled": false,
    "issuerUrl": "",
    "clientId": "",
    "clientSecret": "",
    "scope": "openid email profile",
    "autoRegister": true,
    "autoLaunch": false,
    "buttonText": "Login with OAuth"
  },
  "passwordLogin": { "enabled": true },
  "physicalDeduplication": { "enabled": false, "masterUserId": null },
  "reverseGeocoding": { "enabled": true },
  "server": {
    "name": "",
    "externalDomain": "",
    "loginPageMessage": "",
    "publicUsers": true,
    "lanDiscovery": true
  },
  "storageTemplate": {
    "enabled": false,
    "hashVerificationEnabled": true,
    "template": "{{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}"
  },
  "templates": {
    "email": { "welcomeTemplate": "", "albumInviteTemplate": "", "albumUpdateTemplate": "" }
  },
  "theme": { "customCss": "" },
  "trash": { "enabled": true, "days": 30 },
  "user": { "deleteDelay": 7 }
}

The server has more settings than this, including job concurrency (job), integrity checks (integrityChecks), smart albums and Frameleaf Cloud. Exporting from Configuration transfer gives you the full, current list for your version.

Top-level keys

Key	What it covers	See
backup	Database backup schedule and how many to keep	Backup and restore
ffmpeg	Video playback copies and hardware encoding	System settings
image	Thumbnails, previews and full-size images	System settings
job	How many of each job run at once	System settings
library	External library scans and watching	External libraries
logging	Log level
machineLearning	Machine learning URLs, models and features	System settings
map, reverseGeocoding	Map styles and place names
metadata	Importing faces from file metadata
newVersionCheck	Update checks	Upgrading
nightlyTasks	Nightly jobs and their start time
notifications, templates	Email delivery and email templates	Email
oauth, passwordLogin	Sign-in methods	Sign-in and OAuth
physicalDeduplication	Storing identical files once	Physical deduplication
server	Server name, public URL, welcome message, discovery	System settings
storageTemplate	Folder and file naming on disk	Storage template
theme	Custom CSS
trash, user	Trash retention and account delete delay