A family photo library you can recover
Immich brings photos and videos into a web and mobile interface with albums, search, and sharing. Self-hosting lets you choose where data lives, but makes you responsible for storage, access, and recovery. Seeing thumbnails does not prove that your library is recoverable.
Our example uses two adults, two phones, and an older photo collection on a NAS. Start with 200 representative files, including long videos, HEIC, and Live Photos, before importing the whole family. Keep originals throughout the pilot and investigate failures instead of relying on thumbnail counts.
Version and licensing: an explicit baseline
These examples use Immich v3.3.5, a release containing security fixes. Read its release notes before selecting your deployment version. Immich is distributed under GNU AGPL v3; hosting, hardware, and backups remain your responsibility. Pinning a version makes deployment reproducible but does not remove the need to track security updates.
Size the server and separate data
Official requirements list a minimum of 6 GB RAM and two CPU cores, with 8 GB and four cores recommended. Platforms are amd64 and arm64; since v3, the amd64 machine-learning container requires x86-64-v2. A VM must expose the required instructions. These figures do not guarantee fast bulk imports.
Keep PostgreSQL on local storage, preferably SSD: DB_DATA_LOCATION must not be a network share. Allow extra capacity for thumbnails and derived video, then measure actual growth.
Docker Compose, Unraid, or Synology?
Docker Compose is the recommended method. Keep the services and images from your chosen release: Immich server, machine learning, database, and cache. Do not substitute a generic PostgreSQL image; extensions and versions are part of compatibility.
On Synology, confirm that the model and DSM support Container Manager and meet CPU/RAM requirements. Immich's Synology guide is a community contribution, not an official support commitment. An older NAS can remain a media or backup destination while a small Linux server runs the application and local database. On Unraid, document media and database paths separately, including their storage policy.
Install a pilot using release files
Change — download release files into a new directory rather than taking arbitrary files from main. The following block creates local files but does not start the application. It requires curl and a Linux shell. Docker administration grants substantial host privileges and should be restricted to the administrator.
In .env, set dedicated absolute paths for UPLOAD_LOCATION and DB_DATA_LOCATION, TZ=America/Toronto, and IMMICH_VERSION=v3.3.5. Replace the example PostgreSQL password with a random secret stored in your password manager; follow the template's accepted character requirements. Never publish .env.
# New directory / Nouveau dossier
mkdir immich-family-pilot
cd immich-family-pilot
umask 077
curl -fL -o docker-compose.yml https://github.com/immich-app/immich/releases/download/v3.3.5/docker-compose.yml
curl -fL -o .env https://github.com/immich-app/immich/releases/download/v3.3.5/example.env
chmod 600 .envValidate before the first import
After customization, docker compose config --quiet validates configuration without printing resolved secrets. Success does not verify folder permissions or disk capacity. Review published ports and restrict access to the pilot network before startup.
Change — docker compose up -d creates and starts containers. Immediately register the administrator from the trusted network, then create a regular account for each adult. Test upload, original download, and video playback. To stop a problematic pilot, docker compose stop preserves data; do not delete volumes to troubleshoot a simple failure.
# Validate without printing secrets / Valider sans afficher les secrets
docker compose config --quiet
# CHANGE: run only after successful validation / CHANGEMENT
docker compose up -d
# Read-only status / État en lecture seule
docker compose psiPhone: verify completed transfers
Select albums to upload and grant the necessary Photos access. Enable Background App Refresh, but iOS decides when it runs: immediate uploads are not guaranteed. During the initial import, open the app regularly on stable Wi-Fi.
Items in iCloud may be downloaded temporarily to the iPhone before upload, consuming storage and data. Compare sample server-side originals before cleaning up the phone. Mobile backup feeds Immich; it does not independently back up the server.
External libraries: keep originals read-only
An external library indexes existing files and belongs to one user. Add a read-only mount under the immich-server service's volumes without replacing existing mounts. After recreating the container, use the internal path /mnt/family-archive under Administration > External Libraries.
The :ro suffix restricts writes to originals and prevents some features such as writing XMP sidecars. Moving files and rescanning can lose associations held inside Immich. Back up this external collection too; scanning does not create an independent copy.
# Add to immich-server.volumes / Ajouter aux volumes existants
- /srv/family-archive:/mnt/family-archive:roShare without exposing the whole family library
Use individual accounts and selected albums for relatives. Partner sharing is one-way and can expose GPS metadata and permit resharing; enable it only after explaining its scope. Duplicate detection is per user, not necessarily across both libraries.
Practical test: sign in with a second account and check what it can see, download, and reshare. Test revocation too. A shared link can be forwarded; revoking it cannot remove copies already downloaded.
Semantic search and faces: focused local AI
Contextual search uses models such as CLIP and indexes in PostgreSQL. Try simple descriptions such as “dog in the snow,” then compare results with date or album filters. Quality and language support depend on the selected model.
Facial recognition groups faces; a person still needs to review clusters and names. These features are not a generative assistant that understands every archive or executes tasks. With local machine learning, inference runs on your hardware; model downloads and other network features still need consideration. Protect person metadata as carefully as the photos.
GPU: two separate acceleration paths
Machine-learning acceleration remains experimental. Documented backends include CUDA/NVIDIA, OpenVINO/Intel, ROCm/AMD, ARM NN/Mali, and RKNN/Rockchip, with hardware, driver, and model restrictions. Host detection does not prove container usage.
Video transcoding uses separate configuration: NVENC, Quick Sync, VAAPI, or RKMPP depending on hardware. Enabling GPU search does not automatically accelerate video. Start on CPU, measure queues, then introduce one acceleration path and confirm usage through logs and telemetry. Keep the previous CPU configuration to return to a working pilot.
Back up a consistent set
Built-in database backups contain metadata, not photos or videos. Pair them with UPLOAD_LOCATION files and external libraries. Keep Compose, protected .env, and image versions too. Copying the PostgreSQL directory while it is active is not a validated backup procedure.
For the family pilot, schedule a period without uploads or deletions, wait for file-changing jobs to finish, and create a dump through Administration > Job Queues. Then copy the dump and matching media with your backup tool. If writes cannot be controlled, plan a controlled shutdown or a storage-appropriate consistency procedure. Document the common recovery point.
An independent copy and a real recovery exercise
Our recommendation: a versioned copy on another destination plus an encrypted off-site copy with separate access. RAID/Unraid parity helps with certain disk failures; it does not protect against deletion or a compromised account. Define acceptable data loss, such as 24 hours, and alert when backups exceed that age.
Restore first to an isolated instance with separate paths, a compatible version, and no connected phones. Documentation offers web restoration from onboarding or Administration > Maintenance; restoring replaces the current database. Never run your first test on the only family instance.
Validate accounts, albums, downloaded originals, videos, and external libraries. Compare sample file hashes with the source, measure recovery time, and record missing steps. Declare success only after reading restored media, not merely after downloading the archive.
Remote access: HTTPS and minimal exposure
For private family use, a VPN reduces application exposure; it must be connected on the phone to reach the server. Do not publish HTTP port 2283 directly to the Internet. Expose neither PostgreSQL, cache, nor the machine-learning service.
For public web access, use HTTPS on a subdomain such as photos.example.net. Immich does not support an /immich subpath. Check proxy upload limits, timeouts, and /.well-known/immich routing with a large video and the mobile app.
A Cloudflare Tunnel can be part of the architecture, but test service limits and compatibility between additional authentication and the mobile client. An extra browser-oriented login page does not guarantee working background uploads.
Authentication and secrets
Immich supports OpenID Connect. If your provider enforces MFA, test web login, mobile callback, and account recovery before relying on it. Use the documented redirect URLs rather than inventing a callback.
Limit administrator accounts, protect identity-provider secrets, and revoke unused API keys. Keep a tested recovery path before changing login methods. Self-hosting does not make users anonymous to the server administrator.
Updates and recovery
Read release notes across the upgrade path and update mobile clients in the recommended order. Take a consistent backup before changing images. After adapting Compose and .env, the commands below download and apply the selected version: this is a change with possible downtime.
Immich does not support downgrading, even between patch releases. Putting an old image against a migrated database is therefore not a rollback plan. Prepare to restore the pre-upgrade set into a compatible environment, then perform a controlled switch. Uploads newer than the restored recovery point must be recovered separately.
docker compose config --quiet
# Stop on any error / Arrêter à la première erreur
docker compose pull
# Run only if pull succeeded / Seulement si pull a réussi
docker compose up -d
docker compose psMonitor and troubleshoot without erasing evidence
Read-only — run these commands from the Compose directory with authorized Docker access. Logs may contain filenames or identifiers: redact them before sharing. Avoid plain docker compose config in support tickets because resolved variables can expose secrets.
A slow machine-learning queue calls for CPU, memory, model, and storage checks. An empty external library calls for mount, internal-path, and permission checks. Remote uploads failing only for large videos point toward proxy limits. Measure before reinstalling or increasing every limit.
Monitor free space, container state, upload errors, age of off-host copies, and the last recovery exercise. A healthy container guarantees neither complete originals nor valid backups.
Also review the integrity report: missing files, untracked files, and checksum mismatches require investigation. Do not automatically clean up an anomaly before identifying the original and its backup copy.
docker compose ps
docker compose images
docker compose logs --since 30m --tail 100 immich-server
docker compose logs --since 30m --tail 100 immich-machine-learning
df -h
# Snapshot of resource use / Mesure ponctuelle des ressources
docker stats --no-streamWhen the pilot is ready for the family
Before the full import, require five outcomes: readable originals, sharing checked from another account, confirmed iPhone uploads, a recent off-host copy, and a successful restore. Document who maintains the server and how the family will recover photos if that person is unavailable.
Professional help can cover NAS/server selection, networking, remote access, and backup planning. This guide helps prepare a pilot; it does not replace an assessment of your storage, risks, and recovery procedure.
About the author
Marc-Antoine Lambert
Montréal-based senior IT consultant and Team Lead specializing in architecture, cybersecurity, Microsoft infrastructure, networking and business continuity.
Discuss your environment →