# iCloud Photos Sync server setup

Source: https://frameleaf.app/docs/migrate/icloud-photos-server-setup/

iCloud Photos Sync is built into Frameleaf, so there's nothing to install or configure. Everyone on your server can bring their iCloud Photos library in themselves by following [Import from iCloud Photos](https://frameleaf.app/docs/migrate/icloud-photos/). This page is for the administrator.

The only thing it needs from you is that the Frameleaf web app is served over HTTPS, because Apple sign-in is refused over plain HTTP.

## Turn it on or off

iCloud Photos is on by default. To change that, open **Settings**, then **Server & updates**, then **Server name & welcome** and use **Let people bring in photos from iCloud** under **iCloud Photos**, then save.

While it's off, nothing new comes in from iCloud and people see **iCloud Photos is turned off** on the iCloud Photos page. Photos already in Frameleaf and saved Apple sign-ins are kept, so it picks up again on the next sync after you turn it back on.

If a sync is running or waiting to run, on any account, Frameleaf warns you before turning it off. A sync that's stopped this way brings in the rest of its photos on the next sync after iCloud Photos is back on.

## Where it keeps its files

Frameleaf creates a private `.frameleaf-icloud` folder inside your data folder the first time someone uses iCloud Photos. It holds the encryption key for saved Apple sessions, and the staging area for downloads in progress and verified recovery copies. Leave it where it is, and make sure the disk has room for the staging budgets you allow.

Apple passwords and verification codes are only ever typed into the HTTPS web form: never put them in `.env`, Compose files, command lines or support logs.

The first start after upgrading to a release with iCloud source identities builds an index over the sync's records. On a very large iCloud library, that start takes longer.

If you already set up the separate bridge container with the older Compose overlay, it keeps working and you don't need to change anything.

## When syncs run

A connection set to check **By itself** looks in iCloud during the server's overnight run, with the rest of the night's work. Change the time in **Settings**, then **Computers & background work**, then **Overnight schedule**; see [Nightly tasks](https://frameleaf.app/docs/admin/jobs/#nightly-tasks). A connection set to **Only when I ask** syncs only when its owner presses **Sync now**.

When Library care finds a missing or damaged photo that came from iCloud, it asks iCloud Photos for the original and a connection that checks by itself syncs straight away. See [When a photo here goes missing or gets damaged](https://frameleaf.app/docs/migrate/icloud-photos/#when-a-photo-here-goes-missing-or-gets-damaged).

## Server-wide limits

Each connection has its own **Downloads at once**, from 1 to 4, and its own **Temporary space to use (GB)**, its staging budget. These server-wide limits apply on top, on the workers that run the sync:

| Variable | Default | What it does |
| --- | --- | --- |
| `FRAMELEAF_ICLOUD_MAX_CONCURRENCY` | `4` | Most downloads running at once across all connections. Also the highest **Downloads at once** a person can choose. |
| `FRAMELEAF_ICLOUD_MAX_STAGING_BYTES` | `107374182400` (100 GiB) | Total staging space all connections can reserve. Also the largest staging budget a person can choose. |
| `FRAMELEAF_ICLOUD_FREE_SPACE_BYTES` | `1073741824` (1 GiB) | Free disk space always left over, on top of the next download. |
| `FRAMELEAF_ICLOUD_IDENTITY_MATCHING` | on | Set to `false` to stop matching iCloud source identities between the sync and the iPhone app. Then only identical files count as the same. |

Raise a limit only when the disk has room for it. Verified recovery copies outside a person's current selection keep their reservation until they're reselected and recovered, so when a budget fills up, add capacity. Leave the reservations in the database and the staging folder's contents to Frameleaf.

### Media validation timeout

Every downloaded file is validated before it's used, and videos are fully decoded. `FRAMELEAF_MEDIA_VALIDATION_TIMEOUT_MS` sets how long that may take. The default is `120000` (two minutes); values are kept between `10000` and `86400000`, and an invalid value uses the default. Set it on every server or worker that validates media, for example in an extra Compose override:

```yaml
services:
  frameleaf-server:
    environment:
      FRAMELEAF_MEDIA_VALIDATION_TIMEOUT_MS: '600000'
```

A timeout means the file couldn't be checked, not that it's damaged or repaired. A longer timeout gives long videos time to finish; formats the decoder can't read stay unsupported.

## Disconnecting, backups and restores

**Disconnect** removes a connection's saved Apple session and stops new work. Imported photos stay, and nothing is deleted from the Apple account. Leave the `.frameleaf-icloud` folder alone while a sync is running or while it holds the only verified recovery copy of something.

Back these up together, as one consistent checkpoint:

- the Frameleaf database,
- your data folder, including `.frameleaf-icloud`.

Pause the sync workers before an application-consistent snapshot, and protect the backups carefully, because they include the encryption key. If you restore a database without its matching encryption key, everyone has to sign in to Apple again. Never attach session values, tokens, signed links, passwords or keys to a support report.

See [Backup and restore](https://frameleaf.app/docs/admin/backup-and-restore/) for backing up the rest of your server.

## Before a large import

Try one small album first and check:

1. sign-in and device approval,
2. a normal photo and a Live Photo,
3. a photo with an Apple edit, which should appear in a stack with its original,
4. a second sync of the same album, which should import nothing new,
5. pausing and resuming.

Test recovery only with throwaway media, never a valuable original.
