A few years ago, I received an automated email from my cloud storage provider warning me that I had exceeded my “free tier” photo limit. My options were simple: start paying a monthly subscription fee, or stop backing up the photos of my family. Even worse, reading the updated privacy policies revealed that automated algorithms were scanning my personal galleries to train their proprietary machine learning models.
If you are looking for the absolute best open-source software alternatives to reclaim your data, Immich is the undisputed king of photo management.
Immich is a high-performance, self-hosted replacement for Google Photos and Apple iCloud. It provides native iOS and Android apps, automatic background backups, and blazing-fast timeline scrolling. But what truly sets it apart is its ability to perform advanced facial recognition and semantic search (“find pictures of dogs in the snow”) entirely on your own hardware. By understanding the core differences between local vs cloud AI, you quickly realize how powerful it is to run these models privately.
In this guide, I will walk you through a complete Docker Compose deployment of Immich, covering hardware transcoding, database optimization, and reverse proxy security.
1. Deconstructing the Immich Architecture
Before we start typing commands, you need to understand what you are deploying. Immich is not a simple monolithic application. It is a modern microservices architecture consisting of several specialized containers working together.
If you have ever built a Node.js REST API, you’ll recognize the core Immich Server. Built on the NestJS framework, this API gateway handles client uploads, serves optimized webp thumbnails, and coordinates the entire system.
The heavy lifting happens in the Machine Learning container. Rather than relying on cloud APIs (a major privacy risk if you are studying how open-source intelligence works), Immich uses local Python services to run deep learning models. It uses InsightFace to extract mathematical vectors of human faces, and OpenAI’s CLIP model for semantic text-to-image search. This is a brilliant, real-world example of modern machine learning vs deep learning applications.
All of this data is stored in a PostgreSQL database augmented with the pgvector extension, which allows Immich to run mathematical similarity searches directly in SQL. As I outlined in my PostgreSQL vs MySQL benchmark, Postgres’s extensibility makes it the absolute best choice for vector workloads. Finally, a Redis container manages background job queues to ensure the UI stays snappy even when you upload 10,000 photos at once. This microservice separation is a prime example of the benefits covered in my Docker vs Podman benchmark.
2. Hardware Prerequisites
Because Immich runs machine learning operations locally, it requires more resources than a simple file server.
- CPU: A multi-core x86_64 or ARM64 processor.
- RAM: 4 GB minimum. (8 GB is highly recommended if you have a massive library and want facial recognition to run without crashing).
- Storage: Fast NVMe SSDs for the database, paired with massive HDDs for the actual media.
If you are running this on a rented cloud instance, you should understand what a VPS is and exactly what cloud computing costs at scale. For terabytes of photos, building a physical home server is vastly cheaper. To prepare your server OS, start with a clean installation by following my guide on installing Docker on Ubuntu. I strongly recommend using one of the best Linux distros for beginners like Ubuntu 24.04 LTS.
3. Installation & Docker Compose Configuration
Let’s deploy the stack. Create a dedicated directory on your server:
mkdir -p ~/immich-server
cd ~/immich-serverWe need to create a docker-compose.yml file. While some people prefer deploying apps graphically via Portainer, writing the YAML file yourself gives you ultimate control. Open your favorite text editor—I prefer Micro over Nano, but any of the top 13 Linux CLI text editors will do:
micro docker-compose.ymlPaste the following multi-container configuration:
version: "3.8"
services:
immich-server:
container_name: immich_server
image: ghcr.io/immich-app/immich-server:release
volumes:
- ${UPLOAD_LOCATION}:/usr/src/app/upload
- /etc/localtime:/etc/localtime:ro
env_file:
- .env
ports:
- 2283:2283
depends_on:
- redis
- database
restart: always
immich-machine-learning:
container_name: immich_machine_learning
image: ghcr.io/immich-app/immich-machine-learning:release
volumes:
- model-cache:/cache
env_file:
- .env
restart: always
redis:
container_name: immich_redis
image: docker.io/redis:6.2-alpine
restart: always
database:
container_name: immich_postgres
image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
environment:
POSTGRES_DB: immich
POSTGRES_USER: postgres
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- pgdata:/var/lib/postgresql/data
restart: always
volumes:
pgdata:
model-cache:The Environment Variables
Next, create the .env file to store your secrets:
micro .envUPLOAD_LOCATION=/home/suresh/immich-library
DB_PASSWORD=YourExtremelyStrongPassword123!
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
DB_HOSTNAME=database
REDIS_HOSTNAME=redis
IMMICH_MACHINE_LEARNING_URL=http://immich-machine-learning:3003
MACHINE_LEARNING_WORKERS=1
FFMPEG_THREADS=2
NODE_ENV=productionUse my interactive Password Generator to create a strong database password, and verify it with the Password Strength Checker. Make sure your UPLOAD_LOCATION is properly configured with write permissions. If you need a refresher on chown and chmod, read my guide explaining Linux file permissions.
Bring the stack up:
sudo docker compose up -d4. Hardware Transcoding (Optional but Recommended)
When you upload a massive 4K HEVC video from your iPhone, Immich transcodes it into a web-friendly format so you can play it seamlessly in a browser. This relies on the exact same ffmpeg mechanics I covered in my Jellyfin media server guide.
If you inspect the raw data streams using a JSON formatter or analyze the HTTP protocols in your browser’s network tab, you’ll see why CPU transcoding is brutally slow.
If you have an Intel CPU with QuickSync or a dedicated NVIDIA GPU, you can pass it through to the container to accelerate video processing. For Intel, just add the /dev/dri mapping to your immich-server container block. You can use the top 20 Linux security commands like ls -la /dev/dri to ensure your host OS actually detects the hardware before passing it to Docker.
5. Reverse Proxy Security
By default, Immich binds to port 2283 in plain HTTP. Never expose this port directly to the public internet! Doing so is a fast track to falling victim to the common OSINT mistakes that lead to personal data breaches.
Instead, put Immich behind a reverse proxy. My absolute favorite tool for this is the Caddy web server. It’s significantly easier to write configurations for than traditional proxies, but if you prefer a graphical interface, my Nginx Proxy Manager security guide covers that workflow beautifully.
Assuming you understand how DNS domain resolution works, point an A record (like photos.yourdomain.com) to your server. Caddy will automatically enable HTTPS with Let’s Encrypt, securing your connection natively. If you need to write traditional Nginx blocks, use my Nginx Config Generator to get the syntax right.
Once your proxy is live, navigate to https://photos.yourdomain.com and create your Admin account!
6. Importing Existing Photo Archives
If you have 15 years of family photos sitting on an external drive, uploading them via the web interface will take weeks. Instead, use the official immich-cli tool to ingest them locally.
Assuming you moved the files to your server using SFTP transfers or Syncthing file sync, you can generate an API key from the Immich web dashboard (under User Settings) and run:
npx @immich/cli upload --key "YOUR_API_KEY" --server "http://localhost:2283/api" --recursive /mnt/data/my-photo-archiveIf you aren’t familiar with executing Node packages on the fly, use my Linux Command Explorer to understand how npx handles binaries without installing them globally.
7. The Ultimate Backup Strategy
Your home server is only as reliable as your backups. If your NVMe drive dies tomorrow, your photos are gone.
You need to establish a rock-solid routine. I strongly recommend reading my comprehensive guide on backup strategies for self-hosted servers.
Because Immich stores metadata in PostgreSQL, you cannot simply copy the database files while the container is running. You must use pg_dumpall to export a clean SQL file. You also need to securely back up your .env passwords using one of the best password managers. I personally store my server credentials in a self-hosted Vaultwarden instance, with an offline copy managed by KeePassDX.
For the actual media files in your UPLOAD_LOCATION, I run a nightly rsync cron job that pushes incremental changes to my Nextcloud server.
8. Conclusion & Maintenance
Deploying Immich is profoundly satisfying. Watching the machine learning algorithms correctly group photos of your family members across decades—all processed locally on your own CPU—feels like magic. It is, without a doubt, one of the most powerful self-hosted applications you can run today.
To keep it secure, make sure you lock down your host ports using UFW firewalls and install Fail2ban to block automated network scanners. If you give friends or family accounts on your server, teach them to check the website URL before logging in to avoid phishing spoofing.
Finally, set up Uptime Kuma monitoring so you receive a Telegram notification the moment Immich goes offline, and run through my secure home server checklist to ensure your new photo vault is bulletproof.
Frequently Asked Questions (FAQ)
What exactly is Immich?
Immich is a high-performance, open-source photo and video management system designed to be self-hosted locally. It serves as a privacy-friendly, self-hosted alternative to commercial cloud platforms like Google Photos and Apple iCloud.
Do I need a powerful server to run Immich?
Yes, compared to a simple file server, Immich is demanding. Because it runs machine learning models locally to scan faces and images, it requires a multi-core x86_64 or ARM64 processor and an absolute minimum of 4 GB of RAM (8 GB is heavily recommended).
Can Immich perform facial recognition?
Yes! Immich features local machine learning capabilities. It uses models like InsightFace for highly accurate facial recognition, automatically grouping photos of the same person together across your entire library.
What is Semantic Search in Immich?
Semantic Search allows you to find photos using natural language text descriptions (e.g., “black dog in the snow” or “red car at the beach”). Immich uses the OpenAI CLIP model locally to convert both your text and your photos into mathematical vectors and match them without needing manual tags.
Is there an Immich app for my phone?
Yes. Immich has brilliant, native mobile applications for both iOS and Android. They feature automatic background uploading, meaning your photos sync to your home server automatically the moment you take them.
How do I access Immich when I am away from home?
To access your photos securely from outside your home network, you should set up a reverse proxy like Caddy or Nginx Proxy Manager. This securely routes HTTPS traffic to your server and encrypts the connection using Let’s Encrypt SSL certificates.
How do I backup my Immich server?
You need to back up two separate things: your actual photo files (usually via rsync) and your PostgreSQL database (via pg_dumpall). Backing up the database is critical because it stores all the facial recognition data, album structures, and user accounts.
Can I import my existing Google Photos library?
Yes. You can request a “Google Takeout” archive of all your photos, extract it to your server, and use the official immich-cli tool to bulk-import the massive archive into Immich seamlessly.
Does Immich support video transcoding?
Yes. If you upload large 4K HEVC videos from your phone, Immich will use FFmpeg to transcode them into web-friendly formats so they play smoothly in your web browser. You can accelerate this process by passing an Intel or NVIDIA GPU into the container.
Is Immich safe for multiple users?
Yes. Immich supports robust multi-user environments. You can create separate accounts for your family members, and their photo timelines will remain completely private unless they explicitly choose to share specific albums with you.
Discussion
Loading comments...