Immich Album Sync

One-way album sync between two Immich servers — with a web UI.
Built for Unraid, runs on any Docker host.

Immich A (private)  ──────────────▶  Immich B (public/family)
    Master library                       Curated albums only

Features

• 🖥️ Web UI — configure sync jobs, view status, stream live logs from the browser
• 🔐 Password-protected — username/password login; forced password change on first login
• 🔑 Encrypted API keys — all API keys are AES-encrypted at rest; never stored or rendered in plaintext
• 📅 Cron scheduling — configurable per-job schedule, runs automatically in the background
• 📸 Preserves originals — downloads and uploads raw files with EXIF and GPS intact
• 🍎 Live Photo support — automatically pairs .HEIC + .MOV files
• 🔁 Duplicate-safe — uses immich-go for smart duplicate detection on the destination
• ⚡ Incremental & bandwidth-friendly — checks the destination by checksum before downloading, so re-syncing an unchanged album transfers almost nothing
• 📱 Mobile-responsive — works on phones, tablets, and desktops
• 🚀 Multi-job — sync multiple albums with different schedules and servers
• 🔍 API permission checker — test and verify required Immich API key permissions per job
• 🔔 Webhook notifications — get pinged on sync start/success/partial/failure; generic JSON that auto-formats for Discord & Slack, global or per-job
• 📜 Run history — browse every sync over the last 30 days (or any window) and filter by job and status to pin down failures
• 📦 Support bundle — one-click download of logs, sanitized config, and run history for troubleshooting

Screenshots

🔁 Sync Jobs — manage all album sync rules at a glance

✏️ Edit Job — servers, API keys, schedule & behavior

📜 Live Logs — real-time, color-coded sync activity stream

⚙️ Settings — credentials, account, and app info

Quick Start (Unraid)

Option A — Community Applications XML Template

1. In Unraid, go to Apps → My Apps (or add a template manually)
2. Use the XML template from this repository: immich-album-sync.xml
3. Set a unique SECRET_KEY (32–64 random characters — see Security)
4. Start the container and open http://your-unraid-ip:8080
5. Log in with admin / admin — you will be prompted to set a new password immediately

Option B — Unraid Docker UI (manual)

Option C — docker-compose

services:
  immich-album-sync:
    image: ghcr.io/nightcrawler1016/immich-album-sync:latest
    container_name: immich-album-sync
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./appdata:/app/appdata
    environment:
      SECRET_KEY: "replace-this-with-a-32-to-64-char-random-string"
      TZ: "America/New_York"

Then open http://localhost:8080 and log in with admin / admin.

First-login password change is required. You will be redirected automatically on first login.

Security

First-login Password Change

On first login with the default credentials (admin / admin), the application immediately redirects to a password-change screen. You cannot access any other page until a new password is set. The default password cannot be reused.

API Key Encryption

All Immich API keys entered in sync job forms are encrypted before being stored in the SQLite database using AES-128 (Fernet) with a key derived from your SECRET_KEY. Keys are:

• Never stored in plaintext
• Never rendered in HTML (form fields always show empty; a "Key stored securely" indicator is shown instead)
• Decrypted only in memory at sync runtime

SECRET_KEY Requirements

The container refuses to start if SECRET_KEY is unset, left at a placeholder value (anything beginning with change-me), or shorter than 16 characters. This is deliberate: the key signs session cookies and encrypts stored API keys, so a known/default value would let anyone forge an admin session and decrypt your keys. Set a real key before starting.

Generate a strong key: 1Password Generator — select 32–64 characters with all character types.

Important: Changing SECRET_KEY after the initial setup will invalidate all stored API keys (they were encrypted with the old key) and log out all active sessions. You will need to re-enter API keys for every sync job.

Session Security

Sessions are signed with SECRET_KEY using itsdangerous and expire after 24 hours.

Runs as Non-Root

