# System settings

Source: https://frameleaf.app/docs/admin/system-settings/

Every server-wide setting lives in one place, the [Command Center](https://frameleaf.app/docs/admin/command-center/), and you can review all your changes before you save them. Select **Settings** in the sidebar, then open the area you need. Only administrators see these sections; everyone else sees their own preferences.

This page walks through the server settings area by area. Each setting also has a key in the [config file](https://frameleaf.app/docs/admin/config-file/), shown in brackets where it helps.

## Saving changes

Every settings page edits one shared draft. You can change things on several pages and save them together.

- **Review changes** lists every change with its page, the saved value and the new value. **Save changes** saves them all at once.
- **Discard** returns every page to the saved settings. **Reset this page** puts that page's defaults into the draft; they're applied when you save.
- Pages with unsaved changes are marked in the settings list. Leaving with unsaved changes asks whether to keep editing or discard them.
- Reloading the tab brings the draft back, except passwords, keys and addresses that contain credentials. Those are never stored in the browser.
- If another administrator saves while you're editing, your draft is kept. Changes to different settings are carried onto theirs and you save again. If you both changed the same setting, the page shows the saved value and yours side by side: keep your changes on top of the latest settings, or discard your draft and load the latest.
- Actions that do something straight away, such as sending a test email or disconnecting everyone from a sign-in provider, run on their own. Sending a test email also saves the email settings, and nothing else.

### Copy settings to a file

To keep a copy of the saved settings or load them on another server, open **Server & updates**, then **Advanced**, then **Copy settings**. See [Copy settings](#copy-settings). If you'd rather manage settings from a file on disk, see [Config file](https://frameleaf.app/docs/admin/config-file/).

### Change history

**Change history** lists every change saved from the settings pages, including credential changes, newest first. Each entry shows the administrator who saved it, the time, and each setting before and after. It's kept on the server, so every administrator sees the same list of the latest 50 saves. Credentials only ever appear as replaced or cleared.

## Server credentials

The OAuth client secret and the SMTP password are **write-only**. Their rows show **Stored** or **Not set**, never the value itself.

- **Replace credential** opens a dialog with a single field. The value is sent once, checked like any other change (a new SMTP password is tested against the mail server, for example), and cleared from the dialog when it closes.
- **Clear** removes the stored value after you confirm.
- Saving any other setting, copying, exporting or importing never carries a credential.
- A stored secret never follows a change of server. Saving a different mail server host or username clears the SMTP password, and saving a different OAuth issuer URL clears the client secret. Replace the credential for the new server afterwards.
- **Send a test email** uses the stored SMTP password as long as the server, port, username and security settings on the page match the saved ones.
- Every replacement or removal is written to the server log by credential name and administrator, never by value.

:::tip[Changing mail server]
If email is turned on and the new mail server needs a password: turn email off, save the new server, replace the password, then turn email on again.
:::

Scripts can use `GET /api/admin/config/credentials` to see which credentials are stored, and `PUT` or `DELETE /api/admin/config/credentials/{name}` to replace or clear one. While a [config file](https://frameleaf.app/docs/admin/config-file/) manages the settings, credentials come from that file and can't be changed in the Command Center.

## Storage & originals

How full the drive is, how original files are named and arranged on disk, and how long deleted photos and deleted accounts are kept.

The area opens on a status page. It says how much space your photos use and how much is free, such as "Your photos use 1.2 TB. 640 GB is free.", and once a month of growth has been counted, roughly how long the room will last. Below it:

- **Before the disk fills up** has **Warn me when the disk is nearly full** (`storageWarning.percent`, 90). Choose **At 85% (recommended)**, **At 95%** or **Off**. You're told under **What needs your attention** when the drive passes that mark. It counts everything on the drive, not only your photos. **Off** still warns once less than 10 GB is left.
- **Where photos are kept** opens **Folder layout** and **Move or export**.
- **When things are deleted** opens **Deleted items** and **Your Trash**.
- **Identical files are stored once** says how much space that saves, with **Open Duplicates**. The server's owner also sees **Unused files** with how many files are waiting. See [Identical files](https://frameleaf.app/docs/admin/physical-deduplication/).

### Folder layout

- **Sort originals into folders** (`storageTemplate.enabled`, off). Off, originals are kept under the folders Frameleaf chooses for them. On, each new original is named and filed by the layout you pick. See [Folder layout](https://frameleaf.app/docs/admin/storage-template/).
- The layout cards: **By year, then day (recommended)**, **By year, then month**, **By year, then month name**, **By year**, and **Custom…** for your own pattern. Each card shows a sample path. See [Layouts](https://frameleaf.app/docs/admin/storage-template/#layouts).
- Under the cards, a preview sentence shows where a sample photo goes: "A photo you take on 15 June 2024 will be saved as:" and the path, starting with your own storage label, or your account ID if you have none.

- **Copies are checked before the old file is removed** is a promise, not a switch: "When Frameleaf moves a photo to another drive, the old file stays until the new copy matches it exactly." A move also never replaces another file. See [How files are moved](https://frameleaf.app/docs/admin/storage-template/#how-files-are-moved).

**Advanced: custom pattern** holds **Custom pattern** (`storageTemplate.template`, default `{{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}`). Under it, every tag is listed by kind with what it becomes for a sample photo, with **Example patterns**; they're the same as the [full list](https://frameleaf.app/docs/admin/storage-template/#variables). File endings are always written in small letters.

`storageTemplate.hashVerificationEnabled` is retired. It used to be the **Check files after moving them** switch. Every copy is now checked, so the setting no longer does anything. It stays in the [config file](https://frameleaf.app/docs/admin/config-file/) and the API so older files and scripts keep working, and **Review changes**, **Change history** and **Copy settings** name it **Old copy-check switch (no longer used)**.

:::note[Existing photos]
A new layout only applies to new uploads. Once it's saved the page says "The N photos and videos you already have stay where they are until you re-file them." **Re-file existing photos…** moves them in the background. It's the **Sort originals into folders** job in [Background work](https://frameleaf.app/docs/admin/jobs/#the-queues).
:::

### Deleted items

How long deleted photos and deleted accounts can be brought back. The page starts with the answer, such as **Deleted photos can be brought back for 30 days**, and how many photos and videos are waiting in people's Trash.

**Deleted photos and videos.** Each person restores or removes their own photos in their own Trash; this sets how long everyone has.

- **Keep deleted photos for** (`trash.days`, 30). Choose **7 days**, **30 days (recommended)**, **60 days**, **90 days**, **1 year** or **Another length…**. The line under it gives the date a photo deleted today could still be brought back.
- The Trash itself is `trash.enabled` (on). While it's off, the page says **The Trash is off. Deleting a photo removes it at once.**, and nothing deleted can be brought back. Choose a length to turn it on again.
- If you choose a shorter time, the page warns how many photos already in the Trash are older than that. They're removed for good that night.

**Deleted accounts.** When you delete someone's account in **Users**, it and its photos are kept for a while in case you change your mind.

- **Keep a deleted account for** (`user.deleteDelay`, 7 days). Choose **1 day**, **7 days (recommended)**, **30 days** or **Another length…**. A shorter time also applies to accounts that are already waiting.
- Accounts waiting to be removed are listed with **Restore**. See [Delete an account](https://frameleaf.app/docs/admin/users/#delete-an-account).

**Emptied by the overnight tidy-up.** Photos and accounts past their time are removed when the **Empty Trash and tidy up** step of the [overnight schedule](#overnight-schedule) runs, not at the minute their time runs out. While that step is switched off, nothing is removed and no space comes back; the page then says **The Trash is not being emptied**.

**Waiting in the Trash now** shows how much each person has waiting. You never see the photos themselves. See [Trash](https://frameleaf.app/docs/using/trash/#how-long-items-stay).

### Move or export

Nothing to set here. **What do you want to do?** offers **Move to a new Frameleaf server**, **Move my photos to a bigger drive** and **Take a copy out**, and says what will happen for each. Nothing on the page moves or deletes anything.

- A move is done in Frameleaf Manager, so it can stop and start Frameleaf safely while it works: **Open Frameleaf Manager**. On a server without Manager, the page offers restoring your backup on the new server or drive instead.
- **Advanced: move with the command-line tool** is a step-by-step checklist for moving between two servers from another computer, one person at a time.

See [Move to a new server](https://frameleaf.app/docs/admin/move-to-a-new-server/) and [Move data to another drive](https://frameleaf.app/docs/admin/move-data-to-another-drive/).

## Import & export

Bring photos in from other places, and take a copy out. There's nothing to set for the whole server here: the page starts with how your imports are going, such as **No imports running** or how far a Google Photos import has got, then lists the ways in and out.

- **Bring photos in from…**: **Google Photos** ([Import from Google Photos](https://frameleaf.app/docs/migrate/google-photos/)), **iCloud Photos** ([iCloud Photos](https://frameleaf.app/docs/migrate/icloud-photos/)), **A folder on this server** ([Folders of photos](https://frameleaf.app/docs/admin/external-libraries/)) and **Your phone** ([Mobile apps](https://frameleaf.app/docs/using/mobile-apps/)). Each one checks what you already have, so nothing is added twice.
- **Take a copy out**: **Export a copy** ([Preservation](https://frameleaf.app/docs/using/preservation/)) and **Move to another server or drive** ([Move or export](#move-or-export)).
- **Looking for backups?** opens **Backup**, below. Backup keeps a second copy of your library up to date by itself; an exported copy is one you make by hand.

## Backup

**Backup** is an area of its own, under **Overview** and **Library analytics**. One screen answers "am I protected?" and has three tabs, **Overview**, **Schedule** and **Restore**. The Overview opens on the state of your backups (**Your library is backed up**, **Backing up now**, **Your first backup hasn't finished yet**, **Your photos have no backup away from home**, or how many backups need attention), then **Where your backups are kept**: each place keeps its own copy, so losing one never costs you the others. **On this server** holds library data only; **Buddy Backup** and **Cloud Backup** hold photos, videos and library data, and are set up under [Frameleaf Cloud](#frameleaf-cloud). **Restore** is covered in [Backup and restore](https://frameleaf.app/docs/admin/backup-and-restore/#restore-a-database-backup).

#### Schedule

**When backups run** is one schedule for every backup. They run one after another, never at the same time. Choosing a schedule writes `backup.schedule.cronExpression`, and keeps the snapshot's own time (`backup.database.cronExpression`) and Cloud Backup's in step with it. It is empty until it is first chosen; until then the snapshot's own time, 2 am, is the schedule in force.

- **Back up**: **Every day**, **On chosen days** or **Every few hours**.
- **On** (for chosen days): pick one day or several. Choosing all seven is simply every day.
- **How often** (for every few hours): **Every 2 hours**, **3**, **4**, **6**, **8** or **12 hours**, counted from midnight on this server's clock.
- **Start at** (for every day or chosen days): a time of day on this server's clock. The page says what that is where you are. Night is best: backups use your disk and internet.

Backups have a start time and no stop time: each one carries on until it has finished, and the next run waits for it. **What will happen** says the schedule back as a sentence and lists **The order backups run in**: the snapshot on this server goes first, then Buddy Backup, then Cloud Backup, each starting when the one before it finishes. A place that is switched off is left out, and a backup that can't run doesn't hold up the next. The first backup of a large library takes longer. If it is still going when the next start time comes, the next run begins as soon as it ends.

:::note[This server has a custom schedule]
A schedule set in the config file that is not one of the choices above is kept as it is, and the page says so. Choosing how often to back up replaces it.
:::

#### On this server

A snapshot holds your albums, people, edits and settings. It's kept on this server, so it protects against mistakes, not against losing the server. Use Cloud Backup or Buddy Backup for your photos and videos.

- **Take a snapshot with every backup** (`backup.database.enabled`, on). It goes first and takes a minute or two.
- **Keep the last** (`backup.database.keepLastAmount`, 14 snapshots). Older snapshots are removed only after a new one succeeds.
- **Take a snapshot now** makes one straight away, outside the schedule.
- **Saved snapshots** lists them: download one to keep elsewhere, or take the library data back to it. Restoring asks you to confirm first.

See [Automatic database backups](https://frameleaf.app/docs/admin/backup-and-restore/#automatic-database-backups) for where the files are and how to restore one by hand.

## Search & intelligence

Everything Frameleaf works out about your photos on its own: finding them by describing them, recognising people, reading text, writing captions and tags, suggesting photos to lock, and building albums that fill themselves. The work runs on this server, or on another computer you choose in **Where work runs**.

The area opens on a status page, then has one page per feature. Each page starts with a plain choice, and keeps the numbers behind it under **Advanced**, so you can pick a preset without knowing the numbers, or set your own. When a choice is one of the presets, the page names it; when you have set your own numbers, it says **Custom**.

### Search and recognition

The status at the top says whether everything is on, off or paused, and how many photos are still waiting to be read. **Open Computers** takes you to the computers that do the work; **See what's waiting** opens Background work.

**Search and recognition** (`machineLearning.enabled`, on) is one switch for every feature below. Turning it off keeps everything that has already been read: search, people, text and captions stay as they are, and nothing new is read. Turning it back on carries on from there.

**Where this work runs** shows which computer does recognition. By default it's this server; **Where work runs** lets you send each kind of work to another computer. See [Workers and where jobs run](https://frameleaf.app/docs/admin/workers/).

**Runs in the overnight schedule** tells you how the work is paced: new photos are read soon after they arrive, and reading a whole library again waits for the night. The night is set in **Overnight schedule**; see [Jobs and queues](https://frameleaf.app/docs/admin/jobs/).

**Features** lists the six features with their state: **Ready**, **Off** (what was read is kept), **Paused** (waiting for the computer), or a count of photos still being read. Each one can be turned off by itself.

<span id="advanced-the-helper-programs-address"></span>

#### Advanced: the computer’s address

Recognition runs on this server or on another computer. Frameleaf checks that it is answering and waits a short time for each reply.

- **Address** (`machineLearning.urls`, `http://frameleaf-machine-learning:3003`) is where the computer answers. **Add an address** adds a second one, tried when the first doesn't answer; addresses are tried in order. A new address is used once you save. To run recognition on a more powerful computer, see [Remote machine learning](https://frameleaf.app/docs/admin/remote-machine-learning/).
- **Check that it is answering** (`machineLearning.availabilityChecks.enabled`, on) makes Frameleaf stop sending work to an address that doesn't answer, and try it again later.
- **Checked every** (`machineLearning.availabilityChecks.interval`, 30 seconds) is how often each address is checked.
- **Waits for a reply** (`machineLearning.availabilityChecks.timeout`, 2 seconds) is how long a check waits before the address counts as not answering.

### Visual search

Finds photos and videos by describing them, like "dog on a beach". Smart albums, suggested tags and look-alike duplicates all use the same reading of each photo, so they need Visual search on. See [Search](https://frameleaf.app/docs/using/search/) for how to search, and [Choose a smart search model](https://frameleaf.app/docs/using/search-models/) for the models.

**Search by describing a photo** (`machineLearning.clip.enabled`, on). Off, you can still search by date, place, person, album and file name, but look-alike photos can't be found and no tags are suggested.

**Search quality** (`machineLearning.clip.modelName`, `ViT-B-16-SigLIP-384__webli`) is a slider of the search models Frameleaf publishes, from lighter to heavier: `ViT-B-32__openai`, `ViT-B-16-SigLIP-384__webli` and `ViT-SO400M-16-SigLIP2-384__webli`. A heavier model understands unusual descriptions and other languages better, and is slower. The band under each stop says where it runs: **Processor**, **Your GPU** (as the last [graphics card check](https://frameleaf.app/docs/admin/hardware-acceleration/#check-your-hardware) found it) or **Cloud**. A Cloud stop keeps this server's model and sends the work to Frameleaf Cloud; see [Search and faces on Frameleaf Cloud](https://frameleaf.app/docs/admin/workers/#search-and-faces-on-frameleaf-cloud).

:::caution[Changing the search model reads your whole library again]
When you move the slider, the page says how many photos and videos will be read again and roughly how long that takes, and offers **Save and start tonight** or **Save and start now**. The old search results are cleared when you save, so describing a photo finds nothing until the photos are read again. Searching by date, place, person and file name keeps working, and your albums, tags and captions are not touched.
:::

**Advanced: use your own model** holds **Hugging Face model**. A "model" is the trained program that turns photos and words into something that can be compared. To use one that isn't on the slider, enter its full name from Hugging Face, like `organisation/model-name`. Frameleaf checks its files and settings before anything is read again. While your own model is in use, the page names it; empty the box to go back to the slider.

#### Ask about your photos

**Answer questions about your photos** (`localFeatures.askSearch.enabled`, on) lets people ask things like "when did we last go camping?" from the Search page. Answers only ever include photos the person asking is allowed to see. **Advanced: how many answers** sets **Most answers shown** (`localFeatures.askSearch.maxResults`, 100), from 1 to 1,000. See [Ask about your photos](https://frameleaf.app/docs/using/search/#ask-about-your-photos).

#### Frameleaf Assistant

- **Use Frameleaf Assistant in search** (`localFeatures.assistant.enabled`, on). A question typed in search gets matching photos, each with a line saying why it matched. Classic search stays one tap away.
- **Read questions with a language model** (`localFeatures.assistant.planner`, off). When a planner model is installed on this server or a computer at home, it reads each question first. Without one, simple search rules answer.
- **Advanced: how many answers** sets **Most answers shown** (`localFeatures.assistant.maxResults`, 100), from 1 to 500.

See [Search](https://frameleaf.app/docs/using/search/).

### Faces & identity

Groups photos of the same person so you can name them. Your own corrections always win: every "same person" and "different person" choice you make is kept when faces are checked again. See [People and pets](https://frameleaf.app/docs/using/people/) for naming and fixing, and [How face recognition works](https://frameleaf.app/docs/using/people-recognition/) for what happens underneath.

**Recognise people** (`machineLearning.facialRecognition.enabled`, on). Off, the people you have named stay named, and new photos are not added to them.

**How carefully to group** sets the three numbers under Advanced:

| Choice | What it means | Numbers |
| --- | --- | --- |
| **Fewer mistakes** | Someone appears after 5 clear photos. The same person may show up twice and need merging | distance 0.4, clarity 0.8, 5 photos |
| **Balanced** (default) | Someone appears after 3 photos. A few look-alikes may need splitting | distance 0.5, clarity 0.7, 3 photos |
| **Group more photos** | Someone appears after 2 photos, including blurry and side-on faces. Expect more look-alikes to split | distance 0.6, clarity 0.5, 2 photos |

:::note[Saving this changes how faces are grouped]
New photos follow the new choice straight away. The page says how many photos and videos would be grouped again and offers **Save and start tonight** or **Save and start now**. The names you gave and every "same person" or "different person" choice are kept.
:::

**Recognition quality** is a slider of the face models Frameleaf publishes (`buffalo_s`, `buffalo_m`, `buffalo_l` and `antelopev2`), with the same **Processor**, **Your GPU** and **Cloud** bands as **Search quality**. Changing the face model reads your whole library again to find faces: until that finishes, new photos may not match the people you've already named. Your corrections are kept.

**Use people tags saved by other apps** (`metadata.faces.import`, off). If Lightroom, digiKam or another app saved who is in a photo, those people are shown here. It applies to photos added from now on; to include the photos you already have, read their details again from Background work after saving.

**Save people’s names in XMP sidecars** (`metadata.faces.write`, on). Saves names and face positions beside photos so other photo apps can read them. See [XMP sidecars](https://frameleaf.app/docs/using/xmp-sidecars/).

**Advanced: face model and numbers**

- **Face model** (`machineLearning.facialRecognition.modelName`, `buffalo_l`) is the model the slider chose. A larger model is more accurate and slower.
- **How alike two faces must be** (`machineLearning.facialRecognition.maxDistance`, 0.5), from 0.1 to 2. Lower is stricter and makes fewer wrong matches. Lowering it a little can help Frameleaf tell identical twins apart.
- **Face clarity needed** (`machineLearning.facialRecognition.minScore`, 0.7), from 0.1 to 1. Higher ignores blurry or tiny faces in the background.
- **Photos needed before someone appears** (`machineLearning.facialRecognition.minFaces`, 3), 1 or more. Fewer shows people sooner, including some you may not know.

### Text, documents & receipts

Makes signs, receipts and documents searchable by the words in them. See [Documents and text in photos](https://frameleaf.app/docs/using/documents/) for the Documents view, copying text and correcting misread lines.

**Read text in photos** (`machineLearning.ocr.enabled`, on). Off, the words already read stay searchable, and new photos are not read.

**Languages to read** (`machineLearning.ocr.modelName`) chooses one group of alphabets at a time; pick the one most of your photos use. The choices are **English, French, Spanish and similar**; **English only**; **Chinese, Japanese and English** (the default); **Korean and English**; **Russian, Ukrainian and similar**; **Greek and English**; and **Thai and English**. Each group has its own text-reading model.

**How much to read** sets the two scores under Advanced:

| Choice | What it means | Scores |
| --- | --- | --- |
| **Clear text only** | Signs, headings and printed pages. Fewest mistakes; faded or small text is skipped | noticed 0.7, kept 0.9 |
| **Balanced** (default) | Signs, receipts and printed pages. Very faded or tiny text is skipped | noticed 0.5, kept 0.8 |
| **Faint text too** | Also faded receipts and handwriting. More words to search by, and more of them wrong | noticed 0.3, kept 0.6 |

**Read small print** (`machineLearning.ocr.maxResolution`, off) reads the fine print on receipts and documents. It's slower and needs more memory: on, text is read at 1,280 pixels of detail instead of 736.

:::note[Saving this changes how text is read]
New photos follow it straight away. To read the text in the photos you already have again, start it from Background work after saving. Search keeps finding the words already read.
:::

**Suggest receipt details** (`machineLearning.ocr.documentFields`, off) suggests the shop, the date and the total from what was read. Suggestions stay editable and show where they were read from. See [Suggested details](https://frameleaf.app/docs/using/documents/#suggested-details).

**Advanced: text model and numbers**

- **Text-reading model** shows the model for the language group. Only Chinese, Japanese and English has a larger model (`PP-OCRv5_server`), which reads more accurately and is several times slower than the usual `PP-OCRv5_mobile`.
- **How clear text must be to be noticed** (`machineLearning.ocr.minDetectionScore`, 0.5), from 0.1 to 1. Higher skips faint or partial text.
- **How sure a word must be to be kept** (`machineLearning.ocr.minRecognitionScore`, 0.8), from 0.1 to 1. Higher keeps fewer mistakes and fewer words.
- **Detail used for reading text** (`machineLearning.ocr.maxResolution`, 736 pixels), from 1 to 4,096. Set by **Read small print**.

### Descriptions & tags

Writes a sentence or two about each photo, and suggests tags from what is in it. Search uses both, so a photo can be found by its caption as soon as it is written. See [AI descriptions](https://frameleaf.app/docs/using/ai-descriptions/) for what people see, and [Set up AI descriptions](https://frameleaf.app/docs/using/ai-descriptions-setup/) for choosing a model and previewing before you commit.

The status at the top says how many photos have captions. **Update captions now** writes the rest, or rewrites them after you change the choices below. Changes apply to photos added from now on; the photos you already have keep their old captions until they are updated.

#### Captions

**Write captions for photos** (`machineLearning.imageDescription.enabled`, on). Off, captions already written are kept and still used by search; new photos get none.

**Caption length** sets the sentence count and writing style under Advanced:

| Choice | What it means | Underneath |
| --- | --- | --- |
| **Short** | One sentence. "Two people paddle a red canoe on a lake." | 1 sentence, plain and brief |
| **Medium** (default) | Two or three sentences. "Two people paddle a red canoe on a calm lake at sunset. Mountains rise behind them." | 3 sentences, balanced |
| **Detailed** | Up to six sentences, with colours, weather and what people are doing. Longer captions are not always more accurate | 6 sentences, rich in detail |

**Mention people I have named** (`machineLearning.imageDescription.prompt.identityInjection.enabled`, on) makes captions say "Jamie at the lake". People you haven't named stay unnamed.

**Things to look out for** (`machineLearning.imageDescription.prompt.lookFor`) is a list of things captions mention when they can be seen in the photo. It starts with brands, signage, screens, documents, uniforms, tools, vehicles, animals, food and landmarks.

**Never guess at** (`machineLearning.imageDescription.prompt.forbiddenInferences`) is a list captions leave out. It starts with diagnoses, medication names, procedures, pregnancy and disability. Check a few captions after changing this list: it can't be guaranteed.

**Try it on a few photos** writes sample captions with the choices above. Nothing in your library changes.

**Describe moments in videos** (`machineLearning.imageDescription.videoMomentCaptions`, off) adds captions to a few moments in each video. It takes longer, and speech is not written down.

**Descriptions written by hand are kept** follows the preference **Keep what I wrote myself**: while it's on, writing captions again only replaces what Frameleaf wrote. Off, writing captions again can replace a description written by hand.

#### Tags

**Suggest tags automatically** (`machineLearning.clip.zeroShotTagging.enabled`, on) suggests tags from what is in each photo. Tags you added are always kept. Tags are suggested by Visual search, so it has to be on. See [Tags](https://frameleaf.app/docs/using/tags/).

**How many tags** sets the two numbers under Advanced:

| Choice | What it means | Numbers |
| --- | --- | --- |
| **Fewer, surer** | Up to 3 tags on a photo, and only the obvious ones | strictness 0.35, 3 tags |
| **Balanced** (default) | Up to 6 tags on a photo, with an occasional wrong one | strictness 0.25, 6 tags |
| **More tags** | Up to 12 tags on a photo. More to search by, and more to tidy | strictness 0.18, 12 tags |

#### Where and when captions are written

**Where this work runs** is the computer chosen for captions; **Where work runs** opens the page where you choose it. While captions are on, **Caption model** is a slider of the models Frameleaf publishes, from lighter to larger; see [Choose a model](https://frameleaf.app/docs/using/ai-descriptions-setup/#choose-a-model). Captions follow the overnight schedule too: new photos are captioned soon after they arrive, and rewriting many captions waits for the night. **Overnight schedule** opens the nightly settings.

#### Advanced: caption model and hardware

The "model" is the trained program that writes captions. A bigger one writes better captions and needs more graphics memory. The **Caption model** slider shows the ones Frameleaf publishes (`machineLearning.imageDescription.modelName`, `Qwen/Qwen2.5-VL-3B-Instruct`).

- **Hugging Face model** is for a model that isn't on the slider. Enter its full name, like `organisation/model-name`. It's downloaded the first time captions are written.
- **Backup model** (`machineLearning.imageDescription.fallbackModelName`, `microsoft/Florence-2-base-ft`) is used when the main model isn't available. It must be installed too. Choose **Another model, by its Hugging Face name…** to type one in **Backup model name**.
- **Kind of graphics card** (`machineLearning.imageDescription.acceleration`, Automatic). **NVIDIA (CUDA)** or **Intel (OpenVINO)**; choosing one also picks the caption and private-photo models that suit it. This does not install anything.
- **Which graphics card** (`machineLearning.imageDescription.device`, AUTO). Leave as AUTO unless the computer has more than one.

#### Advanced: wording lists and extra instructions

- **Sentences in a caption** (`machineLearning.imageDescription.prompt.sentenceCountTarget`, 3), from 1 to 6, and **Writing style** (`machineLearning.imageDescription.prompt.style`, balanced): **Plain and brief**, **Balanced** or **Rich in detail**. Both are set by **Caption length**; change either and the length shows **Custom**.
- **Extra instructions** (`machineLearning.imageDescription.prompt.customInstructions`) is anything else captions should follow, up to 2,000 characters.
- The page also keeps the lists of words that mark a photo as private or medical (`machineLearning.imageDescription.prompt.nsfwIndicators`, `machineLearning.imageDescription.prompt.medicalIndicators`) and the vocabulary captions should prefer (`machineLearning.imageDescription.prompt.customVocabulary`). See [Prompt & Vocabulary](https://frameleaf.app/docs/using/ai-descriptions-setup/#prompt--vocabulary).

#### Advanced: names, and writing your own instructions

- **Most names in one caption** (`machineLearning.imageDescription.prompt.identityInjection.maxNames`, 5), from 1 to 20.
- **How sure before naming someone** (`machineLearning.imageDescription.prompt.identityInjection.minFaceConfidence`, 0.7), from 0 to 1. Higher names fewer people. Fixing a face updates its captions.
- **Write my own instructions** (`machineLearning.imageDescription.prompt.advanced.enabled`, off) is for experts: it replaces the built-in caption instructions with **Your instructions** (`machineLearning.imageDescription.prompt.advanced.rawPromptTemplate`). `{schema}`, `{names}`, `{vocabulary}` and `{style_hint}` are filled in for each photo. Keep `{schema}`, or captions can't be read back. **If the schema placeholder is missing** (`machineLearning.imageDescription.prompt.advanced.placeholderValidation`, Don't save) chooses between **Don't save** and **Warn me**. **Start again from the built-in text** puts the built-in instructions back. See [Raw prompt editor](https://frameleaf.app/docs/using/ai-descriptions-setup/#raw-prompt-editor).

#### Advanced: suggested tags, in numbers

- **Tag match strictness** (`machineLearning.clip.zeroShotTagging.minSimilarity`, 0.25), from 0 to 1. Higher gives fewer, surer tags.
- **Most tags on one photo** (`machineLearning.clip.zeroShotTagging.maxTags`, 6), from 1 to 20. Tags you added don't count.

### Locked-content detection

Looks for private photos, such as nudity, and suggests moving them to Locked. Only the photo's owner sees the suggestion, and nothing is locked until they agree. Who can open Locked, and what it hides, is set by each person in **Your sign-in & privacy**; see [Locked and private content](https://frameleaf.app/docs/using/private-content/) and its [Automatic detection](https://frameleaf.app/docs/using/private-content/#automatic-detection) section.

**Suggest photos to lock** (`machineLearning.nsfwDetection.enabled`, off). Off, photos already in Locked stay there, and no new suggestions are made. On, new photos are checked soon after they arrive.

**How cautious to be** sets the score under Advanced:

| Choice | What it means | Score |
| --- | --- | --- |
| **Only the obvious** | Suggests only photos that are clearly private. Some will be missed | 0.95 |
| **Balanced** (default) | Suggests most private photos, with an occasional beach or bath photo by mistake | 0.85 |
| **Suggest more** | Misses very little. Expect more ordinary photos among the suggestions | 0.7 |

:::note[Saving this changes which photos are suggested]
New photos follow it straight away. To check the photos you already have again, start it from Background work after saving. Photos already in Locked stay there, whatever the new check finds.
:::

**What Locked hides** opens **Locked content** in **Your sign-in & privacy**, the one place where who can open Locked, and what it hides, is set.

**Tags never unlock a photo**: a photo stays in Locked even if someone removes its tags. Only its owner's PIN opens it.

**Advanced: model, hardware and number**

- **Hide flagged photos until unlocked** (`machineLearning.nsfwDetection.hideFromLibrary`, off) keeps the photos this check flags out of library views until the session is unlocked with the PIN.
- **Private-photo model** (`machineLearning.nsfwDetection.modelName`, `onnx-community/nsfw_image_detection-ONNX`). What it finds stays on this server. Type another only if you know it is installed.
- **Runs on** (`machineLearning.nsfwDetection.device`, AUTO) is which processor or graphics card does the checking. AUTO lets Frameleaf choose.
- **How sure before suggesting** (`machineLearning.nsfwDetection.threshold`, 0.85), from 0.01 to 1. Higher suggests fewer photos.

### Categories & smart albums

Albums such as Travel, Food and Pets that fill themselves from what is in each photo, and categories of your own. Your own albums and tags are never changed. See [Built-in smart albums](https://frameleaf.app/docs/using/smart-albums/).

**Build smart albums** (`smartAlbums.enabled`, off). Off, no albums are made for anyone; the choices for each album are kept.

**Smart albums** lists each built-in album as **Offered** or **Not offered**. Open one to change it:

- **Offer this album**: off takes the album out of everyone's library. No photo is removed or changed.
- **Album name** is the name everyone sees.
- **Words that add a photo**: a photo joins when it shows any of these. Behind it are two lists, under **Advanced: the two lists and the number**: a single word is a **tag that adds a photo**, which has to be on the photo exactly; several words are a **description that adds a photo**, compared with what the photo looks like.
- **How strict** sets **Match strictness** under Advanced, from 0.2 to 0.4: **Fewer, surer** (0.32), almost every photo clearly belongs but some that belong may be left out; **Balanced** (0.28), a few photos may not belong; **More photos** (0.24), more of them will only look a bit like the album.
- **Update this album** sorts the photos you already have again with the saved choices. Changes otherwise apply to photos added from now on; **Update albums now** on the main page does the same for every album.

#### Categories of your own

**Suggest my own categories** (`smartAlbums.rules.visualCategories`, on) lets people describe a category, such as "birthday parties", and see which photos match before anything is tagged.

**When a photo matches a category** (`smartAlbums.rules.defaultAction`, Ask me first): **Ask me first** keeps matches in a list for you to accept, and nothing is tagged until you do; **Tag it automatically** gives matching photos the category's tag straight away, and you can remove it from any photo. Nothing is ever archived unless you choose that for a category.

## Editing & playback

How photos and videos are made ready to view, and how edits are saved. Photos get a preview and videos that won't play everywhere get a playback copy, so browsing is fast on every device. Your originals are never changed.

The area opens on a status page that says whether photos and videos are ready to view, or how many are still waiting, and names the saved preview quality and playback rule. Under **Viewing** are **Image previews** and **Video playback copies**; under **Editing** are **Edited masters**, **AI restoration** and **Studio & Dolby Vision**. Each page starts with a plain choice and keeps the numbers behind it under **Advanced**. When the numbers match a preset, the page names it; when you have set your own, it says **Custom**.

### Image previews

Smaller copies that keep browsing fast. The status at the top says whether every photo has a preview, or how many photos and videos are still waiting; browsing keeps working with the old previews until each new one is ready.

**Preview quality** sets the thumbnail and preview numbers under Advanced:

| Choice | What it means | Thumbnail | Preview |
| --- | --- | --- | --- |
| **Space saver** | Takes the least space. Fine on phones, a little soft on a large screen | WebP, 200 px, quality 70 | WebP, 1080 px, quality 70 |
| **Balanced** (default) | Sharp on phones, tablets and most laptops | WebP, 250 px, quality 80 | JPEG, 1440 px, quality 80 |
| **Sharpest** | Sharp on 4K screens and when you zoom in. Takes the most space | WebP, 480 px, quality 90 | JPEG, 2160 px, quality 90 |

**Make full-size viewing copies** (`image.fullsize.enabled`, off) is for RAW and HEIC photos, which browsers can't show at full size. It uses more space.

:::note[These choices apply to photos added from now on]
When you change a choice, the page offers two ways to save. **Save and rebuild tonight** also makes the previews of the photos you already have again, in the overnight schedule; browsing keeps working with the old ones until then. **Save for new photos** leaves the previews you have as they are. **Undo** puts the saved choices back before you save.
:::

**Rebuild every preview** has the **Rebuild previews** button, which makes them all again straight away with the saved choices; browsing keeps working meanwhile, and **Stop** on the status ends it, keeping the previews already made. A photo with no preview yet shows a grey square until it is made. **Runs in the overnight schedule** reminds you that new photos get their previews as they arrive, and any preview still missing is made in the overnight schedule, which **Overnight schedule** opens. See [Jobs and queues](https://frameleaf.app/docs/admin/jobs/#nightly-tasks).

For videos, Frameleaf samples several frames before it picks the thumbnail. On longer videos it prefers frames at least 30 seconds in, and it skips black, blown-out or flat frames.

#### Advanced: thumbnails

The small pictures in the library grid. **Preview quality** sets these; changing one here makes that choice **Custom**.

- **Size** (`image.thumbnail.size`, 250 px) is the longer edge, in pixels: **Smaller, 200 px**; **Small, 250 px**; **Medium, 480 px**; **Large, 720 px**; or **Largest, 1080 px**. Larger looks sharper and uses more space. A size set in the config file outside these choices is shown as it is and kept.
- **Format** (`image.thumbnail.format`, WebP). WebP takes less space; JPEG works everywhere.
- **Quality** (`image.thumbnail.quality`, 80), from 1 (**Smaller files**) to 100 (**Best looking**).
- **Show a blurry version while loading** (`image.thumbnail.progressive`, off). The picture sharpens as it arrives. JPEG only: choosing WebP turns it off.

#### Advanced: previews

The picture you see when you open one photo. It is also what search and recognition read.

- **Size** (`image.preview.size`, 1440 px): **Small, 720 px**; **Medium, 1080 px**; **Large, 1440 px**; or **Largest, 2160 px**.
- **Format** (`image.preview.format`, JPEG).
- **Quality** (`image.preview.quality`, 80), from 1 to 100.
- **Show a blurry version while loading** (`image.preview.progressive`, off). JPEG only.

#### Advanced: full-size viewing copies

Used when you zoom in on a photo your browser can't open by itself. Only made when **Make full-size viewing copies** is on, and these rows are held until it is.

- **Format** (`image.fullsize.format`, JPEG). JPEG works everywhere; WebP takes less space.
- **Quality** (`image.fullsize.quality`, 80), from 1 to 100.
- **Show a blurry version while loading** (`image.fullsize.progressive`, off). JPEG only.

#### Advanced: colour and RAW photos

- **Colour range** (`image.colorspace`, Display P3). **Display P3** keeps richer colours on modern screens; **sRGB** suits older ones. sRGB photos stay sRGB either way.
- **Use the camera's own preview** (`image.extractEmbedded`, off) gives faster previews for RAW photos, using the picture the camera already made. How good it is depends on the camera.
- **Better RAW previews** (`image.enhancedRaw.enabled`, on) works the picture out from the RAW file itself when the camera's preview is missing or unusable.

### Video playback copies

Copies that play smoothly on every device. A playback copy sits beside the original; downloads and backups always use the original. The status at the top says whether every video plays on every device, how many are waiting for a copy, or that playback copies are off, in which case videos play from the original, which some phones, TVs and browsers can't show. [Video transcoding](https://frameleaf.app/docs/admin/video-transcoding/) goes further into every option.

#### Playback copies

**Which videos get a copy** (`ffmpeg.transcode`, Only videos that need one) is the rule in plain words. The three other rules stay under Advanced; while one of them is saved, the choice here shows that rule's name:

| Choice | What it means | Rule |
| --- | --- | --- |
| **Only videos that need one** (default) | Videos that already play on every device are left as they are | `required` |
| **All videos** | Every video gets a copy. Uses more space; worth it on a slow connection, where a smaller copy starts sooner | `all` |

**Playback quality** sets the size and the quality number under Advanced:

| Choice | What it means | Playback size | Quality number |
| --- | --- | --- | --- |
| **Good (720p)** | Plays everywhere and takes the least space. Looks soft on a TV | 720p | 23 |
| **Better (1080p)** (default) | Plays everywhere. Sharp on phones, laptops and most TVs | 1080p | 23 |
| **Best (4K)** | Needs a fast connection and a recent device, and copies take much longer to make | 4K | 20 |

:::note[These choices apply to videos added from now on]
When you change a choice, the page offers two ways to save. **Save and remake tonight** also remakes the playback copies you already have, in the overnight schedule (switching to **All videos** on a big library takes a few nights); videos keep playing with the old copies until then. **Save for new videos** leaves the copies you have as they are. **Undo** puts the saved rule, size, quality number and conversion speed back before you save.
:::

**Remake every playback copy** has the **Remake copies** button, which makes the copies again straight away with the saved choices; videos keep playing meanwhile, and **Stop** on the status ends it, keeping the copies already made. It is held while the rule is **Never make copies**.

**HDR on regular screens** (`ffmpeg.tonemap`, on) shows bright HDR videos with natural colours on screens that aren't HDR. Your HDR originals are kept. Turning it on uses the **HDR method** saved under Advanced, or Hable if none was. It also decides how an edited HDR video is saved; see [Edited masters](#edited-masters).

**Adjust quality to the connection (early feature)** (`ffmpeg.realtime.enabled`, off) makes videos start faster and switch quality as the connection changes. Each step is made as the video plays, so a server that can't keep up may stutter. See [Adjust quality to the connection](https://frameleaf.app/docs/admin/video-transcoding/#adjust-quality-to-the-connection).

**Your original videos are never changed**: a playback copy sits beside the original, and downloads and backups always use the original.

#### Speed

**Use the graphics card to convert videos faster** (`ffmpeg.accel`, off) says which card it is set to use, or the card the server's own check found. It can only be turned on once a card has been found or chosen; otherwise it says that no graphics card for video was found. **Test it** makes a short test video with the card and says whether it worked, and how many times faster than the processor it was; the row then shows when it was last tested. If the card stops answering later, the page says the day it stopped helping: playback copies are made with the processor instead, which is slower, and every video still plays. **Which graphics card this server has** opens **Graphics card check**, where the card is checked once for the whole server. See [Hardware transcoding](https://frameleaf.app/docs/admin/video-transcoding/#hardware-transcoding) and [Hardware acceleration](https://frameleaf.app/docs/admin/hardware-acceleration/#check-your-hardware).

#### Advanced: which videos need a copy

A video is played as it is when its picture, its sound and its file type are all on these lists. Anything else gets a playback copy.

- **Rule** (`ffmpeg.transcode`, Only videos that need one): **Only videos that need one**, **All videos**, **Also videos larger than the playback size** (`optimal`), **Also videos above the largest file rate** (`bitrate`) or **Never make copies** (`disabled`). With **Never make copies**, some videos will not play on some devices. See [Which videos get a copy](https://frameleaf.app/docs/admin/video-transcoding/#which-videos-get-a-copy).
- **Video formats played as they are** (`ffmpeg.acceptedVideoCodecs`, H.264): H.264, HEVC, VP9 and AV1. Called codecs. The format copies are made in is always on the list and can't be cleared.
- **Sound formats played as they are** (`ffmpeg.acceptedAudioCodecs`, AAC, MP3 and Opus), plus PCM 16-bit. Other sound is converted even if the picture plays fine. The sound format copies are made in is always on the list.
- **File types played as they are** (`ffmpeg.acceptedContainers`, MOV, Ogg and WebM). Called containers.
- **Largest file rate** (`ffmpeg.maxBitrate`, 0). Called the maximum bitrate: how much data one second of video may use, such as 8M. Videos above it get a smaller copy. 0 means no limit.

#### Advanced: how copies are made

The video converter's own settings. **Playback quality** sets the size and the quality number together; change either and it shows **Custom**.

- **Playback size** (`ffmpeg.targetResolution`, 1080p): 480p, 720p, 1080p, 1440p, 4K or **Same as the original**. The longer side is scaled down to this; videos are never scaled up.
- **Video format** (`ffmpeg.targetVideoCodec`, H.264): H.264, HEVC, VP9 or AV1. Called the codec. H.264 plays almost everywhere; newer ones are smaller but not every device has them. Choosing a format also makes it the only one played as it is, so older copies are not kept.
- **Quality number** (`ffmpeg.crf`, 23), from 0 to 51. Called CRF. Lower looks better and uses more space. The right value depends on the format: typically 23 for H.264, 28 for HEVC, 31 for VP9 and 35 for AV1.
- **Conversion speed** (`ffmpeg.preset`, ultrafast): ultrafast, superfast, veryfast, faster, fast, medium, slow, slower or veryslow. Called the preset. Slower makes smaller files and takes longer. Real-time playback uses it too.
- **Sound format** (`ffmpeg.targetAudioCodec`, AAC): AAC, MP3 or Opus. Only for playback copies. Choosing one adds it to the sound formats played as they are.
- **Processor cores for video** (`ffmpeg.threads`, 0), from 0 to 256. 0 lets Frameleaf decide. More convert faster and slow other things down.
- **HDR method** (`ffmpeg.tonemap`, Hable): **Hable**, **Mobius**, **Reinhard** or **Off**. Called tone mapping: how bright HDR colours are fitted to a regular screen. Used when **HDR on regular screens** is on; choosing **Off** here turns that switch off. Hable keeps detail, Mobius colour and Reinhard brightness.
- **Convert in two passes** (`ffmpeg.twoPass`, off). Better quality at the same size. Takes about twice as long. With H.264 and HEVC it needs a largest file rate and ignores the quality number.
- **Keyframe spacing** (`ffmpeg.gopSize`, 0 frames), 0 or more. Called the GOP size. 0 uses the default. Shorter spacing makes skipping through a video snappier and files larger.

#### Advanced: graphics card

Set these only if Frameleaf picks the wrong graphics card or you are tuning a particular card.

- **Kind of graphics card** (`ffmpeg.accel`, Off): **NVIDIA (NVENC)**, **Intel (Quick Sync)**, **VAAPI**, **Rockchip (RKMPP)** or **Off**. Called hardware acceleration. This is what the **Use the graphics card** switch above turns on and off.
- **Read videos with the graphics card too** (`ffmpeg.accelDecode`, on). Called hardware decoding. Faster when the card supports the video's format.
- **Which graphics card** (`ffmpeg.preferredHwDevice`, auto) is the card's place on the server, such as `/dev/dri/renderD128`. Leave as auto unless there is more than one. Applies to VAAPI and Quick Sync.
- **B-frames** (`ffmpeg.bframes`, −1 frames), from −1 to 16. In-between frames that make files smaller. −1 uses the default.
- **Reference frames** (`ffmpeg.refs`, 0 frames), from 0 to 6. More makes files smaller and uses more memory.
- **Constant-quality mode** (`ffmpeg.cqMode`, Automatic): **Automatic**, **CQP** or **ICQ**. How the card holds quality steady. The choices depend on the card.
- **Smarter quality over time** (`ffmpeg.temporalAQ`, off). Called temporal AQ. Spends more detail on moving scenes when the card supports it. NVIDIA cards only.

#### Advanced: adjusting quality to the connection

Used when **Adjust quality to the connection** is on; both rows are held until it is. Each step is made as the video plays.

- **Formats to stream** (`ffmpeg.realtime.videoCodecs`, H.264 and HEVC), plus AV1. With a graphics card, choose only formats it can make.
- **Quality steps** (`ffmpeg.realtime.resolutions`, 480p, 720p and 1080p), plus 1440p and 4K. Never larger than the original.

### Edited masters

How your edited photos and videos are saved. See [How edits are stored](https://frameleaf.app/docs/using/editing/#how-edits-are-stored) for what lives where, and [What an edited video keeps](https://frameleaf.app/docs/using/editing/#what-an-edited-video-keeps) for the full list of guarantees.

**Original quality** is what every edit keeps. Frameleaf always does this; it isn't a choice:

- **Resolution**: **Original size**. Edits keep the original size. Only a crop makes an edit smaller.
- **Colour handling**: **Standard range** while **HDR on regular screens** is on, so edited HDR videos look right on every screen; **HDR kept** while it is off, so edited HDR videos keep their HDR colours. Your HDR original is always kept. The row links to the switch that sets it, on Video playback copies.
- **Audio handling**: **Every channel**. Edits keep every audio channel as recorded, with its timing.

**Video trims** is where the video editor starts each new trim; you can still cut one video the other way.

- **How trims are cut** (`editing.trimMode`, Precise). **Precise** cuts exactly where you choose: the video is made again from the original, which takes a little longer. **Fast · keyframe aligned** saves in seconds when a trim is the only change, but may start slightly earlier; with other changes the cut stays exact. It is also how the server cuts a trim that names no mode. See [Video tools](https://frameleaf.app/docs/using/editing/#video-tools).

### AI restoration

Clean up and sharpen old videos, with a short preview first. See [Restore and upscale](https://frameleaf.app/docs/using/editing/#restore-and-upscale) and the Studio guide to [Restoration](https://frameleaf.app/docs/studio/restoration/).

**Restoring a video** holds the one setting: each restoration starts with this style, and you can still choose the other one for a video.

- **Restoration style** (`editing.restoration.style`, Faithful). **Faithful** removes noise and blockiness without inventing detail. **Creative** rebuilds fine detail, which suits very small or soft videos; it can invent texture that wasn't there. See [Choose a mode](https://frameleaf.app/docs/studio/restoration/#choose-a-mode).

The page then lists what every restoration does:

- **A 5-second preview comes first.** You compare before and after on part of the video, then decide whether to restore all of it.
- **Your original is always kept.** A restored video is saved as a new version beside it.
- **Restored videos are at most 4K.** You choose the size for each video. Nothing is made larger than 3840 × 2160.

**Where restoration runs**: AI restoration and Smooth motion run on the computer chosen in **Where work runs**, which the button opens. Choose **Nowhere (keep this off)** there to stop offering one of them. See [Choose where each kind of work runs](https://frameleaf.app/docs/admin/workers/#choose-where-each-kind-of-work-runs).

### Studio & Dolby Vision

Whether this server can make Studio exports. Nothing here is a setting: each row is a fact this server can answer, and **Graphics card check** opens the page that checks the server's own card. See the [Studio overview](https://frameleaf.app/docs/studio/overview/) and [Exporting](https://frameleaf.app/docs/studio/exporting/).

- **Studio exports**: making the finished video of a project. It needs a computer with a graphics card connected to this server, so the row says **Ready**, **Can't run yet**, **Checking…** or **Couldn't check**, from what the connected computers can take now.
- **HDR projects**: **Automatic**. A project becomes HDR as soon as it holds an HDR clip. Regular screens see it tone mapped. See [HDR projects](https://frameleaf.app/docs/studio/colour/#hdr-projects).
- **Dolby Vision**: **Not yet**. Studio can't make Dolby Vision video yet.
- **Where Studio opens**: **Browsers and tablets**. Studio opens in any web browser and in the Frameleaf app on tablets. The phone apps don't include it in this version.

## Libraries

The Libraries page, where you add and check [folders of photos](https://frameleaf.app/docs/admin/external-libraries/), sits above the settings. **Keeping folders up to date** holds the two server-wide settings:

- **Check every folder each night** (`library.scan.enabled`, on). Frameleaf looks for new, changed and removed files, one folder after another, so photos added to a folder show up without anyone pressing **Check now**. It **Runs in the overnight schedule**, after backups; the time is set in **Overnight schedule** (see [Jobs and queues](https://frameleaf.app/docs/admin/jobs/)).
- **Notice new files right away** (`library.watch.enabled`, off). A photo saved into a folder shows up within a minute, instead of waiting for the next check. It works for folders on this server's own disks, not network drives, and is still being tested. See [Keeping folders up to date](https://frameleaf.app/docs/admin/external-libraries/#keeping-folders-up-to-date).

## Library care

Check that your photos and videos are all there, fix what isn't, and clear out duplicates. The area opens on **Library health**, the answer to "is my library all right?", then has one page for each part: **File checks**, **Things to fix**, **Tidy up**, **Duplicates**, **Album cleanup** and **Search and recognition progress**, and ends with **Identify photo locations** and the **Tools**. An administrator sees the whole household and every setting below; a member sees their own library, their own Things to fix and their own damaged and missing files, and no settings. Checks only look. When one finds a damaged or missing file, Frameleaf tries to fix it by itself and lists what it did; nothing is deleted to fix a file, and any fix can be undone.

For the tools themselves see [Library Care](https://frameleaf.app/docs/using/library-care/); for damaged and missing photos see [Damaged and missing files](https://frameleaf.app/docs/using/damaged-and-missing-files/); for what each check looks at see [System integrity](https://frameleaf.app/docs/admin/system-integrity/); for finding a file that moved see [Media recovery](https://frameleaf.app/docs/admin/media-recovery/).

### Library health

The status at the top says **Your library is healthy** when every photo and video was on the drive and undamaged when last checked, **Not checked yet** before the first check (it runs tonight, and reads every file, so on a large library it is spread over a few nights), or how many files need attention. **Check now** starts the three file checks straight away; you can keep using Frameleaf while they run. Under it, **Original files** says whether they are all present and undamaged and when that was checked, and **Search and recognition** says how many photos are still to read for faces, captions, text and search.

**Needs attention** lists what was found, one row per kind: missing files (**Find them**), damaged files and files not in a library (**Review**), and files that couldn't be processed. Nothing has been removed; each row opens the place it is fixed.

After a library is brought in from another app, **Checking your imported library** shows here while Frameleaf reads every imported file, with how many files are checked and how many identical photos were merged. **Pause** stops it without losing anything, and **Resume** carries on from where it stopped.

**Look after your library** opens the pages below, each with its state. Beside the pages described here it has **Tidy up**, which moves memes, receipts, screenshots and other clutter off the timeline (see [Tidy up](https://frameleaf.app/docs/using/tidy-up/)), and **Album cleanup**, which merges duplicate albums and nests albums by their names, with **Undo last cleanup** after one has run (see [Tidy your albums](https://frameleaf.app/docs/using/tidy-your-albums/)).

**Identify photo locations** names the places your photos were taken, such as a park or a café, using AI credit you choose to spend on Frameleaf Cloud. See [Name the businesses and venues in your photos](https://frameleaf.app/docs/using/places/#name-the-businesses-and-venues-in-your-photos).

**Tools** opens the lists you work through at your own pace: **Live Photo pairing**, **Missing files**, **Damaged files** and, for the server's owner, **Unused files**. See [Library Care](https://frameleaf.app/docs/using/library-care/) for each tool.

### File checks

Looks for original files that have gone missing, been damaged, or been left on the drive in nobody's library, and shows what was found. The status says **Every file is present and undamaged** with when that was last checked, **Not checked yet**, **Checking your files now**, **File checks are off** (nothing is looking, so a problem would only show up when someone opens the photo), or how many files need attention. **Check now** runs every check that is on; **Check again** does the same once something was found.

:::note[Check the drive before anything else]
When many missing files all sit in one folder, the page says so: that usually means a drive is unplugged or a folder was moved, not that the photos are gone. Once the drive is plugged back in or the folder is put back, check again and the list clears by itself. Moving those photos to Trash would take them out of your library.
:::

#### What was found

Each kind that found something gets its own list, with its fixes in order of safety:

- **Missing files** are in your library but no longer on the drive; the photos still show their previews. **Find them again** opens the Missing files tool; see [Find a file that moved or was renamed](https://frameleaf.app/docs/admin/media-recovery/#find-a-file-that-moved-or-was-renamed). **Clear this list** forgets the findings and touches nothing; anything still wrong at the next check is listed again. **Move these photos to Trash…** takes them out of your library, and asks first.
- **Damaged files** are on the drive but have changed since Frameleaf stored them, so they may not open. **Restore from a backup** opens the restore page. **Look for a good copy** (or **Look at it**, when no other copy can be searched for) opens the Damaged files tool; see [Damaged files](https://frameleaf.app/docs/using/library-care/#damaged-files). **Clear this list** and **Move these photos to Trash…** work as above.
- **Files not in a library** are in Frameleaf's folders on the drive but in nobody's library, usually left by an upload that was cut off. Frameleaf read each one once and sorted it. The list says how many are photos again ("Any of them can be undone"), how many are spare copies (**Left alone**) and how many need a decision from you, and shows a few of the photos. **See the photos** opens [Photos found on the drive](#photos-found-on-the-drive). There is no button here that deletes these files.

Each list shows three findings and says how many more are in **Details for support**; **Remove from list** takes one finding off the list without touching its file.

#### What is checked

Three checks, one after another. Nothing is moved, renamed or deleted unless you press a button. Each has a switch, **Look for …**, and its own **Check now**. **Check one…**, on Missing files and Damaged files, lets you pick one photo or video and checks its file straight away, without waiting for the rest of the library or tonight's run. A switch writes every setting that check is made of, and reads as on only when all of them are on.

- **Missing files** (`integrityChecks.missingFiles.enabled` with `libraryCare.healthScan`, on) looks for files that are in your library but no longer on the drive. Off: missing files won't be noticed.
- **Damaged files** (`integrityChecks.checksumFiles.enabled` with `libraryCare.checksumScan`, on) looks for files that have changed since Frameleaf stored them. Off: damage won't be noticed.
- **Files not in a library** (`integrityChecks.untrackedFiles.enabled`, on) looks for files on the drive that are in nobody's library. Photos are put back by themselves. Off: photos left off the library won't be noticed.

Turning **Missing files** or **Files not in a library** on also keeps the audit of the database's file references on (`libraryCare.integrityAudit`, on); it goes off only when both are off. A row that has never run says **Not checked yet** and **First check tonight**.

#### When a check finds a problem

"Frameleaf tries to fix it at once and lists what it did, so you can review it." **See damaged and missing files** opens [Damaged and missing files](#damaged-and-missing-files), where the same switches sit.

- **Repair damaged photos by themselves** (`libraryCare.autoRepair`, on). "A repaired copy takes the damaged one's place, and the damaged file is kept beside it. Any repair can be undone." Off: "Damaged photos wait for you. You see each repair before choosing it." Either way, Frameleaf still looks for an exact copy of a photo whose file changed after it was stored.
- **Look for missing files** (**Always**). "Compares files on this server's drives, in the folders your old photo app used and in your backups by their contents, so a renamed or moved copy is still found." There's no setting behind it; it can't be turned off.
- **Put found photos back by themselves** (`libraryCare.putBackFoundFiles`, on). "A photo that went missing is joined to its file again, and a photo no library has is added. Either can be undone." Off: "found photos wait in Needs you, and nothing joins the library until you choose." **See found photos** opens [Photos found on the drive](#photos-found-on-the-drive), where the same switch sits.

#### When checks run

**Runs in the overnight schedule**: the checks run at night, so they don't slow Frameleaf down during the day. **Overnight schedule** opens the nightly settings in Computers & background work; see [Nightly tasks](https://frameleaf.app/docs/admin/jobs/#nightly-tasks).

**Advanced: how much is checked each night** holds the limits on the damage check. Looking for damage means reading each file from start to finish, which keeps the disk busy, and these two stop a big library from being read all night:

- **Stop after** (`integrityChecks.checksumFiles.timeLimit`, 1 hour): **30 minutes**, **1 hour**, **2 hours**, **4 hours** or **8 hours**. Each night's damage check stops after this long, and the next night carries on where it left off.
- **Check each night** (`integrityChecks.checksumFiles.percentageLimit`, The whole library) is how much of the library the damage check reads in one night:

| Choice | What it means | Underneath |
| --- | --- | --- |
| **The whole library** (default) | Every file is read again on each night it fits in the time allowed | 100% |
| **Half** | Every file is read again every 2 nights | 50% |
| **A quarter** | Every file is read again every 4 nights | 25% |

A share set in the config file that matches none of these is shown as its percentage; choose one of the three to change it.

The checks, and the file health scan that fills the Missing files and Damaged files tools, all run in the overnight schedule's **Check files** step, so they have no start times of their own. The config file still keeps `integrityChecks.missingFiles.cronExpression`, `integrityChecks.checksumFiles.cronExpression`, `integrityChecks.untrackedFiles.cronExpression` and `libraryCare.healthScanCronExpression`, but they no longer start anything.

**Details for support** lists every finding with the place of its file on the drive, for when you are working through a fault with someone: **See every path** opens one check's full list, and **Download … as a spreadsheet** saves it. See [Review the reports](https://frameleaf.app/docs/admin/system-integrity/#review-the-reports).

**Recent checks** lists the last runs: which check, when, how many files it read and how long it took, and whether it found nothing wrong, stopped before it finished, or carries on next night.

### Things to fix

Everything Frameleaf has found that needs a decision from you, in one list. Every account opens it: an administrator sees the whole household, a member their own library. The status says **Nothing to fix**, how many suggestions are waiting for you, or how many files need attention. Nothing changes until you choose.

**Waiting for you** has a row per kind, each with a count and a **Review** button that opens its list. Turn a kind of suggestion off and Frameleaf stops looking for it; the row then says **Not looking**, and suggestions already made are kept.

- **Missing files** and **Damaged files** come from File checks. **Review** opens the **Needs you** list in [Damaged and missing files](#damaged-and-missing-files).
- **Fixed for you** (administrators): "Damaged photos Frameleaf repaired and missing ones it found again. Any of them can be undone." The count is for this week, the same as the Overview's. **Review** opens the **Fixed for you** list.

When Frameleaf has fixed files this week and some are still left, the status says how many files need you: "Frameleaf fixed N files by itself this week. N missing and N damaged are left: it has tried everything it can for them."
- **Live Photos to reconnect** (`libraryCare.livePhotoRepair`, on): photos that lost their moving part. Unclear pairs wait for you. **Review** opens the Live Photo pairing tool; see [Live Photos](https://frameleaf.app/docs/using/library-care/#live-photos).
- **RAW files to match** (`libraryCare.rawRecovery`, on): RAW originals that belong with a JPEG you already have. They are matched when missing files are searched for, so the row says **Looking** rather than a count; **Review** opens the Missing files tool.
- **Look-alike photos** suggests which copy to keep, and is turned on and off in **Duplicates**. **Review** opens the duplicates review; see [Review duplicates](https://frameleaf.app/docs/using/duplicates/#review-duplicates).
- **Couldn't process**: photos and videos Frameleaf couldn't read or make previews of, set aside after 3 tries. The originals are untouched. See [Couldn't process](https://frameleaf.app/docs/using/library-care/#couldnt-process).
- **Dates that look wrong**: a camera clock, a time zone or a missing date put these in the wrong place. **Review** opens the [Date & Time Doctor](https://frameleaf.app/docs/using/date-and-time-doctor/).

### Damaged and missing files

"Every file Frameleaf found a problem with, what it did about it, and anything left for you." Every account has this page: a member sees their own files, and an administrator also sees the household's, without their pictures. The tabs are **Needs you**, **Fixed for you** and **Left as they are**, and each file opens its **What happened** history. See [Damaged and missing files](https://frameleaf.app/docs/using/damaged-and-missing-files/) for the page itself and what to do about each file.

**What Frameleaf does by itself** ("As soon as a problem is found, and after each night's file checks") is shown to administrators only:

- **Repair damaged photos by themselves** (`libraryCare.autoRepair`, on). The same switch as in [File checks](#when-a-check-finds-a-problem). Off: "Damaged photos wait in Needs you, where you see each repair before choosing it."
- **Look for missing files** (**Always**). Frameleaf compares files by their contents, so a renamed or moved copy is still found.
- **Ask phones for missing photos** (`libraryCare.askPhones`, on). "Phones with the Frameleaf app look for photos this server has lost each time the app is opened, and send back any they still have. Nothing to tap." Off: phones aren't asked, and a missing photo goes straight to Needs you once the server's own search and Cloud Backup have been tried. See [Phones send lost photos back](https://frameleaf.app/docs/using/damaged-and-missing-files/#phones-send-lost-photos-back).

Under them, **Nothing is deleted to fix a file**: "A repaired photo takes the damaged one's place in your library, and the damaged file is kept beside it. When Frameleaf moves a file into its folder, the old one stays until the new copy has been checked to match it exactly."

### Photos found on the drive

"Files that were on the drive but in nobody's library: what each one turned out to be, and what Frameleaf did with it." Administrators open it from **File checks** with **See the photos**; it isn't in the list of pages. The files are shown as pictures in four lists, **Needs you**, **Put back**, **Added** and **Spare copies**, and each picture opens what happened to that file, with **Undo**. Another account's picture is never shown; a lock stands in its place. See [Photos found on the drive](https://frameleaf.app/docs/using/photos-found-on-the-drive/) for the page itself.

**Tidied without asking** says how many previews for photos that are gone were cleared, and how many XMP files were joined to the photo of the same name. Neither is listed for review.

**What Frameleaf does by itself** ("After each night's file checks, and as soon as a file is found"):

- **Put found photos back by themselves** (`libraryCare.putBackFoundFiles`, on). The same switch as in [File checks](#when-a-check-finds-a-problem). Off: "found photos wait in Needs you, and nothing joins the library until you choose."
- **Clear previews for photos that are gone** (`libraryCare.clearGonePreviews`, on). "Only files Frameleaf made itself. An original is never cleared." Off: those previews are left on the drive.

Under them, **An original is never deleted to tidy the drive**: "Each file is read once and remembered, so the drive isn't read again for the same answer. Spare copies and files that won't open stay where they are until you delete them yourself."

### Duplicates

Two kinds: exact copies of the same file, which Frameleaf handles for you, and photos that only look alike, where you choose. The status says **Every file is stored once**, **No duplicates to deal with**, how many look-alike groups are waiting (**Review look-alikes**), or how many files could not be checked. See [Duplicates](https://frameleaf.app/docs/using/duplicates/) for the review itself.

#### Exact copies

When the very same file is added twice, by you or by two people, Frameleaf keeps one file on the drive. Each person still sees it in their own library, with their own albums and edits. There is no switch for this. Under **Identical files are stored once** the page shows:

- how much space is saved, and when the library was last checked
- **Check again**, which reads every file again. It changes nothing you can see, and every merge it makes can be undone
- **Recent merges**: how many the last check made. **See merges** opens the duplicate review, where each one is listed under **Merged for you** and can be undone
- **Extra copies not stored once yet**: identical files that were found but not merged yet, and the space they take. **Check again** stores them once
- **Extra copies**: the copies that are no longer needed wait in **Unused files**, and the space comes back when the server's owner empties it
- **Problems**: files that were skipped, as **Could not be read from the drive**, **Changed while it was being read** or **Not merged** (files in folders Frameleaf reads but never changes). Nothing is merged or removed on a guess

**Only files that are exactly the same are merged**: Frameleaf reads each whole file from the drive, and two files are identical only when every byte matches. The oldest copy is kept.

See [Identical files](https://frameleaf.app/docs/admin/physical-deduplication/).

#### Look-alike photos

Bursts, edited versions and copies saved again by another app. Frameleaf groups them and suggests which to keep. Nothing is deleted until you choose.

**Find look-alike photos** (`machineLearning.duplicateDetection.enabled` with `libraryCare.duplicateReview`, on) is one switch for both settings, and is on only while both are. Off: groups already found stay in the review until you deal with them. **Search and recognition** has to be on for this page to work, because look-alikes are found from what Visual search has read.

**How alike they must be** sets the photo distance under Advanced:

| Choice | What it means | Photo distance |
| --- | --- | --- |
| **Nearly identical** | Only photos that are almost the same picture, such as a copy saved again by another app | 0.004 |
| **Balanced** (default) | Bursts and copies saved again, but not different photos of the same scene | 0.01 |
| **Loosely alike** | Also photos taken a moment apart. More groups, and more of them will not really be duplicates | 0.03 |

A number set under Advanced that matches none of these shows as **Custom**; choose one of the three to replace it.

:::note[This only changes photos compared from now on]
When you change how alike photos must be, the page says how many photos would be compared again and about how long that takes. **Save and start now** compares every photo again straight away; **Save and start tonight** does it in the overnight schedule. Groups you have already dealt with stay dealt with, and the review keeps showing today's groups until the comparison finishes. **Undo** on the notice puts the saved number back before you save.
:::

**Check one photo or video…** looks for the look-alikes of one photo straight away; any it finds go to Things to fix.

**Camera originals are suggested first** (`machineLearning.duplicateDetection.preferOriginalFormat`, always on): RAW, then HEIC, over copies that were saved again. You still decide. See [Suggested keepers](https://frameleaf.app/docs/using/duplicates/#best-copy).

**Compare whole videos** (`machineLearning.duplicateDetection.enhancedVideo.enabled`, on). Before calling two videos alike, Frameleaf lines up their timelines picture by picture, so a shared title screen or intro is not enough. A trimmed or re-saved copy matches when it still holds most of the video. Off: videos are matched on one picture alone.

**Uses what Visual search has read**: look-alikes are found from the same reading of each photo, so if Visual search is turned off, no new ones are found. Your choices here are kept, and the page says so; **Visual search** opens its page in Search & intelligence.

**Advanced: how alike, in numbers**. "Distance" is how different two pictures are: 0 means the same picture, and bigger numbers mean less alike.

- **Photo distance** (`machineLearning.duplicateDetection.maxDistance`, 0.01), from 0.001 to 0.1. Lower finds only very close matches; higher finds more. Set by **How alike they must be**.
- **How much of a video must match** (`machineLearning.duplicateDetection.enhancedVideo.minMatchFraction`, 70%), from 50 to 100%. Of the part two videos have in common, this is how much must line up picture by picture. Higher is stricter: a trimmed copy may stop matching.
- **How different the pictures may look** (`machineLearning.duplicateDetection.enhancedVideo.maxHashDistance`, 8), from 0 to 16, in five steps: **Very strict** (only copies that look the same, picture for picture), **Strict**, **Balanced, the usual choice** (a copy saved at another size or quality still matches), **Loose** and **Very loose** (different videos that only look alike may be grouped together).

The video numbers can only be changed while **Compare whole videos** is on.

### Search and recognition progress

What Frameleaf has finished reading in your photos, and what is still waiting. The status says **Nothing is waiting to be read**, how many photos it is still reading (you can keep using Frameleaf, and results appear as they are ready), or **Reading is paused**. **Finish now** appears when work is held: it resumes paused work and queues the photo details still to read, and the server is busier until it finishes.

**What is still to read** has one line for each thing Frameleaf reads: **Visual search**, **Faces & identity**, **Text, documents & receipts**, **Descriptions & tags**, **Photo details** (dates, places and camera details from each file) and **Look-alike photos**. Each says **Nothing waiting**, how many are left to read (**Reading now** or **Waiting its turn**), **Paused**, how many couldn't be read (details in the Job manager), or **Off** when the feature is turned off in its settings. **Open** goes to that feature's page, and **Redo one…** reads one photo or video you pick again straight away with today's settings. A line says **Waiting for a computer** when the computer chosen for that work isn't answering.

**When this work runs**: **Runs in the overnight schedule**, because new photos are read soon after they arrive and anything still waiting is picked up overnight, so the server stays quick during the day; **Overnight schedule** opens the nightly settings. **Where this work runs** is this server, or another computer you have set up to help; **Where work runs** opens the routing page. See [Nightly tasks](https://frameleaf.app/docs/admin/jobs/#nightly-tasks) and [Workers and where jobs run](https://frameleaf.app/docs/admin/workers/).

#### When photos are read again

A change in Search & intelligence can mean reading photos again.

**Keep what I wrote myself** (`libraryCare.manualMetadata`, on). Writing captions again only replaces what Frameleaf wrote, never a description someone typed. Off: a description written by hand can be replaced the next time captions are written again.

:::caution[Descriptions written by hand can now be replaced]
With **Keep what I wrote myself** off, the next time captions are written again, for one photo or for the whole library, Frameleaf's caption takes the place of anything a person typed. Turn it back on to keep them.
:::

**Redo only what changed** (`libraryCare.incrementalEnrichment`, on). Renaming someone updates their photos without checking the rest again.

## Computers & background work

The area opens on a short status: whether the computers that do the work are answering, and whether the background work is keeping up. Its pages are **Computers**, **Background work**, **Graphics card check** and **Overnight schedule**. **Computers** includes **Where work runs**, whose photos each computer works on, and each person's choice about Frameleaf Cloud. Computers and the graphics card check are covered in [Workers and where jobs run](https://frameleaf.app/docs/admin/workers/) and [Hardware acceleration](https://frameleaf.app/docs/admin/hardware-acceleration/).

<span id="job-manager"></span>

### Background work

The page has two views, **Everyday** and **Advanced**; see [Jobs and queues](https://frameleaf.app/docs/admin/jobs/#where-to-manage-jobs). Its settings:

- **How hard this server works** (`job.*.concurrency`): **Light**, **Balanced** or **Fast** sets how many of each kind of job run at once. It's saved through the same review draft. Higher concurrency gets more done per hour, though each single action takes as long as before.
- **When heavy work runs**: **Overnight** or **Any time**. It's the same setting as **Save heavy background work for the night** in [Overnight schedule](#overnight-schedule) (`nightlyTasks.quietHours`, on).
- **Jobs running at once** (`job.capacity`, **Automatic**): the most jobs the server works on together, across every task. Choose **Automatic**, which suits most servers, or a number from 1 to 32. If the server was started with `FRAMELEAF_JOB_CAPACITY`, that number is used and can't be changed here.
- **Each task’s own number**: in **Advanced**, **How many run at once** sets one task by hand. Finding faces, preparing photos for search, recognising people and converting videos are heavy, so raise them in small steps. If a task's number is higher than **Jobs running at once** allows, the page says so and offers to raise it.

:::caution
Don't raise concurrency, especially for thumbnails, beyond the number of CPU cores you have. It slows down the web app and apps without making thumbnails any faster.
:::

| Job | Default concurrency (**Balanced**) |
| --- | --- |
| Making thumbnails | `3` |
| Reading photo details | `5` |
| Converting videos | `1` |
| Finding faces | `2` |
| Preparing photos for search | `2` |
| Reading text in photos | `1` |
| Library scans, photo detail files, updating search, moving files, sending notifications, housekeeping | `5` each |

Recognising people always runs one at a time, because the clustering it uses isn't parallel. See [Jobs and queues](https://frameleaf.app/docs/admin/jobs/) for what each kind of work does.

### Overnight schedule

The server's own night work, in one place: when it runs, what it does, and whether heavy background work waits for it. The page opens on how last night went, then **Tonight, in order** and **Recent nights**. See [Nightly tasks](https://frameleaf.app/docs/admin/jobs/#nightly-tasks) for what each step does.

- **Start time** (`nightlyTasks.startTime`, midnight). When the night's work starts, on this server's clock. Night is best, because the steps read your whole disk.
- **Stop the night's work in the morning** (`nightlyTasks.stopTime`, 6:00 AM). No step starts after this time, and anything left carries on the next night. Turn it off (an empty value in the config file) to run every step to the end.
- **Run** (`nightlyTasks.days`, every night). **Every night**, or **Only some days** with the days the work starts on.
- **Save heavy background work for the night** (`nightlyTasks.quietHours`, on). Faces, pets, reading text, descriptions, Visual search, duplicates and converting videos wait for the start-to-stop window. Uploads and thumbnails never wait. See [Quiet hours](https://frameleaf.app/docs/admin/jobs/#quiet-hours).
- **Finish anything that didn't process** (`nightlyTasks.reprocessUnfinished`, on). Each night, checks for photos and videos that still need previews, details, search, faces, text or a playback copy, and queues what's missing.
- **Empty Trash and tidy up each night** (`nightlyTasks.databaseCleanup`, on). The first step, and the only one that removes anything for good. **Choose what this step does** has:
  - **Empty Trash and remove deleted accounts** (`nightlyTasks.emptyTrash`, on). If off, the step still tidies up, but Trash isn't emptied and keeps using space.
  - **Make missing thumbnails** (`nightlyTasks.missingThumbnails`, on).
  - **Group new faces** (`nightlyTasks.clusterNewFaces`, on). Adds new photos of people to the right person. See [People recognition](https://frameleaf.app/docs/using/people-recognition/#jobs).
  - **Prepare memories** (`nightlyTasks.generateMemories`, on). See [Memories](https://frameleaf.app/docs/using/memories/).
  - **Recount storage** (`nightlyTasks.syncQuotaUsage`, on). See [Storage quotas](https://frameleaf.app/docs/admin/users/#storage-quotas).
  - **Count the library and check phone backups** always runs. It keeps Library analytics up to date and notices a phone whose backup has stopped.
- **Different timing for one step** (`nightlyTasks.steps`). Each step can run **Every night, with the others**, **Once a week** on the **Once-a-week day** (`nightlyTasks.weeklyDay`, Sunday), or **Only when I start it**. A step set to run only when you start it leaves the order and runs with **Run now**. If that's the tidy-up step, Trash isn't emptied until you run it.
- **Advanced: clock**. Every time here, in Backup and in Library care uses this server's clock, set by **Time zone** in [Server name & welcome](#server-name--welcome).

**Run now** starts every step that's on, one after another, whatever its own timing. **Stop** ends tonight's run; the steps it didn't reach run at the usual time.

**Backups** keep a schedule of their own, set in Backup and shown here so the whole night is in one place. If the two overlap, only the steps that use the disk or the internet (checking folders, iCloud Photos, checking files) wait for the backups to finish. Emptying Trash never waits. If the start time is close to the backups, the page suggests starting one an hour or more after the other.

## Frameleaf Cloud

Frameleaf Cloud is optional. It adds remote access, cloud processing and cloud backup to your server, and the server works fully without it: local photos, albums, accounts and sign-in never depend on the link. The area has six pages, in this order: **Account & link**, **Plan**, **Licence**, **Remote access**, **Cloud processing** and **Cloud backup**. See [Frameleaf Cloud](https://frameleaf.app/docs/cloud/overview/) for what a plan includes, and [Your Frameleaf account](https://frameleaf.app/docs/cloud/account/) for the account itself.

Every control on these pages is written to the `frameleafCloud` group of the configuration. Most of them save as soon as you change them, with a notice such as "Remote access is on."; the ones that save with the rest of your settings say so below. On a server run from a configuration file the pages are read-only, like the rest of Settings.

### Account & link

The page opens on the link's state: **This server isn't linked to a Frameleaf account**, **Linked to** your account, or **Frameleaf Cloud ended this link**. Linking is free and optional. It is the first step for remote access, backups away from home and cloud processing, and nothing from your library is uploaded by linking. If whoever runs the server has turned Frameleaf Cloud off in its configuration, the page says **Frameleaf Cloud is turned off for this server**: nothing is sent to Frameleaf, and everything else works as usual.

**Link this server** starts the link. The page shows **Your code**, a QR code and the address to approve it on. Open that address on your phone or computer, sign in, and check that the code matches; only approve it if the key fingerprint matches too. Linking finishes by itself once the code is approved. **Get a new code** replaces a code that expired, **Cancel** stops the attempt, and **Clear this link** abandons one that did not finish. If your Frameleaf account keeps its data in another region than the one this server asked for, the page says so and offers **Link in the account's region**.

**What linking leads to** lists each extra with what else it needs: **Free with an account**, **Needs a licence**, **Needs a plan** or **Pay as you use it**. **Linking a server without a browser** explains the one-time link token; see [Link a server with no browser](https://frameleaf.app/docs/cloud/account/#link-a-server-with-no-browser).

Once linked, the page shows the account, the date it was linked, when Frameleaf last heard from this server and the region your data is kept in. **Manage on frameleaf.cloud** opens your account.

A notice says whether the Frameleaf apps find this server **Available anywhere** or **At home only**. Sign in to the Frameleaf app on iPhone, iPad or Android with your Frameleaf account and this server appears by itself; away from home the app connects directly when it can and through the Frameleaf relay otherwise. **Set up remote access** takes you to the Remote access page.

**What you can do from your Frameleaf account when you're away** has two switches. Your account can only ask: this server decides, and keeps a record of each request. They are kept with the link, not in the configuration:

- **Turn remote access on or off** lets you enable remote access from your Frameleaf account when you are away.
- **Start a cloud backup** lets the account site start a backup run. It can never read, change or delete backups.

**What this server sends** says what a check-in holds. **Sent**: how it is doing (its Frameleaf version, how long it has been running and whether it is healthy). **Also sent**: where to reach it (its addresses, and whether remote access is connected). **Never sent**: anything of yours, meaning photos, videos, thumbnails, metadata, names, accounts or usage. Check-ins happen every few minutes.

**Advanced**, under it, holds the rest:

- **Instance ID** is this server's ID, the same one used on Licence and Sign in with Frameleaf.
- **Key fingerprint** is what the approval page shows when you link.
- **Contact Frameleaf now**, with **Check in now**, contacts Frameleaf Cloud straight away. It happens by itself; use it after fixing a connection problem.
- **Refresh your plan automatically** picks up renewals and plan changes without a manual refresh.
- **Take the tour** opens the short tour of what a linked server can do.
- The exact list of what each check-in sends.

**Unlink this server**, with **Unlink…**, stops every cloud feature on this server; you can link again at any time. Before you confirm, the dialog lists what stops: remote access, cloud processing (queued jobs are cancelled and held AI credit is released), scheduled cloud backups (backups already made are kept, and this server can still open them), everyone's linked Frameleaf accounts and the plan. Licences stay, and local photos, albums, accounts and sign-in keep working exactly as before. Tick the box to confirm, then choose **Unlink server**. See [Unlink a server](https://frameleaf.app/docs/cloud/account/#unlink-a-server).

### Plan

Your library needs no plan. A Frameleaf Cloud plan adds remote access for everyone on this server and the storage for Cloud Backup, and it needs a Server licence on this server first. Local photos are never locked: if a plan ends, only remote access and cloud backup pause.

The status at the top says **No plan on this server**, **Frameleaf Cloud plan is active** with the account and the renewal date, **Your plan needs renewing** or **Your plan has ended**. With a plan, **Manage subscription** opens your Frameleaf account (**Update payment** when a payment didn't go through).

**What this plan gives** spells it out. With this plan: remote access for everyone on this server at a name of your own on frameleaf.net, and 1 TB of Cloud Backup storage. Not part of a plan: cloud processing, which is paid for as you use it from AI credit, and the licence, which is a one-time purchase. **What it costs** shows the monthly and yearly price for this server. Under them:

- **Your name on frameleaf.net** shows the address everyone reaches this server at, with **Choose a name…** or **Change name…**. See [Remote access](https://frameleaf.app/docs/cloud/remote-access/).
- **Cloud Backup**: the storage comes with the plan, and your licence decides who can use it. **Open Backup** goes to the Backup area.
- **Buddy Backup** needs a Server licence on both servers and a free Frameleaf account. The plan's only part is letting the two servers connect through Frameleaf when they can't reach each other directly.
- **More storage**: every plan includes 1 TB. If your backups grow past it, another 1 TB is added automatically, billed monthly even on a yearly plan.
- **Cloud processing** shows the AI credit left, with **Add AI credit**. It is paid for as you use it, with or without a plan.
- **Licence** says which licence this server has. Keys and licence files are added on the Licence page.
- **Stop using this plan on this server**, with **Stop using it here…**, takes the plan off this server only. Remote access turns off and cloud backups pause here. It does not cancel your subscription, which is managed in your Frameleaf account; use it when moving the plan to another server.
- **Last checked with Frameleaf** and **Came from** (**Frameleaf account**, or **Licence file (offline)**) say where the plan was read from. **Check for changes now**, with **Refresh**, asks again. Renewals and plan changes arrive by themselves; use it if you have just paid and nothing has shown up.

Without a plan, the page lists what a plan adds and the **Monthly** and **Yearly** choices, then **Continue to the Frameleaf store**. You pay in the Frameleaf store, never on this server, and this server picks up the plan by itself. A server that already has its licence pays less for the yearly plan. **What a plan doesn't include** lists cloud processing, the licence and storage past the included 1 TB. For the plans, their prices and what each includes, see [Plans and supporter licences](https://frameleaf.app/docs/cloud/overview/#plans-and-supporter-licences).

:::note[Your plan needs renewing]
When a payment doesn't go through, remote access and your Cloud Backup storage keep working until the date shown. Update your payment method in your Frameleaf account to avoid a pause. Once a plan has ended, remote access and cloud backup are paused; everything else on this server, including every photo, keeps working.
:::

### Licence

Frameleaf is free to self-host. Without a licence, your library and everything on this server keep working; only Frameleaf Cloud and backups away from home need one. A licence is one purchase: it never expires, has nothing to renew, and never locks your photos.

**What a licence gives** lists the same things on every page that mentions them:

- **Lets this server use Frameleaf Cloud.** You need a licence, Server or Individual, before you buy a Frameleaf Cloud plan or AI credit. The plan is what adds remote access and the storage for Cloud Backup.
- **A lower price for Frameleaf Cloud plans**, with one rate for a **Server licence** and a smaller one for an **Individual licence**, for as long as the licence stays on this server. The two are never added together. The rates are shown on the page.
- **Backups away from home.** A Server licence adds **Cloud Backup** and **Buddy Backup** for everyone on this server. An Individual licence adds Cloud Backup for one account.
- A **Supporter badge** beside the name of everyone the licence covers.
- **Yours for life.**

See [Licences, plans and credit](https://frameleaf.app/docs/cloud/account/#licences-plans-and-credit).

**Enter a licence key**. A licence bought from this server is added by itself. A key from an email or a gift is entered here, and only here. It looks like FL-XXXX-XXXX-XXXX, and Frameleaf tells you which kind it is before anything changes: **This is a Server licence**, which covers everyone on this server, or **This is an Individual licence**, which covers your own account only. Then choose **Activate**. A server with no Frameleaf Cloud address can't check a key, and installs a licence file instead.

**A server with no internet connection** installs a **Licence file**, a file ending in `.lic` made for this server only. On another device, download the file for this server from your Frameleaf account, using **This server’s ID** (**Copy** copies it), then **Choose licence file…** here. The file can carry a licence and a Frameleaf Cloud plan, and cloud features follow its dates.

Once licensed, **Your licence** shows the **Licence key** (the full key is in the email it came in), its **Kind**, when it was **Added**, who it covers (**Everyone**, or one person only), what's **Included**, and when it was **Last checked with Frameleaf**. Frameleaf checks once a day on its own; **Check now** checks again. If a plan's renewal didn't go through, the page says how long remote access and Cloud Backup keep working.

**Remove from this server…** stops Cloud Backup and Buddy Backup for everyone the licence covered, the supporter badge and the plan discount. Backups already made are kept, the licence stays yours to add again here or on another server, a Frameleaf Cloud plan is not cancelled, and your photos are not affected. **Remove your Individual licence…** does the same for an Individual licence on your own account. **Enter another licence key** adds a second one; a Server licence key covers everyone.

### Remote access

Reach this server from anywhere, with nothing to set up on your router. Nobody but you and the people you invited can see inside the connection. Remote access needs a linked server and is part of Frameleaf Cloud. See [Remote access](https://frameleaf.app/docs/cloud/remote-access/) for the whole picture, and [Remote access without Frameleaf Cloud](https://frameleaf.app/docs/admin/remote-access/) for a VPN or your own reverse proxy instead.

The status at the top says **Remote access is off**, **Remote access is starting** (the server is getting its address and certificate, which takes a minute or two), **Remote access is on and working**, **Remote access is working, but slower** once the month's allowance is used up, or **This server can’t be reached from outside your home**.

**Let people reach this server away from home** (`frameleafCloud.remoteAccess.enabled`, off). People away from home sign in with their Frameleaf account. Turning this off disconnects anyone away from home straight away.

**How devices connect** (`frameleafCloud.remoteAccess.mode`) chooses the route:

| Choice | What it means | Value |
| --- | --- | --- |
| **Always through Frameleaf** | Works everywhere, at up to 8 Mbit/s: enough to browse and watch. Counts toward your monthly allowance | `relay` |
| **Straight to your home when possible** | Faster, and doesn't use your monthly allowance. Frameleaf sets up your router for you. When that isn't possible, the connection goes through Frameleaf instead | `relay-and-direct` |

Under the choice, **Right now:** says which route is in use, for example that devices connect straight to your home, or that your internet provider doesn't allow direct connections, so everything goes through Frameleaf. Without a Frameleaf Cloud plan, this server is reached only straight to your home, and the Frameleaf apps don't work away from home.

**This month through Frameleaf** is a meter of what you have used of the month's allowance. If it runs out, remote access slows down until the 1st. It never stops, and connections straight to your home aren't slowed. See [Limits](https://frameleaf.app/docs/cloud/remote-access/#limits).

**Door on your router** appears when devices may connect straight to your home. A port is a numbered door on your router; devices away from home come in through it.

- **I set up my router myself** (`frameleafCloud.remoteAccess.portMapping`, off). Turn this on if you forward the port by hand. Frameleaf then stops asking your router to do it.
- **Port you forwarded** (`frameleafCloud.remoteAccess.directPort`, 2443), a number between 1024 and 65535.
- If your internet provider shares one public address, or the router can't be reached from the server's container, the page says so. Remote access keeps working through Frameleaf.

**Your public address** is the address to share or scan on a phone. It appears once remote access is on and this server has its certificate. **Show QR code** and **Download QR code** give it as a code to scan. With a plan, **Your name on frameleaf.net** lets you choose the name in that address; the technical address still reaches this server and never changes. See [Your server's addresses](https://frameleaf.app/docs/cloud/remote-access/#your-servers-addresses).

**The address in links you share** (`frameleafCloud.remoteAccess.publicUrl`, `frameleaf`) is used in shared links, emails and when people sign in: **Your Frameleaf address** or **Your own domain**. The page shows what links you share will start with.

**Use your own domain** reaches this server at an address on a domain you own, such as photos.example.com. Frameleaf still carries the traffic and this server still holds the certificate; it comes with a Frameleaf Cloud plan.

- **Custom hostname** (`frameleafCloud.remoteAccess.customHostname.host`, empty) is a subdomain you control. The page lists the two DNS records to add at your domain provider, with their **Type**, **Name** and what each **Points to**: one sends visitors to your server through Frameleaf, the other lets this server renew its own certificate for your domain.
- **Check my domain** looks for the two records. Nothing changes until they are found, and DNS changes can take up to an hour. Once verified, the hostname points to this server and its certificate is issued and renewed here. **Remove domain** goes back to the Frameleaf address.
- **Another address** (`server.externalDomain`) is only for when you run your own gateway in front of this server. Type the full address people should use. It's saved with your other settings changes, and it's the same setting as **Public server URL** in [Server name & welcome](#server-name--welcome).

See [Use your own domain](https://frameleaf.app/docs/cloud/remote-access/#use-your-own-domain).

<span id="public-server-url"></span>

**Signing in away from home** applies to every connection from outside your home, whichever way it arrives (`frameleafCloud.remoteAccess.allowPasswordOverRelay`, off):

- **Frameleaf account only (recommended)**: everyone away from home signs in with their Frameleaf account.
- **Frameleaf account or password**: also lets people type this server's password away from home. Passwords are easier to guess, or to be tricked out of. Keep this only for someone who can't use a Frameleaf account.

Links you shared publicly still open without signing in. At home, people keep signing in however they do now.

**Let people download full-size originals through Frameleaf** (`frameleafCloud.remoteAccess.allowOriginalsOverRelay`, off). Originals are large and use the allowance quickly. Photos and videos always open and play either way.

:::caution[Turning these on asks you to confirm]
Letting people download originals means anyone signed in away from home could download full-size originals, including where each photo was taken, and large downloads can use up the month's allowance quickly. Letting people sign in with a password away from home means remote visitors could sign in with only a password, without Frameleaf account protection such as passkeys and new-device checks, so leaked or reused passwords become a direct way in. Choose **Keep off** or **Turn on**.
:::

**Connection details** has the technical side: the **Frameleaf region**, the response time, since when the server has been connected, how much was sent through Frameleaf this month, the router mapping in use (**UPnP**, **NAT-PMP** or **Forwarded manually**), and the **Certificate**, which **Renews** automatically and is issued to this server only; the private key never leaves it. **Run a connection test** (or **Check it now**) checks five things and says which passed: **Security certificate**, **This server is listening**, **A test request got through**, **Through Frameleaf** and **Straight to your home**.

### Cloud processing

Your own computers stay the default, and nothing goes to the cloud without asking. Cloud processing is pay as you go: it needs a linked server and AI credit, but no plan. Each job still shows its model and cost before it starts. See [Cloud GPU](https://frameleaf.app/docs/cloud/cloud-gpu/).

The status at the top says **Cloud processing needs a linked server**, **Cloud processing is off**, **Cloud processing is on** with how much AI credit there is to spend and what was spent today, or **AI credit is almost gone**. When the processing terms have changed, nothing goes to Frameleaf's computers until you **Review terms**.

**Use Frameleaf Cloud for chosen jobs** (`frameleafCloud.cloudMl.enabled`, off). Turning this off cancels waiting cloud jobs and returns their held credit. The first time you turn it on, the processing terms open; once accepted, you save to turn cloud processing on.

**What leaves this server** says it in one line: smaller copies of the photos and videos you choose, with location and camera details removed. Never your originals, faces, or the names you gave people. **What is sent, in detail** lists what you accepted: **Terms** (the version accepted, or **Not accepted**), **Names in descriptions** (**Only names written in a photo**, or **Left out**), **Medical signals** (**Allowed in descriptions**, or **Never described**), **Smart search** and **Faces** (whether previews can be sent, or the work is **Prepared on this server** and **Found and recognised on this server**). Faces on Frameleaf Cloud are turned on with their own consent in the processing terms, not with a setting (`frameleafCloud.cloudMl.faces.enabled` is always off). **Review terms and features** opens them again. See [Choose what leaves your server](https://frameleaf.app/docs/cloud/cloud-gpu/#choose-what-leaves-your-server).

**What may use the cloud** shows which kinds of work may use Frameleaf's computers and which stay on your own. It's chosen on one page, together with which of your own computers does what: **Change where work runs** opens **Where work runs** on [Computers](https://frameleaf.app/docs/admin/workers/#choose-where-each-kind-of-work-runs) (`frameleafCloud.cloudMl.routing`). **Text, documents & receipts** always stays at home. **Visual search** and **Faces & identity** can use Frameleaf Cloud only with the same model as this server; see [Search and faces on Frameleaf Cloud](https://frameleaf.app/docs/admin/workers/#search-and-faces-on-frameleaf-cloud). Each person can also keep their own photos at home; see [Each person's photos](https://frameleaf.app/docs/admin/workers/#each-persons-photos).

| Kind of work | What it does | Key |
| --- | --- | --- |
| **Descriptions & tags** | Captions, tags and moments for Library care | `routing.descriptions` |
| **Enhance & upscale** | Sharper, larger photos from the editor | `routing.upscale` |
| **AI restoration** | Cleans up and sharpens old videos, in the editor and Studio | `routing.restoration` |
| **Transcripts & captions** | Turns speech in a video into text and captions | `routing.studio` |
| **Smooth motion** | Higher frame rates and smooth slow motion for videos | `routing.interpolation` |

For a row set to **Ask me each time**, the place suggested first is `frameleafCloud.cloudMl.startWith` (**This server**), set on **Computers** under **Finer choices**.

**Models**. Each kind of work chooses its model on its own settings page, with a slider from lighter to heavier models. A blue model runs on Frameleaf Cloud, and the price shows before anything is sent. **Models and prices** lists them, and **Estimate a cost** shows, for a **Model** and a **Quantity**, the likely cost, the most it is likely to cost, and what is held until the job settles. You pay for the GPU time a job uses, per second, plus a start fee for each computer that loads the model.

**Waiting for Frameleaf Cloud** lists work that hasn't started yet, and why: new photos waiting to join the next batch (waiting for a batch keeps the start fee down), photos waiting because describing new photos automatically is off, because Frameleaf Cloud is turned off, or because it doesn't offer the model this server uses.

**Spending**. AI credit is paid for in advance, and you see the price of cloud work before it starts. Nothing is ever charged automatically unless you turn on automatic top-up.

- **AI credit** shows what there is to spend and what is set aside for work that is running; whatever isn't used comes back. **Add credit** opens a top-up on frameleaf.cloud in a new tab, with card fees included so the full amount becomes AI credit.
- **Daily limit** is the most Frameleaf spends in one day, on everything. Work that would pass it waits until tomorrow. Raising it happens in your Frameleaf account; this server can only lower it.
- **Top up automatically** adds credit with the payment method saved on frameleaf.cloud when available credit runs low. It's turned on in your Frameleaf account; this server can only turn it off.
- **Describe new photos automatically** (`frameleafCloud.cloudMl.autoDescribe.enabled`, off). New photos get a description as they arrive, without asking each time. It needs cloud processing on and the current terms accepted.
- **Limit for new photos** (`frameleafCloud.cloudMl.autoDescribe.dailyBudgetUsd`, $2.00 a day) is part of the daily limit, not on top of it. When it's reached, the rest wait until tomorrow.
- **Allow someone else** (`frameleafCloud.cloudMl.spenders`, nobody). Only administrators can confirm Frameleaf Cloud jobs until you allow other people here, each with an optional monthly limit for the cloud work they start themselves. A monthly limit counts what was settled this month plus the AI credit set aside for their running jobs, and is checked when a job is confirmed.
- **What these add up to** says the limits back in plain sentences.

See [How you pay](https://frameleaf.app/docs/cloud/cloud-gpu/#how-you-pay) and [Automatic descriptions](https://frameleaf.app/docs/cloud/cloud-gpu/#automatic-descriptions).

**Describe your library…** describes the photos that have no description yet, in batches on Frameleaf Cloud. It shows how many photos, with which model, what it is likely to cost and what is held, before anything is sent.

**Recent cloud work** lists each job with its estimate next to what it actually cost. **Open job manager** goes to Background work.

### Cloud backup

Back up originals and the database to an encrypted bucket that only this server uses. Cloud backup needs a linked server and a Frameleaf Cloud plan; your photos and every local feature keep working without one. Only new or changed files upload, so a photo you have twice is stored once; every file is encrypted on this server before it is uploaded, and you choose at setup who keeps the key; backups from different servers never mix. The status at the top is **Off** until it is set up. See [Cloud backup](https://frameleaf.app/docs/cloud/cloud-backup/), and [Buddy Backup](https://frameleaf.app/docs/cloud/buddy-backup/) for backing up to another home server instead.

**Set up cloud backup** (`frameleafCloud.cloudBackup.enabled`, off) walks through four steps. The destination and key choice can't be changed later without starting a new backup.

1. **Destination** (`frameleafCloud.cloudBackup.target`, `off`): **Frameleaf-managed storage** (`managed`), included with your plan, where Frameleaf creates a bucket just for this server; or **Your own S3-compatible bucket** (`byo-s3`), an empty bucket with versioning turned on, on a provider that supports customer-provided encryption keys (SSE-C). Backups are encrypted on your server either way; SSE-C only protects the bucket's claim file. For your own bucket, enter the **Storage address** (`frameleafCloud.cloudBackup.s3.endpoint`, HTTPS), **Region** (`frameleafCloud.cloudBackup.s3.region`, empty reads it from the storage address or uses us-east-1), **Bucket** (`frameleafCloud.cloudBackup.s3.bucket`), **Access key ID** (`frameleafCloud.cloudBackup.s3.accessKeyId`) and **Secret access key** (`frameleafCloud.cloudBackup.s3.secretAccessKey`, stored on this server and never shown again), then **Check bucket**.
2. **Encryption key** (`frameleafCloud.cloudBackup.keyMode`, `server`). New backups are encrypted on this server before upload, with keys the storage provider never receives:

   | Choice | What it means | Value |
   | --- | --- | --- |
   | **Generate a key for me** (default) | This server creates the key and keeps it next to its identity. You save a recovery kit in the next step. If you lose this server and the recovery kit, the backup cannot be read | `server` |
   | **I'll maintain my own key**, with **Keep a copy on this server** on | A key is created in this browser and you download it. Scheduled backups run unattended; the copy stays on this server and is never sent to Frameleaf Cloud | `own-stored` |
   | **I'll maintain my own key**, with **Keep a copy on this server** off | The key is never saved. After every restart backups pause until someone enters it, and restores always need the key file | `own-memory` |

   With your own key you must **Download key file** and confirm **I saved the key file somewhere other than this server** before you can continue, and type "I understand" to confirm that a lost key means every backup in this bucket is permanently unreadable. With a generated key, **Also keep an encrypted copy with Frameleaf** (`frameleafCloud.cloudBackup.escrow`, off) stores a copy protected by a passphrase of 12 characters or more that only you know; Frameleaf cannot read it, and it helps if you lose this server but still remember the passphrase.
3. **Recovery kit** (generated key only) is shown once: the server instance, bucket, key fingerprint and recovery code. **Download** or **Print** it and keep it somewhere safe and offline, then confirm **I saved or printed the recovery kit**.
4. **Turn on backup**, or **Claim bucket** and then **Finish setup** for your own bucket. Each server uses its own bucket, and a bucket belongs to exactly one server: Frameleaf writes a marker with this server's instance ID so no other server can use it.

See [Choose how the key is kept](https://frameleaf.app/docs/cloud/cloud-backup/#choose-how-the-key-is-kept).

Once set up, **At a glance** shows the **Last backup** (how many new or changed files, and their size), when it was **Last checked** and whether everything could be read back, and where it is **Stored in**: **Frameleaf-managed storage**, included with your plan, where Frameleaf can see file names and sizes but never contents; or **Your own bucket**, whose credentials and key Frameleaf never holds. **Storage used** is a meter against your plan, with any extra 1 TB blocks added to it, or the size and number of unique files billed by your provider. **Back up now** starts a run; progress and a **Cancel** follow here and in Activity. A run that stops shows why, and a key that is not loaded after a restart shows **Unlock**, which loads the key file for this session only.

**Also backed up** applies to everyone on this server. **Library data** (albums, people, edits, tags and settings) is **Always** backed up, and always the whole library.

- **Thumbnails and previews** (`frameleafCloud.cloudBackup.include.thumbs`, off). Restores show pictures sooner, at the cost of more storage.
- **Transcoded videos** (`frameleafCloud.cloudBackup.include.encodedVideo`, off). Restored videos play straight away, at the cost of more storage.

**Older versions** let you go back if you deleted or changed something by mistake. Nothing still needed by a kept version is ever removed.

- **Keep daily runs** (`frameleafCloud.cloudBackup.retention.keepDaily`, 7 days), from 1 to 90.
- **Keep weekly runs** (`frameleafCloud.cloudBackup.retention.keepWeekly`, 4 weeks), from 0 to 52.
- **Keep monthly runs** (`frameleafCloud.cloudBackup.retention.keepMonthly`, 12 months), from 0 to 120.

**Safety**:

- **Check the backups** (`frameleafCloud.cloudBackup.verifyWeekly`, on). Every week a sample of the backed-up files is fetched and checked, and every month each file is confirmed to be there. Anything missing or damaged is uploaded again.
- **Check the backup now**, with **Verify**, reads back a sample of the backed-up files to make sure they can be restored.
- **Recovery file**, with **Update recovery file**: choose your saved recovery file to download it again with your latest backups added. A new server needs this to open your newest backup, so do it after backing up and keep the file somewhere safe.
- **Recovery copy is out of date** appears when your backup key changed after the copy with Frameleaf was stored. **Update recovery copy** stores it again with your passphrase.
- **Get something back**, with **Restore…**, opens the Backup area's restore page, where you restore photos, albums or the whole library from this backup. See [Restore](https://frameleaf.app/docs/cloud/cloud-backup/#restore).

When scheduled runs start (`frameleafCloud.cloudBackup.schedule.cronExpression`, 3:00 every night) is set once for every backup on **Backup**, then **When backups run**, together with the database backup; backups run one after another, never at the same time.

The included files, the older versions and the safety check save with your other settings changes. **Technical details** shows the **Encryption** (on this server before upload, with keys only you hold), the **Bucket**, its **Region** (your own bucket only), which **Key** choice is in use, the **Key fingerprint**, and whether a **Recovery copy** is kept with Frameleaf, protected by a passphrase only you know.

**Turn off cloud backup**, with **Turn off backup…**, stops scheduled runs. The bucket and its backups are kept, and you still need this key to read them, so keep your recovery kit or key file. Delete the bucket in your Frameleaf account, or at your storage provider, when you no longer need it.

## Who can sign in

How people sign in to this server, at home and away. The area has two pages, **Sign-in methods** and **Sign in with Frameleaf**. Each person's own settings are in **Your sign-in & privacy** under Personal: their password, [passkeys](https://frameleaf.app/docs/using/account-settings/#passkeys), Locked PIN, linked sign-in provider, Always Locked rules, signed-in devices and [API keys](https://frameleaf.app/docs/api/overview/#create-an-api-key). What Locked hides, and who can open it, is explained in [Locked and private content](https://frameleaf.app/docs/using/private-content/); an administrator can reset someone's password or PIN under [Users](https://frameleaf.app/docs/admin/users/#sign-in-and-security).

### Sign-in methods

The page starts with the answer, such as **People can sign in two ways**, with which ones, or **Nobody can sign in** if every way is off. Changes on this page wait in your draft until you select **Save changes**. When the server's settings come from a configuration file, every control here is read-only. The full walkthrough, with provider examples, is [Sign-in and OAuth](https://frameleaf.app/docs/admin/sign-in-and-oauth/).

#### Ways to sign in

- **Password** (`passwordLogin.enabled`, on). Each person's own password. Don't turn this off until an administrator has signed in another way. While it's off, the page warns **Password sign-in is off**: if Frameleaf Cloud or your provider is unreachable, nobody can sign in at home until it's back.
- **Frameleaf account** shows **On** once this server is linked to Frameleaf, and **Off** until then. It's what people use away from home. **Open** goes to [Sign in with Frameleaf](#sign-in-with-frameleaf).
- **Another sign-in provider** (`oauth.enabled`, off). For a household or organisation that already runs its own sign-in, such as Google Workspace. Most homes leave this off. Turning it on shows the two groups below.

#### Require a passkey or two-step

A passkey by itself, or any two of password, emailed code and authenticator code.

**Who must** (`signInPolicy.require`, **Administrators away from home**) also offers **Everyone away from home** and **Everyone, everywhere**. Everyone else can still sign in with one step. Choosing **Everyone, everywhere** needs password sign-in on and a passkey, or a password with two-step sign-in, on your own account first; otherwise saving is refused. `reset-sign-in-policy` on the [command line](https://frameleaf.app/docs/admin/server-commands/) puts it back to the default.

**Apply to older apps too** (`signInPolicy.applyToOlderApps`, off). Older apps and sessions that were signed in before this setting keep working as they did until you turn this on.

What each choice means is in [Require a passkey or two-step](https://frameleaf.app/docs/admin/sign-in-and-oauth/#require-a-passkey-or-two-step).

<span id="oauth"></span>

#### Connect your provider

Three things your sign-in provider gives you when you add Frameleaf to it:

- **Provider address (Issuer URL)** (`oauth.issuerUrl`, empty, required). The address your provider gives for sign-in, such as `https://accounts.google.com`. `/.well-known/openid-configuration` is added for you if you leave it off.
- **Client ID** (`oauth.clientId`, empty, required). The name your provider knows Frameleaf by.
- **OAuth client secret** (`oauth.clientSecret`) is a credential row: it shows **Stored** or **Not set**, never the value. **Replace credential** saves a new secret on its own, straight away, outside the settings draft; **Clear** removes it.
- **Check the connection**: **Check** asks the provider to introduce itself, and says **Found your provider** with its name, or what went wrong. Nothing is saved until it answers.
- **Addresses to allow at your provider** lists the three addresses your provider asks for, ready to copy: **Signing in on the web**, **Connecting an account you already have** and **Signing in on the Frameleaf app**.

#### Accounts from your provider

- **Create accounts automatically** (`oauth.autoRegister`, on). The first time someone signs in through your provider, they get an account here. Off: only people you've added can sign in. Creating an account also needs the provider to say the email address is verified; see [Verified email addresses](https://frameleaf.app/docs/admin/sign-in-and-oauth/#verified-email-addresses).
- **Space for new people** (`user.newUserStorageQuota`, no limit) is set once, under **Users**, for every way an account is made: **Open Users**. In the config file, `oauth.defaultStorageQuota` (empty) can still set a limit in GB for accounts the provider creates when it sends none.
- **Words on the sign-in button** (`oauth.buttonText`, `Sign in with your provider`). What everyone sees on the sign-in page.

The **Advanced** group holds the rest. This kind of sign-in is called OpenID Connect, and every setting here already has a value that works with most providers:

- **How Frameleaf proves itself** (`oauth.tokenEndpointAuthMethod`, `client_secret_post`) appears once a secret is stored: **Client secret in the request** or **Client secret in the request header**. Use the method your provider asks for.
- **Information requested** (`oauth.scope`, `openid email profile`). What Frameleaf asks the provider for, such as name and email.
- **Signature on the sign-in token** (`oauth.signingAlgorithm`, `RS256`) and **Signature on profile details** (`oauth.profileSigningAlgorithm`, `none`). Use the type your provider asks for; the second is only needed if your provider signs profile details.
- **What the provider asks each time** (`oauth.prompt`, empty). The prompt parameter, for example `select_account`, `login` or `consent`.
- **Sign-out address** (`oauth.endSessionEndpoint`, empty). People are sent to this address when they sign out.
- **Wait for the provider** (`oauth.timeout`, 30 seconds). How long Frameleaf waits for your provider before giving up.
- **Allow a provider without a valid security certificate** (`oauth.allowInsecureRequests`, off). Only for a provider on your own home network. Anyone on the way could read the sign-in, so never use it across the internet.
- **Go straight to the provider** (`oauth.autoLaunch`, off). Skips Frameleaf's sign-in page and opens your provider's. To reach the normal sign-in page anyway, see [Auto launch](https://frameleaf.app/docs/admin/sign-in-and-oauth/#auto-launch).
- **Folder name from provider** (`oauth.storageLabelClaim`, `preferred_username`) sets the person's folder name on disk from this claim. See [Storage labels](https://frameleaf.app/docs/admin/users/#storage-labels).
- **Administrator from provider** (`oauth.roleClaim`, `frameleaf_role`) makes someone an administrator when this claim says `admin`. The claim may be `user` or `admin`.
- **Space limit from provider** (`oauth.storageQuotaClaim`, `frameleaf_quota`) sets the person's space from this claim, a number of GB. See [Storage quotas](https://frameleaf.app/docs/admin/users/#storage-quotas).
- **Account Management URL** (`oauth.accountManagementUrl`, empty). Where in your provider a person can manage their own profile.
- **Sign-in address for an older app** (`oauth.mobileOverrideEnabled`, off). Turn it on when your provider doesn't allow an app address like `frameleaf-auth:///oauth-callback`. **Mobile redirect URI** (`oauth.mobileRedirectUri`) must then be this server's `/api/oauth/frameleaf-mobile-redirect` address, which forwards the sign-in to the app. See [Mobile redirect override](https://frameleaf.app/docs/admin/sign-in-and-oauth/#mobile-redirect-override).
- **Changing to a different provider?** **Disconnect everyone…** disconnects every account from this provider first. Their accounts and photos stay. The page asks you to confirm, because it can't be undone.

The folder name, administrator and space claims are read when an account is created. Changing them at the provider later doesn't change the account; edit it under **Users** instead.

:::caution[An override address that isn't this server's]
If the older-app address points anywhere else, the page says so in red instead of showing an address: the Frameleaf app can't sign in with this override. Use this server's `/api/oauth/frameleaf-mobile-redirect` address and allow it with your identity provider.
:::

:::note[Behind a reverse proxy]
The provider sends people back to the address they signed in from, so the proxy has to pass the original host and scheme through. See [Reverse proxy](https://frameleaf.app/docs/admin/reverse-proxy/#what-every-proxy-needs).
:::

#### Registered apps

Apps that can ask people on this server for access. Each person chooses what they allow. See [Connected apps](https://frameleaf.app/docs/admin/connected-apps/).

- **Let new apps register themselves** (`connectedApps.allowRegistration`, on). AI assistants such as Claude and ChatGPT add themselves when someone connects them. Each person still has to choose **Allow** before an app can see anything. Turn this off to allow only apps that are already registered.
- **AI agents (MCP)** (`connectedApps.allowMcp`, on). Lets people connect AI agents to their library through MCP. Turning this off also stops existing agents from using the library.

#### If nobody can sign in

Whoever can reach the computer Frameleaf runs on can always get back in, and nothing in your library is touched. The page lists the three steps, and **Show the commands** gives the two commands: `frameleaf-admin enable-password-login` turns password sign-in back on for everyone, and `frameleaf-admin reset-admin-password` sets a new password for the first administrator. Then sign in and check which ways to sign in are on. If only one person is locked out, reset their password from **Users** instead. See [Server commands](https://frameleaf.app/docs/admin/server-commands/).

### Sign in with Frameleaf

Let people sign in with their Frameleaf account, which is what they use away from home. It works alongside passwords and your own provider. This page saves each change by itself, not through the settings draft.

The page starts with who can use it: **Everyone can sign in with Frameleaf**, how many of the people here can, or **Sign in with Frameleaf isn’t available yet** until the server is linked (**Link this server**; see [Link a server](https://frameleaf.app/docs/cloud/account/#link-a-server)).

- **Who has linked** lists each person as **Linked** or **Not yet**. Someone who hasn't linked **Can only sign in at home**. Each person links their own Frameleaf account, from their own sign-in settings; **Remind** emails them a link to those settings (it needs [email](https://frameleaf.app/docs/admin/email/) and a public address for this server), and **Link yours** opens your own.
- **Where it is used**: away from home, people sign in with their Frameleaf account; **Change in Remote access** opens [Remote access](#remote-access). **Offer it at home too** (`frameleafCloud.signIn.showOnLocalLogin`, off) adds a "Sign in with Frameleaf" button to the sign-in page at home. Passwords stay available. It reads **Link this server first.** until the server is linked.
- **Words on the button** (`frameleafCloud.signIn.buttonText`) is what the button on the sign-in page says. Edit it and select **Save**.
- **Space for people you invite** is set once, under **Users**, for every way an account is made. See [Space for new people](https://frameleaf.app/docs/admin/users/#space-for-new-people).
- **Your own OpenID provider** opens Sign-in methods above.
- **Signs in through** names the Frameleaf service that checks who people are, and **Server ID** is the same ID shown on **Account & link** and **Licence**. There is no client secret to manage: the server proves itself with its own key.

## Notifications

The area lists **Emails you receive**, every account's own choice of which emails to get (see [Email notifications](https://frameleaf.app/docs/using/account-settings/#notifications)), **What needs your attention**, an administrator's view of a full drive, a missed backup, stopped work or a new version, and **Email delivery**, the server's settings below. For setting up each provider step by step see [Email](https://frameleaf.app/docs/admin/email/).

### Email delivery

The page opens on **Email status**: **Email is not set up** or **Email is turned off** (nothing is sent; invitations and album updates appear in the app only), **Email stopped working** (Google or Microsoft is asking you to sign in again), or **Email is set up**, with the address this server sends from.

#### Which email should Frameleaf send from?

Pick your email provider and Frameleaf fills in the rest. The tiles are **Gmail** (Gmail and Google Workspace), **iCloud Mail** (icloud.com, me.com and mac.com), **Yahoo Mail** (yahoo.com and ymail.com), **Microsoft** (Outlook.com, Hotmail and Microsoft 365) and **Other** (enter the details yourself). A tile is only a preset: it fills in the mail server, port and encryption, and the page reads the provider back from those values.

| Tile | Mail server | Port | Encrypt from the start |
| --- | --- | --- | --- |
| **Gmail** | smtp.gmail.com | 465 | On |
| **iCloud Mail** | smtp.mail.me.com | 587 | Off |
| **Yahoo Mail** | smtp.mail.yahoo.com | 465 | On |
| **Microsoft** | signs in instead | | |
| **Other** | yours | yours | yours |

Gmail and Microsoft can also send through their own service: **Sign in with Google** or **Sign in with Microsoft** opens that provider's page in a new tab, where you choose the account and allow Frameleaf to send email from it. Frameleaf can send and nothing else: it cannot read your mail, and no password is kept on this server. Gmail keeps **Use an app password instead** beside it; Microsoft is sign-in only. Signing in needs a server linked to a Frameleaf account, because Google and Microsoft only let you sign in through a public web address; the account is free. **Disconnect…** stops sending until an account is set up again. See [How connected accounts work](https://frameleaf.app/docs/admin/email/#how-connected-accounts-work).

- **Send email from this server** (`notifications.smtp.enabled`, off). On, welcome emails, album invitations and album updates are sent from this account. Off, nothing is sent; invitations and album updates appear in the app only.
- **Email address** (`notifications.smtp.transport.username`), for a provider tile: the address emails from this server come from.
- **App password** (`notifications.smtp.transport.password`), for a provider tile. Gmail, iCloud and Yahoo don't let other apps use your normal password; you make an app password on the provider's own site, and **How to make an app password for …** opens its guide. The password is write-only: its row shows **Stored** or **Not set**, as described under [Server credentials](#server-credentials).
- **Mail server** (`notifications.smtp.transport.host`), for **Other**: the address of your email provider's sending server.
- **Mail account name** (`notifications.smtp.transport.username`), for **Other**: usually your full email address.
- **Encrypt from the start** (`notifications.smtp.transport.secure`, off). On, the connection is encrypted from the first moment, usual for port 465. Off, the connection is encrypted once it is made, if the mail server offers it, usual for port 587.
- **Sender address** (`notifications.smtp.from`): the address people see emails come from. **How it looks in an inbox** shows the name and address together.

**Advanced** holds the rest:

- **Sender name** (the name part of `notifications.smtp.from`): the name people see beside the address. Leave it empty to show the address only.
- **Send replies to** (`notifications.smtp.replyTo`): where a reply to one of these emails goes. Leave empty to use the sender address.
- **How email is sent** (`notifications.smtp.transport.type`, a mail server). After signing in it reads **Through Google's own service** or **Through Microsoft's own service**, and there is no mail server, port or password to set. Choosing a tile or **Other** sets it back to a mail server.
- **Port** (`notifications.smtp.transport.port`, 587). Your email provider says which number to use; 465 and 587 are the usual ones. A tile fills it in.
- **Send even if the security certificate can't be checked** (`notifications.smtp.transport.ignoreCert`, off). Only for a mail server you run yourself. Leave off otherwise.

:::note[Changing the mail server clears the password]
Saving a different mail server or account name clears the stored password, so replace it afterwards. If email is on and the new server needs a password: turn email off, save the new server, replace the password, then turn email on again.
:::

**Check it works** sends one email to your own address. A test that works also saves these email settings, and nothing else. Until the page is saved it says **Save your changes first, and enter the password. The test uses what is saved.**; with sending off it says **Turn on "Send email from this server" first.** A sent test shows the address and time; if it is not in your inbox, look in the junk folder.

#### The emails themselves

Frameleaf writes a welcome for new people, an invitation when an album is shared, and a note when an album gets new photos. Most households never change them. **Change the wording of emails** opens one row per email, each saying **Standard wording** or **Your wording**, with **Edit**:

- **Welcome email** (`templates.email.welcomeTemplate`): sent to someone when you make them an account. It can insert the person's name, their sign-in email, the temporary password and a link to Frameleaf.
- **Album invitation email** (`templates.email.albumInviteTemplate`): sent when someone shares an album with a person. It can insert the person's name, who shared it, the album name and a link to the album.
- **Album update email** (`templates.email.albumUpdateTemplate`): sent when photos are added to an album shared with a person. It can insert the person's name, the album name and a link to the album.

The editor shows **Insert into the email** buttons for those names, a **Preview with sample names**, **Use the standard wording** and **Use this wording**. Leave the text empty to use the standard wording. Each default is empty, meaning the standard wording. See [Email templates](https://frameleaf.app/docs/admin/email/#email-templates).

- **First line of an invitation** (`templates.email.invitationFirstLine`, empty): the greeting at the top of an invitation email, for example "Hey [Person's name]!". [Person's name] becomes their name, and [Who shared it] works too. Leave it empty for the standard greeting. If you have written your own wording for the album invitation email, that is sent as written, so this line opens the emails about shared photos instead.
- **Show the Frameleaf name and logo** (`templates.email.showBranding`, on): at the top of every email this server sends.

## Server & updates

What this server is called, which version it runs, where its maps come from, and what it records when something goes wrong. The area opens on three groups, **This server**, **Updates & diagnostics** and **Maps**, with the **Troubleshooting**, **Server logs**, **Custom styling** and **Copy settings** pages kept under **Advanced**. **Server logs** is the log viewer, covered in [Monitoring and logs](https://frameleaf.app/docs/admin/monitoring/#read-the-logs). Changes on every page wait in your draft until you select **Save changes** at the bottom of the settings; **Reset this page** puts the page back to what is saved. When the server's settings come from a configuration file, every control here is read-only; see [Configuration file](https://frameleaf.app/docs/admin/config-file/).

### Server name & welcome

What this server is called, and what people see before they sign in. Beside the fields, **What people will see** is a sample of the phone app's server list and the sign-in page. It follows what you type.

#### Name and welcome

**Server name** (`server.name`, empty) is shown in Settings and when people choose a server in the phone app. Without a name it shows as "This server". Up to 100 characters; the sample suggests something like "The Rivera family photos".

**Welcome message** (`server.loginPageMessage`, empty) is shown to everyone before they sign in. Keep it short. The sample shows it above the email and password fields, or **No welcome message** while it is empty.

**Time zone** (`server.timeZone`, **Same as this computer**) is used for the times on this server, such as when backups and overnight work start. **Same as this computer** is the zone of the computer Frameleaf runs on, named beside it once the page has asked the server; the list below it has every zone, west to east. A zone saved from a configuration file that isn't in the list is kept and shown as typed.

**Advanced: Welcome message is** (`server.loginPageMessageFormat`, **Plain text**) chooses how the welcome message is read:

| Choice | What it means |
| --- | --- |
| **Plain text** (default) | Everything you type is shown exactly as typed |
| **Web formatting** | HTML, the code web pages are written in, lets you add a link or bold text. A mistake can change the sign-in page. Scripts, pictures and anything from other websites are always left out |

#### Finding this server

**Public server URL** (`server.externalDomain`, empty) is the address this server has on the internet. Links in emails and shared links are built from it. It's the same setting as the one under [Remote access](#remote-access), shown here so a server without remote access can set it too.

**Let phones on your Wi-Fi find this server** (`server.lanDiscovery`, on). On, the phone app lists this server when it is on the same network. People still have to sign in. Off, people type this server's address in the phone app. Turning it off only stops the broadcast: direct connections and sign-in work as before. While it's on, any device on this network can see that a Frameleaf server exists here, and its server name, so choose a name without a person's name in it. The server only broadcasts when it can see your home network; inside a container on a Docker bridge network it usually can't, so use host networking if you want discovery from a container. The phone app's side is in [The discovery card](https://frameleaf.app/docs/apps/iphone/#the-discovery-card).

**Allow automations to call devices on my network** (`server.automationsLocalNetwork`, off). Off, [workflows](https://frameleaf.app/docs/admin/workflows/#frameleaf-events) send Frameleaf events only to secure (`https`) addresses on the internet. On, they can also reach devices at home, such as Home Assistant. This computer itself and cloud metadata addresses stay out of reach either way.

**People can find each other when sharing** (`server.publicUsers`) has moved: whether everyone can pick other people by name is now with People & sharing. **Open People & sharing** takes you there; see [Sharing](https://frameleaf.app/docs/using/sharing/).

#### Help

**Ask Frameleaf** (`help.askEnabled`, on) lets people ask questions in the help panel. The question, the conversation so far and this server's hardware go to frameleaf.app's Ask service. Help articles stay available either way. What the service receives, and how to use it from this website, is in [Ask Frameleaf](https://frameleaf.app/docs/help/ask-frameleaf/#what-is-sent-when-you-ask).

#### iCloud Photos

**Let people bring in photos from iCloud** (`icloud.enabled`, on). Each person signs in with their own Apple account. While this is off, nothing new comes in from iCloud; photos already here and saved sign-ins are kept. If a sync is running or waiting to run, on any account, Frameleaf warns you first. See [iCloud Photos Sync server setup](https://frameleaf.app/docs/migrate/icloud-photos-server-setup/).

### Updates

Which version of Frameleaf this server runs, and whether there is a newer one. The page opens on the answer. With **Look for updates** set to **Never**, it opens on **You're running Frameleaf** and the version: the server isn't looking, so it can't say yet whether that's the newest. Select **Check now** and it changes to **is up to date** with when it was checked. When the server looks every day or every week, the page opens on **is up to date** once a check has run. The other answers are that a newer version **is available** (you decide when to install it) and **Couldn't check for updates** when Frameleaf's release list did not answer; this server keeps working, so try again later. **Check now** asks straight away, whatever the schedule.

**Versions** lists **Installed** and, once a check has run, **Newest from Frameleaf** with when it was checked. When a newer version is available, two links follow, with a reminder that you install it from where this server was set up, not from this page: **What is new** opens the release notes for it, and **Before you update** reminds you to make sure a backup has finished and opens Backup; see [Backup and restore](https://frameleaf.app/docs/admin/backup-and-restore/).

#### Looking for updates

**Look for updates** (`newVersionCheck.enabled` and `newVersionCheck.frequency`, **Never**) is one choice:

| Choice | What it sets | What it means |
| --- | --- | --- |
| **Never** (default) | `enabled` off | This server does not look. Use "Check now" when you want to know |
| **Every day** | `enabled` on, `frequency` `daily` | This server asks once a day whether there is a newer version |
| **Every week** | `enabled` on, `frequency` `weekly` | This server asks once a week whether there is a newer version |

**Hear about a new version** opens Notifications: **What needs your attention** lists a new version as soon as Frameleaf finds one. See [Command Center](https://frameleaf.app/docs/admin/command-center/#updates).

Two promises are printed on the page. **This server asks only Frameleaf's release list**: the list is Frameleaf's releases page on GitHub, nothing about your library is sent, and no other service is contacted. **You decide when to install**: Frameleaf tells you about a newer version and never installs one by itself. How to install one, for each kind of installation, is in [Upgrading](https://frameleaf.app/docs/admin/upgrading/).

**Advanced: Get early versions** (`newVersionCheck.channel`, **Off (recommended)**) chooses which releases count. Early versions arrive sooner and may be less reliable:

| Choice | What it sets |
| --- | --- |
| **Off (recommended)** | `stable`: only stable releases |
| **On** | `releaseCandidate`: stable releases and release candidates |

**Advanced: Installed** says whether this server runs **A stable release** or **An early version**, worked out from the installed version's name. **Having a problem?** under **More** opens Troubleshooting to download a report.

### Maps & places

Where the map comes from and whether photos get place names. The map's own page, place search and fixing a location are in [Places and the map](https://frameleaf.app/docs/using/places/).

#### The map

**Show photos on a map** (`map.enabled`, on). On, the map pictures come from a map service: the device you view the map on asks it for the part of the world on screen. Your photos are never sent to it. Off, the Map page and the small maps beside photos are hidden for everyone.

**Map look** (**Standard**) chooses where the pictures come from. The choice is greyed out while the map is off:

| Choice | What it means |
| --- | --- |
| **Standard** (default) | Frameleaf's own map, in a light and a dark version |
| **Custom** | The map is drawn from the style addresses under Advanced |

**Advanced: map style addresses** holds the two addresses, which can only be typed once **Custom** is chosen. A map style is a file that says how the map is drawn and where its pictures come from. Each address must point to one.

- **Light map style address** (`map.lightStyle`, `https://tiles.frameleaf.cloud/v1/style/light.json`)
- **Dark map style address** (`map.darkStyle`, `https://tiles.frameleaf.cloud/v1/style/dark.json`)

The page shows **Custom** whenever either address differs from the standard one, including after a configuration file set them. **Go back to the standard map**, with **Use the standard map**, puts both addresses back to Frameleaf's own map. Writing your own style, or building one with MapTiler, is in [Use your own map style](https://frameleaf.app/docs/using/places/#use-your-own-map-style).

#### Places

**Name the places in your photos** (`reverseGeocoding.enabled`, on) turns a photo's location into a town and country, worked out on this server. Off, new photos get no place names; names already found are kept. **How places are named** on the page opens [Place names stay on your server](https://frameleaf.app/docs/using/places/#place-names-stay-on-your-server).

### Troubleshooting

What to send when you need help, and what this server records to help fix a problem. This page is under **Advanced** on the area's front page.

#### Having a problem? Download a report

**Download a report** makes one file to send to whoever is helping you. It is made on this device and goes nowhere by itself. **What the report includes**: the Frameleaf version and which features are on; how much storage is used and free; how much background work is waiting; and this server's settings, with the mail account and every password left out. It never includes photos, videos, file names or people's names, and no passwords, keys or sign-ins. If the file can't be prepared, the page says **Could not prepare the diagnostics file**.

#### What this server records

A running record of what the server did, for finding out what went wrong.

**Keep a record of what this server does** (`logging.enabled`, on). On, the record stays on this server. Off, nothing is recorded, so a problem is much harder to find. The other two controls are greyed out while it's off.

**How much to record** (`logging.level`, **Normal**) is a choice between two levels:

| Choice | What it sets | What it means |
| --- | --- | --- |
| **Normal** (default) | `log` | What happened and what went wrong, without the detail |
| **Detailed** | `debug` | Records much more, which helps whoever is helping you. It can include file names. Go back to Normal when the problem is solved |

**Advanced: Exact level** (`logging.level`) has six levels, from only the most serious problems to everything. When one of the other four is chosen, **How much to record** shows it as a third choice and says **Set to an exact level under Advanced**:

| Choice | What it sets |
| --- | --- |
| **Only what stops the server** | `fatal` |
| **Errors only** | `error` |
| **Warnings and errors** | `warn` |
| **Normal activity** | `log` (Normal) |
| **Detail for finding a fault** | `debug` (Detailed) |
| **Everything** | `verbose` |

**Read the logs yourself** opens **Server logs**, where administrators read, search and download the record in the browser. Where the record is kept, how to read it, and setting the level from the environment are in [Monitoring and logs](https://frameleaf.app/docs/admin/monitoring/#log-level). Nothing in it is sent anywhere; see [No telemetry](https://frameleaf.app/docs/admin/monitoring/#no-telemetry).

#### Library analytics

The charts in Library analytics are drawn from a history kept on this server. It never leaves it. See [Library analytics](https://frameleaf.app/docs/admin/command-center/#library-analytics).

**Keep a history for Library analytics** (`analytics.enabled`, on) adds to that history every night. Off, Library analytics has nothing new to draw.

**Keep it for** (`analytics.historyDays`, **24 months**) is how far back the history goes: **90 days**, **12 months** or **24 months**. A length set from a configuration file that isn't one of the three is shown as a number of days; anything from 30 to 800 days is accepted.

### Custom styling

Change how Frameleaf looks for everyone on this server, with your own style sheet. This page is under **Advanced** on the area's front page, and is for people who write CSS.

:::note[A style sheet can hide or move anything in the app]
Settings pages always keep the standard look, so you can come back here and turn **Use custom styling** off.
:::

**Use custom styling** (`theme.customCssEnabled`, on). On, the style sheet below changes how Frameleaf looks for everyone. Off, Frameleaf has its standard look, and your style sheet is kept for later.

**Style sheet (CSS)** (`theme.customCss`, empty) applies to everyone who opens this server in a web browser, except on settings pages. For example:

```css
p {
  color: green;
}
```

### Copy settings

A copy of this server's saved settings, to keep or to load on another server. This page is under **Advanced** on the area's front page. The file is the same shape as a [configuration file](https://frameleaf.app/docs/admin/config-file/#what-the-file-looks-like).

**Save to a file** downloads the copy; **Copy as text** puts the same text on the clipboard, and **Show the file** displays it on the page. **What is included**: every setting on these Settings pages for the whole server. Never photos, videos, albums or accounts, and never passwords, keys or sign-ins inside an address; those are emptied before the file is made.

**Load from a file** changes nothing by itself. Each setting that would change is listed under **Settings that would change**, in the words of its own page, and in the bar at the bottom, and nothing is saved until you confirm there. While settings are waiting, the page says how many, and reminds you they are listed under "Load from a file". **Load from a file** is hidden when the server's settings come from a configuration file; the file itself is what to edit then.

## Setting up a new server

A new server has no administrator. Until it has one, anyone on its home network can claim it; there is no setup code. Set it up soon after installing, before anyone else on your network reaches it.

**Who can set it up**

- Only from your home network, never over remote access. A request counts as home when it comes from a private address, or through a trusted local reverse proxy that passes the visitor's address in `X-Forwarded-For`. Tries are limited per address.
- Only while the server has no administrator. Once one exists, setup is over.
- For a server that isn't on your home network, such as a rented server, connect through an SSH tunnel or add your network to `FRAMELEAF_TRUSTED_LAN_CIDRS`.
- **Restore from a backup** onto a new server follows the same rules.

**Setting up in the browser**

Open the server's address and setup starts on its welcome page. It goes through five chapters: **Welcome**, **Account**, **Library**, **Protection** and **Ready**.

1. **Create your admin account.** Enter a name, an email and a password of at least 8 characters. This is the server's own sign-in. It keeps working even when the internet or Frameleaf Cloud doesn't.
2. **Add a Frameleaf account**, if you want one. It's optional: it links this server to a Frameleaf account so you can reach your library away from home, sign in anywhere and add Cloud Backup when you want it. Your photos stay on this server.
   - **Create account and link** makes a new Frameleaf account from the name and email you just gave, with a password for it. Frameleaf emails a 6-digit code to confirm the address.
   - **I already have a Frameleaf account** switches to its email and password, then **Sign in and link**. An account with an authenticator app asks for its code.
   - **Skip for now** leaves the server unlinked. You can link it later in **Settings**, then **Frameleaf Cloud**.
3. Carry on through where the library lives and how it's protected. Nothing is imported during setup.

The server is linked straight away, with no approval page to open on another device. The Frameleaf password is sent once and never stored on the server. If setup can't reach Frameleaf Cloud, your admin account already works, so skip and link later.

**Setting up from the Frameleaf app**

The iPhone and Android apps can also set up a new server on your home network and link it to your Frameleaf account. An administrator made that way has no server password at first, and is asked to set one; see [A password for the owner of a linked server](https://frameleaf.app/docs/admin/sign-in-and-oauth/#a-password-for-the-owner-of-a-linked-server). A server that's already linked to a Frameleaf account is never set up or linked again: the apps join it with Sign in with Frameleaf.

See [First steps](https://frameleaf.app/docs/start/first-steps/).

Linking to Frameleaf Cloud is optional. `FRAMELEAF_LINK_TOKEN` links a server when it starts, without a browser, with a single-use link token (`fll_…`). An administrator can link a server that's already set up from **Settings** or the app. See [Frameleaf Cloud account](https://frameleaf.app/docs/cloud/account/#link-a-server).
