Skip to content

iCloud Photos Sync 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. 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.

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.

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.

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

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.

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:

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.

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 for backing up the rest of your server.

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.