The app process runs as an unprivileged user (PUID:PGID, default 99:100 = Unraid's nobody:users), not root. The container uses root only briefly at startup to fix data-directory ownership, then drops privileges. If your appdata is owned by a different user and you see permission errors, set PUID/PGID to match (see Troubleshooting).

Brute-Force & CSRF Protection

• Login rate limiting — repeated failed logins from an IP are throttled (10 failures within 15 minutes triggers a 5-minute lockout).
• CSRF protection — state-changing requests are rejected unless their Origin/Referer matches the app's own host, on top of a SameSite=Lax session cookie.

Safe Support Bundles

The downloadable support bundle never contains API keys, and server hostnames/IP addresses are masked in both sync.log and the job configs — so it is safe to share for troubleshooting.

Environment Variables

Volume Mount

Map this to a path on your Unraid array, e.g. /mnt/user/appdata/immich-album-sync.

Cache on External Storage or a Different Disk

For large first-time syncs (hundreds of GB or multi-TB albums), you may want the download cache on a high-capacity array disk, a separate SSD pool, or a network share — rather than your primary Unraid cache pool.

Unraid / Docker setup:

1. Add a second Path mapping in the Docker template:
   • Container path: /app/cache
   • Host path: /mnt/user/YourLargeDisk/immich-sync-cache (or any writable path)
2. Set the CACHE_PATH environment variable to: /app/cache

The sync engine will write all downloaded originals to that path. The main /app/appdata volume (database, logs) is unaffected.

docker-compose example with separate cache volume:

services:
  immich-album-sync:
    image: ghcr.io/nightcrawler1016/immich-album-sync:latest
    container_name: immich-album-sync
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./appdata:/app/appdata                     # database + logs (small, keep on fast drive)
      - /mnt/big-drive/sync-cache:/app/cache       # large cache on a different disk or share
    environment:
      SECRET_KEY: "replace-with-your-random-key"
      TZ: "America/New_York"
      CACHE_PATH: /app/cache

Web UI Pages

Setting Up a Sync Job

1. Open Sync Jobs → New Job
2. Enter the Source Server (your private Immich) URL and API key
3. Enter the Destination Server (your family/public Immich) URL and API key
4. Use the Test Connection button to verify API key permissions before saving
5. Select the source album name (populated from the test result)
6. Set a cron schedule (e.g. 0 23 * * * for 11 PM daily)
7. Save — the job will run on schedule automatically

Required API Key Permissions

Source note: asset.download is a separate scope from asset.read — it is what actually permits downloading original files. A key with only album.read + asset.read passes metadata checks but fails every file download with 403 Forbidden. user.read is not required on the source.

Destination note: Uploads run through immich-go, which requires a broad set of scopes and validates the connection via GET /api/users/me (so user.read is mandatory here). Its documented requirements include user.read, asset.read, asset.statistics, asset.update, asset.upload, asset.copy, asset.replace, asset.delete, asset.download, album.create, album.read, albumAsset.create, server.about, stack.create, tag.asset, and tag.create. Because this set changes between immich-go versions, the simplest reliable choice is an all-permissions API key on the destination. A narrowly-scoped key fails with Missing required permission: …. For family sharing, create a dedicated non-admin user on the destination and use their all-permissions key.

See Immich API Key documentation for how to create keys with specific permissions.

Notifications

Get notified when a sync runs — configured entirely in the browser under Settings → Notifications. No environment variables needed.

How it works

• One webhook URL. Paste any URL that accepts a JSON POST. If it's a Discord or Slack incoming-webhook URL, the message is auto-formatted (Discord embeds with a color per status; Slack attachments). Any other URL receives a plain JSON body you can route however you like.
• Pick your events. Choose any of Run started, Successful runs, Partial (some errors), and Failed runs. A common low-noise choice is just Failed + Partial.
• Global default + per-job override. The Settings page sets the default for every job. On a job's edit page you can leave it on Use global settings, turn it Off for that job, or set a Custom webhook/events just for that job.
• Test button. "Send test notification" posts a sample message so you can confirm the URL works before relying on it.

Security & privacy

• Webhook URLs are encrypted at rest (same Fernet scheme as API keys) and are never rendered back into the page — the field shows "Saved securely" and stays blank; leave it blank to keep the current URL.
• Notification payloads never contain secrets — no API keys, no server URLs (only the job name, album names, run counts, status, timestamps, and, for failures, the error message).
• A notification failure can never break a sync — the worst case is a warning in the log.

Generic JSON payload

Non-Discord/Slack endpoints receive:

{
  "service": "immich-album-sync",
  "event": "failed",
  "status": "failed",
  "job": "Family Shared Sync",
  "source_album": "Family Shared",
  "dest_album": "Family Shared",
  "message": "Family Shared Sync: Sync failed",
  "counts": { "found": 12, "downloaded": 0, "uploaded": 0, "skipped": 0, "failed": 12 },
  "error": "Album 'Family Shared' not found on the source server.",
  "started_at": "2026-07-04T02:00:00+00:00",
  "finished_at": "2026-07-04T02:00:07+00:00",
  "duration_seconds": 7,
  "timestamp": "2026-07-04T02:00:07+00:00"
}

Batch Processing

The sync engine automatically processes large albums in rolling batches to prevent the local cache from filling up your disk.

How batching works

Instead of downloading the entire album before uploading anything, the engine:

1. Downloads files until either BATCH_SIZE_MB or BATCH_FILE_COUNT is reached
2. Uploads that batch to the destination server
3. Clears the batch from the cache
4. Repeats until all files are processed

The final batch respects your CLEANUP_CACHE setting — intermediate batches are always cleared.

Defaults

With the default 10 GB limit, syncs under 10 GB behave exactly as before (single batch). Syncs over 10 GB are automatically split — you'll see progress in the live log like:

─── Batch 1: 247 files (9.98 GB) — 831 items remaining ───
   Batch 1: 212 uploaded to destination
   Batch 1: cache cleared, ready for next batch
─── Batch 2: 231 files (10.01 GB) — 600 items remaining ───
...

Tuning for your setup

How It Works

1. At the scheduled time, the sync engine connects to Immich A via its REST API
2. Finds the configured source album by name and lists all assets (including Live Photo .MOV companions)
3. Checksum pre-check — asks Immich B which of those assets it already has (by SHA-1). Assets already present are added straight to the destination album via the API, with no download or upload; only genuinely-new assets continue to the next step
4. Downloads the new originals to the local cache in rolling batches — once a batch reaches BATCH_SIZE_MB (default 10 GB) or BATCH_FILE_COUNT, it is immediately uploaded and cleared before the next batch begins
5. Uploads each batch to Immich B using immich-go (v0.31.0), which performs a second layer of duplicate detection on the destination
6. Logs all activity to /app/appdata/logs/sync.log, viewable live in the browser

Re-syncing an unchanged album is nearly free: the checksum pre-check skips every already-synced asset before any bytes are transferred, so there is no wasted bandwidth or disk. The pre-check is best-effort — if it ever fails, the engine falls back to downloading everything and lets immich-go de-dupe on upload, so no asset is ever missed. Files already present in the cache are also skipped on re-download.

Docker Image Tags

# Pull latest stable
docker pull ghcr.io/nightcrawler1016/immich-album-sync:latest

# Pull dev build
docker pull ghcr.io/nightcrawler1016/immich-album-sync:dev

Building Locally

git clone https://github.com/NightCrawler1016/immich-album-sync.git
cd immich-album-sync
docker build -t immich-album-sync:local .
docker run -p 8080:8080 \
  -e SECRET_KEY=my-local-dev-secret-32-chars-long \
  -v $(pwd)/appdata:/app/appdata \
  immich-album-sync:local

Troubleshooting

Download Support Bundle

In the Live Logs page, click Download Support Bundle to get a ZIP containing:

• sync.log — full sync log (server hostnames/IPs redacted)
• jobs.json — job configurations (API keys redacted; URL hosts masked)
• sync_runs.json — last 100 run records
• system_info.json — Python version, immich-go version, paths

The bundle is safe to share for troubleshooting: API keys are removed, and server hostnames/IP addresses are masked in both the log and job configs.

Common Issues

Notes on immich-go

This container pins immich-go to v0.31.0 for stability. The upload command used internally:

immich-go upload from-folder \
  --server DEST_URL \
  --api-key DEST_KEY \
  --into-album "Album Name" \
  --recursive /path/to/cache

Note: flags must appear after from-folder in v0.31.0. Earlier versions used different syntax.

Credits & Acknowledgements

This project is built on top of several excellent open-source tools — credit goes to their authors:

A big thank you to the immich-go project in particular — it does the heavy lifting of uploading files with smart duplicate detection so this tool doesn't have to reinvent that wheel.

License

MIT