# Config file

Source: https://frameleaf.app/docs/admin/config-file/

Keep your server's settings in a file on disk instead of changing them in the [Command Center](https://frameleaf.app/docs/admin/command-center/). It's ideal if you manage your server as code, want version history for your settings, or want the same settings on several servers.

:::caution[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 **Advanced**, then **Copy settings**, and choose **Save to a file** or **Copy as text**. Keep it as 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.

:::note[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:

```bash
# .env
FRAMELEAF_CONFIG_FILE=/config/frameleaf-config.json
```

```yaml
# docker-compose.yml
services:
  frameleaf-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.

:::note[With Frameleaf Manager]
Manager keeps `FRAMELEAF_CONFIG_FILE` for its own use, so it can't be added on the **Containers** page. On a Manager installation, change settings in the Command Center, and use **Copy settings** to keep a copy or load one from another server.
:::

## What the file looks like

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

```json
{
  "backup": {
    "database": { "enabled": true, "cronExpression": "0 02 * * *", "keepLastAmount": 14 },
    "schedule": { "cronExpression": "" }
  },
  "ffmpeg": {
    "transcode": "required",
    "targetVideoCodec": "h264",
    "targetAudioCodec": "aac",
    "targetResolution": "1080",
    "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://frameleaf-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,
    "reprocessUnfinished": true,
    "clusterNewFaces": true,
    "stopTime": "06:00",
    "days": [0, 1, 2, 3, 4, 5, 6],
    "emptyTrash": true,
    "quietHours": true,
    "weeklyDay": 0,
    "steps": { "cleanup": "nightly", "folders": "nightly", "icloud": "nightly", "fileChecks": "nightly" }
  },
  "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": "Sign in with your provider"
  },
  "passwordLogin": { "enabled": true },
  "reverseGeocoding": { "enabled": true },
  "server": {
    "name": "",
    "externalDomain": "",
    "loginPageMessage": "",
    "timeZone": "",
    "publicUsers": true,
    "lanDiscovery": true
  },
  "storageTemplate": {
    "enabled": false,
    "hashVerificationEnabled": true,
    "template": "{{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}"
  },
  "templates": {
    "email": {
      "welcomeTemplate": "",
      "albumInviteTemplate": "",
      "albumUpdateTemplate": "",
      "invitationFirstLine": "",
      "showBranding": true
    }
  },
  "storageWarning": { "percent": 90 },
  "theme": { "customCss": "", "customCssEnabled": true },
  "trash": { "enabled": true, "days": 30 },
  "user": { "deleteDelay": 7 }
}
```

The server has more settings than this, including job concurrency (`job`), integrity checks (`integrityChecks`), who must use a passkey or two-step (`signInPolicy`), connected apps, smart albums, editing, iCloud Photos and Frameleaf Cloud. Save a copy from [Copy settings](https://frameleaf.app/docs/admin/system-settings/#copy-settings) to get the full list for your version.

## Top-level keys

| Key | What it covers | See |
| --- | --- | --- |
| `backup` | Database snapshots, how many to keep, and the one schedule every backup follows | [Backup and restore](https://frameleaf.app/docs/admin/backup-and-restore/#automatic-database-backups) |
| `ffmpeg` | Video playback copies and hardware encoding | [System settings](https://frameleaf.app/docs/admin/system-settings/#video-playback-copies) |
| `image` | Thumbnails, previews and full-size images | [System settings](https://frameleaf.app/docs/admin/system-settings/#image-previews) |
| `job` | How many jobs run at once | [Background work](https://frameleaf.app/docs/admin/jobs/#concurrency) |
| `library` | External library scans and watching | [External libraries](https://frameleaf.app/docs/admin/external-libraries/) |
| `logging` | Log level | |
| `machineLearning` | Machine learning addresses, models and features | [System settings](https://frameleaf.app/docs/admin/system-settings/#search--intelligence) |
| `map`, `reverseGeocoding` | Map styles and place names | |
| `metadata` | Importing faces from file metadata | |
| `newVersionCheck` | Update checks | [Upgrading](https://frameleaf.app/docs/admin/upgrading/) |
| `nightlyTasks` | The overnight schedule: start and stop time, days, each step's timing, and quiet hours (`quietHours`) | [Overnight schedule](https://frameleaf.app/docs/admin/system-settings/#overnight-schedule) |
| `notifications`, `templates` | Email delivery and email templates | [Email](https://frameleaf.app/docs/admin/email/) |
| `oauth`, `passwordLogin`, `signInPolicy` | Sign-in methods, and who must use a passkey or two-step | [Sign-in and OAuth](https://frameleaf.app/docs/admin/sign-in-and-oauth/) |
| `server` | Server name, public URL, time zone, welcome message, discovery | [System settings](https://frameleaf.app/docs/admin/system-settings/#server-name--welcome) |
| `storageWarning` | How full a drive gets before Frameleaf warns you, as a percentage | |
| `storageTemplate` | Folder and file naming on disk | [Storage template](https://frameleaf.app/docs/admin/storage-template/) |
| `theme` | Custom CSS | |
| `trash`, `user` | Trash retention and account delete delay | |
