Immich: Your Ultimate Guide to Building a Private Photo Server with AI 🚀

G: Are you tired of entrusting your precious photo memories to big tech companies? Worried about privacy, storage limits, or ever-changing terms of service? What if you could have all the smart features of cloud photo services – like AI-powered search and facial recognition – but with complete control over your data?

Enter Immich, an incredible open-source, self-hosted photo and video backup solution that’s rapidly gaining popularity. Think of it as your personal Google Photos alternative, but entirely under your roof. This comprehensive guide will walk you through everything, from setting up Immich on your own server to unlocking its powerful AI capabilities. Let’s dive in! 📸

Table of Contents:

1. Why Immich? The Power of Self-Hosting Your Photos
2. Prerequisites: What You’ll Need Before You Start
3. Immich Installation: Step-by-Step Guide
4. Importing Your Existing Photos 📂
5. Unlocking Immich’s AI Capabilities 🤖
6. Advanced Configurations & Best Practices ✨
7. Troubleshooting Common Issues 🔧
8. Conclusion: Your Private Photo Sanctuary Awaits!

1. Why Immich? The Power of Self-Hosting Your Photos 🏡

In an era where data privacy is paramount, self-hosting your photos offers unparalleled benefits:

• Total Data Control: Your photos, your server. No third party ever touches your precious memories. You decide where they’re stored, how they’re secured, and who can access them.🔒
• Privacy First: Say goodbye to concerns about your photos being used for data mining or targeted advertising. Immich is built with privacy in mind.
• Cost-Effective Long-Term: While there’s an initial setup cost for hardware and power, it often pales in comparison to recurring cloud subscription fees, especially for large photo libraries.
• Feature-Rich & Modern: Immich isn’t just a basic file server. It boasts a beautiful, modern interface, dedicated mobile apps (iOS & Android), smart search, facial recognition, duplicate detection, sharing features, and more!
• Open Source Community: Being open source means a vibrant community constantly improving the software, adding features, and providing support. You’re part of something bigger! 🤝

2. Prerequisites: What You’ll Need Before You Start 🛠️

Before we begin the installation, let’s gather your tools and ensure your environment is ready.

A. Hardware Recommendations:

Immich can be run on various setups, from a Raspberry Pi to a dedicated server. Here’s a general guide:

• Server Hardware:
  • Mini PC / NUC: Excellent balance of power and low energy consumption. Examples: Intel NUC, Beelink Mini PCs.
  • Old Desktop/Laptop: Repurpose existing hardware. Ensure it’s reasonably modern.
  • NAS (Network Attached Storage): Many users run Immich in Docker on their Synology, QNAP, or TrueNAS systems.
  • Dedicated Server/VM: For power users with large libraries or multiple services.
• CPU: A modern multi-core CPU (Intel i3/i5 or AMD Ryzen 3/5 equivalent or better) is recommended, especially for AI features which can be CPU intensive.
• RAM:
  • Minimum: 4GB
  • Recommended: 8GB+ for smoother operation, especially with AI features enabled and a growing library. More RAM helps with caching and AI model loading.
• Storage:
  • SSD (Solid State Drive): Highly recommended for the operating system and Immich’s database (PostgreSQL and Typesense). This drastically improves performance. A 120GB+ SSD is usually sufficient for the OS and application data.
  • HDD (Hard Disk Drive): For storing your actual photos and videos. Choose a size appropriate for your library (e.g., 2TB, 4TB, 8TB+). Consider RAID for data redundancy if you have critical data.

B. Software Requirements:

• Operating System:
  • Linux (Recommended): Ubuntu Server (LTS versions like 22.04) or Debian are excellent choices due to their stability and wide support.
  • Windows/macOS: While Docker Desktop can run Immich, a Linux environment is generally preferred for performance, stability, and long-term server operation.
• Docker & Docker Compose: Immich runs as a collection of Docker containers, orchestrated by Docker Compose. These must be installed on your chosen server OS.

C. Network Setup (Optional but Recommended):

• Static IP Address: Assign a static IP to your server on your local network. This makes it easier to consistently access Immich.
• Port Forwarding (for external access): If you want to access Immich from outside your home network, you’ll need to configure port forwarding on your router (typically port 443 for HTTPS).
• Domain Name & Reverse Proxy (for secure external access): For a professional and secure setup, consider acquiring a domain name and setting up a reverse proxy (like Nginx Proxy Manager, Caddy, or Traefik) to handle HTTPS certificates and routing. This is crucial for security if you expose Immich to the internet. 🌐

3. Immich Installation: Step-by-Step Guide 🚀

This guide assumes you’re setting up Immich on a Linux server (Ubuntu/Debian based).

Step 1: Prepare Your System

First, update your package lists and upgrade any existing packages. It’s always a good practice.

sudo apt update && sudo apt upgrade -y

Step 2: Install Docker and Docker Compose

If you don’t have Docker and Docker Compose installed, you’ll need to do so.

A. Install Docker Engine:

# Add Docker's official GPG key:
sudo apt update
sudo apt install ca-certificates curl gnupg -y
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update

# Install Docker packages:
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

B. Add your user to the docker group (optional but recommended for ease of use):

This allows you to run docker commands without sudo. You’ll need to log out and log back in for this to take effect.

sudo usermod -aG docker $USER

After this step, remember to log out of your SSH session and log back in for the group changes to apply!

Step 3: Download Immich’s Docker Compose Configuration

Immich provides an example.env and docker-compose.yml file that makes setup straightforward.

# Create a directory for Immich (e.g., in your home folder)
mkdir ~/immich
cd ~/immich

# Download the latest Immich release files
# You can check the latest release on Immich's GitHub: https://github.com/immich-app/immich
# As of writing, this command fetches the latest stable configuration:
wget -O docker-compose.yml https://raw.githubusercontent.com/immich-app/immich/main/docker/docker-compose.yml
wget -O .env https://raw.githubusercontent.com/immich-app/immich/main/docker/example.env

Step 4: Configure Your Environment Variables (.env file)

This is a critical step. The .env file contains important settings for your Immich instance. Open it with a text editor (like nano):

nano .env

Here are the key variables you should review and modify:

• UPLOAD_LOCATION=/usr/src/app/upload: This is the internal path within the Docker container. You need to map this to a host path where your photos will actually be stored. We’ll do this in docker-compose.yml in the next step. For now, understand that this is where Immich expects to store its uploads.
• DB_PASSWORD=your_super_secret_password: Change this immediately! Use a strong, unique password for your PostgreSQL database.
• TYPESENSE_API_KEY=your_typesense_api_key: Change this immediately! Use a strong, unique API key for Typesense (Immich’s search engine).
• TZ=America/New_York: Set your correct timezone. Find valid timezones here: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
• LOG_LEVEL=verbose: Keep this for initial setup and troubleshooting, you can change it to info later.
• NODE_ENV=production: Keep this as production.

Save and exit (Ctrl+X, Y, Enter in nano).

Step 5: Edit docker-compose.yml (Storage Paths)

Now, we need to tell Immich where to store your actual photo files on your host system. Open docker-compose.yml:

nano docker-compose.yml

Look for the volumes section under the immich-server and immich-microservices services (and immich-machine-learning if present, though storage is primarily for the first two for uploads).

You’ll see a line like: - ./upload:/usr/src/app/upload

Change ./upload to the absolute path on your host server where you want your photos to be stored.

Example: If you want your photos stored in /mnt/photos/immich, change the lines to:

# ... inside immich-server and immich-microservices volumes sections ...
    volumes:
      - /mnt/photos/immich:/usr/src/app/upload
# ... also update for the machine-learning service if it has an upload volume defined,
# though it primarily needs access to the image cache and models paths.
# Ensure consistency across all services that interact with upload directory.

# Also, configure paths for your database and typesense data if you want them persistent outside the default docker volumes:
# Example for PostgreSQL (immich-postgres service):
    volumes:
      - /mnt/immich_data/postgres:/var/lib/postgresql/data
# Example for Typesense (immich-typesense service):
    volumes:
      - /mnt/immich_data/typesense:/data

Important: Ensure the user running Docker has write permissions to these directories (/mnt/photos/immich, /mnt/immich_data/postgres, etc.). You can typically use sudo chown -R youruser:youruser /mnt/photos/immich and sudo chmod -R 775 /mnt/photos/immich for the photo directory, and similar for data directories.

Save and exit (Ctrl+X, Y, Enter in nano).

Step 6: Initialize Immich Database (Important for first run!)

Immich requires a database migration on the first run.

docker compose run --rm immich-server npm run db:migrate -- --env production

This command runs the migration and then exits. It’s crucial for setting up the database schema.

Step 7: Launch Immich! 🎉

Finally, start all Immich services using Docker Compose:

docker compose up -d

• up: Starts the containers.
• -d: Runs them in “detached” mode (in the background).

Give it a few minutes for all containers to start up and initialize. You can check their status with:

docker compose ps

All containers should show Up in the STATUS column.

Step 8: Access Immich in Your Browser

Open your web browser and navigate to:

http://your_server_ip:2283

(Replace your_server_ip with the actual IP address of your Immich server).

You should see the Immich login page. Create your first admin account, and congratulations – your private photo server is now up and running! 🥳

4. Importing Your Existing Photos 📂

Now that Immich is running, it’s time to get your photos in! Immich offers several ways to do this:

A. Mobile App Auto-Backup (Recommended for new photos)

The Immich mobile app (available on Android and iOS) is the easiest way to continuously back up new photos and videos from your phone.

1. Download the App: Search for “Immich” on your respective app store.
2. Connect to Your Server:
   • Enter your server URL (e.g., http://your_server_ip:2283). If you set up a reverse proxy with HTTPS, use that URL (e.g., https://photos.yourdomain.com).
   • Log in with your Immich credentials.
3. Enable Backup: Go to Settings -> Backup and enable Auto Backup. You can choose specific albums or folders to back up.

B. Immich CLI (Command Line Interface) Importer (Best for Bulk Importing)

For large existing photo libraries, using the Immich CLI tool (immich-cli or immich-go) is the most robust method. These tools handle metadata, duplicates, and are designed for large transfers.

1. Install the CLI:
   • immich-go (Go-based, often faster, recommended):

     go install github.com/immich-app/immich-go@latest

     (You’ll need Go installed: sudo apt install golang-go)

   • immich-cli (Node.js based):

     npm install -g @immich/cli

     (You’ll need Node.js and npm installed)

2. Configure & Import:
   • Immich-go example:

     immich-go upload --server "http://your_server_ip:2283" --key "YOUR_API_KEY" /path/to/your/photos/folder

     To get your API Key: Log into Immich web UI, go to Profile & Settings -> API Key.

   • The CLI tool will recursively scan your folder, upload new assets, and skip duplicates.

C. External Libraries (Read-Only Mount)

Immich also supports mounting an existing photo library in a read-only fashion. This is useful if you want Immich to index photos that are already organized and stored elsewhere (e.g., on a NAS share) without moving them.

1. Mount the Share: Mount your external photo library to a directory on your Immich server (e.g., /mnt/external_photos).
2. Add to docker-compose.yml: In the immich-server service, add another volume mapping:

       volumes:
         - /mnt/photos/immich:/usr/src/app/upload # Your primary upload location
         - /mnt/external_photos:/mnt/external_library:ro # Read-only mount

3. Restart Immich:

   docker compose down && docker compose up -d

4. Add External Path in Immich UI: Log into Immich, go to Administration -> Settings -> Libraries. You can add /mnt/external_library as an external path. Immich will scan this path and import metadata for the photos without moving them.

5. Unlocking Immich’s AI Capabilities 🤖

This is where Immich truly shines! Its AI features transform your static photo library into a dynamic, searchable, and intelligent archive.

Immich uses various machine learning models (like CLIP, Facial Recognition models, etc.) to analyze your photos in the background.

A. How Immich AI Works:

• Object Recognition: Identifies objects, scenes, and concepts within your photos (e.g., “cat,” “beach,” “sunset,” “food”).
• Facial Recognition & Tagging: Detects faces, groups similar faces together, allowing you to name individuals.
• Optical Character Recognition (OCR): Can identify text within images, making signs, documents, or screenshots searchable.
• Search Engine (Typesense): Immich uses Typesense for blazing-fast search across all extracted metadata and your custom tags.

B. Enabling AI Features:

Most AI features are enabled by default in recent Immich versions, but it’s good to confirm your .env file settings.

1. Open your .env file:

   nano .env

2. Verify or Add These Lines:

   • IMAGE_GENERATION_ENABLED=true (This refers to features like Smart Search using CLIP and potentially other image generation tasks. Keep this true.)
   • FACE_DETECTION_ENABLED=true (Essential for facial recognition.)
   • TYPESENSE_ENABLED=true (Should be true by default, enables the search engine.)

   Note: Some advanced AI models might require specific hardware (e.g., GPUs) for optimal performance, but Immich’s core AI functions are designed to run well on modern CPUs.

3. Restart Immich if you made changes:

   docker compose down && docker compose up -d

   This ensures the new settings are picked up by the containers.

C. Post-Processing & AI Indexing:

After you upload photos or enable AI features, Immich will start processing them in the background. This involves:

• Thumbnail Generation: Creating various sizes of thumbnails for quick viewing.
• Metadata Extraction: Reading EXIF data (date, camera, location).
• AI Analysis: Running photos through the machine learning models for object detection, facial recognition, etc.

Patience is Key! ⏳ For large libraries, this can take a significant amount of time (hours or even days), depending on your server’s processing power. You’ll see the “background tasks” progress in the Immich UI (Administration -> Job Status).

D. Using Immich’s AI Search:

Once processing is complete, you can start searching!

1. Go to the Search bar in the Immich web UI or mobile app.
2. Type what you’re looking for:
   • Objects: “cat,” “dog,” “car,” “beach,” “mountain,” “pizza,” “tree,” “flower” 🐱🚗🏞️🍕
   • Concepts: “sunset,” “wedding,” “graduation,” “party” 🌅🎓🎉
   • Text: “receipt,” “street sign,” “menu” (if OCR is enabled and processed) 🧾
   • Locations: “Paris,” “London,” “New York” (if location data is present)
   • People: Once faces are detected and tagged, you can search for “John Doe” or “Sarah” and see all photos of them. 👨‍👩‍👧‍👦
3. Facial Recognition: Navigate to the People section in the sidebar. You’ll see detected faces grouped. Click on a group to view all photos of that person, and you can assign a name to them. Immich will learn over time and group new photos with that person.

The AI capabilities make finding specific photos incredibly easy, even years down the line, without having to manually tag everything. It’s truly transformative for photo management! ✨

6. Advanced Configurations & Best Practices ✨

To make your Immich server more robust, secure, and user-friendly, consider these advanced steps:

A. Reverse Proxy with HTTPS (Highly Recommended for External Access)

If you want to access Immich from outside your home network, a reverse proxy with HTTPS is essential for security.

• What it does:
  • Encrypts your connection (HTTPS) using SSL/TLS certificates (e.g., from Let’s Encrypt).
  • Allows you to use a custom domain name (e.g., photos.yourdomain.com) instead of an IP address and port.
  • Centralizes port forwarding (only port 443 needs to be open on your router).
• Popular Reverse Proxies:
  • Nginx Proxy Manager: User-friendly web UI for configuration. Great for beginners.
  • Caddy: Extremely simple to configure, automatically handles Let’s Encrypt certificates.
  • Traefik: Powerful and highly configurable, often used with Docker for automatic service discovery.
• How to Set Up:
  1. Get a domain name (if you don’t have one).
  2. Point a subdomain (e.g., photos.yourdomain.com) to your home IP address (using a Dynamic DNS service if your IP changes).
  3. Install your chosen reverse proxy (often in its own Docker container).
  4. Configure it to forward requests for photos.yourdomain.com to your Immich server’s internal IP and port (e.g., 192.168.1.100:2283).
  5. Ensure port 443 is forwarded from your router to your reverse proxy’s server.

B. Backup Strategy 💾

This is arguably the most important section! Self-hosting means you are responsible for your data’s safety.

• 3-2-1 Rule:
  • 3 copies of your data: The original, your Immich copy, and at least one backup.
  • 2 different media types: E.g., internal hard drives, external hard drives, cloud storage (encrypted!).
  • 1 off-site copy: A copy stored somewhere physically separate from your home.
• What to Back Up:
  • Immich Photo/Video Directory: The upload directory you configured (/mnt/photos/immich in our example). This is your primary asset storage.
  • PostgreSQL Database: This contains all your metadata, user accounts, albums, AI tags, etc. Back up the postgres volume (/mnt/immich_data/postgres if you mapped it). You can use pg_dump from within the immich-postgres container.
  • Typesense Data: The typesense volume (/mnt/immich_data/typesense). Less critical than PostgreSQL as it can be rebuilt, but backing it up saves re-indexing time.
  • Immich Configuration (.env and docker-compose.yml): Essential for easily restoring your setup. Store these in a safe place!
• Backup Tools: rsync (for file system backups), Duplicati, Proxmox Backup Server, cloud storage sync tools (e.g., S3, Backblaze B2).

C. Monitoring Your Server 📈

Keep an eye on your server’s health:

• CPU, RAM, Disk Usage: Use tools like htop, glances, or sudo docker stats to monitor resource consumption. Immich’s AI processes can be resource-intensive.
• Disk Space: Ensure you have enough free space for new uploads and future growth.
• Logs: Check Docker logs for any errors or warnings: docker compose logs -f (to follow logs) or docker logs immich-server (for specific container logs).

D. Updating Immich ⬆️

Immich is under active development, so updates are frequent and recommended!

1. Backup your data first! (Especially the database).
2. Stop Immich:

   cd ~/immich # Go to your Immich directory
   docker compose down

3. Pull latest files:

   wget -O docker-compose.yml https://raw.githubusercontent.com/immich-app/immich/main/docker/docker-compose.yml
   wget -O .env https://raw.githubusercontent.com/immich-app/immich/main/docker/example.env # Overwrite your .env if you wish to see new variables, but be careful! Best to manually merge differences.

   Instead of overwriting .env directly, it’s safer to compare your existing .env with example.env and manually add new variables or updated values.

4. Run database migration (if needed):

   docker compose run --rm immich-server npm run db:migrate -- --env production

5. Start Immich:

   docker compose up -d

   Docker will pull the latest images for each service.

E. Security Best Practices 🛡️

• Strong Passwords: For Immich admin account, database, and SSH access.
• Firewall: Only open necessary ports (22 for SSH, 80/443 for web access if using a reverse proxy, or 2283 if directly exposing Immich).
• Keep OS Updated: Regularly run sudo apt update && sudo apt upgrade -y.
• Limit User Access: If multiple users access Immich, ensure they have appropriate permissions.
• Disable Password Authentication for SSH: Use SSH keys instead.

7. Troubleshooting Common Issues 🔧

Even with a perfect guide, things can sometimes go wrong. Here are solutions to common Immich issues:

• “Cannot connect to the Docker daemon”:
  • Cause: Docker isn’t running, or your user isn’t in the docker group.
  • Solution:

    sudo systemctl start docker
    sudo usermod -aG docker $USER # Then log out and back in

• “Port 2283 already in use” (or similar port error):
  • Cause: Another application on your server is already using that port.
  • Solution:
    • Change Immich’s port in docker-compose.yml (e.g., 2284:2283).
    • Find and stop the conflicting application: sudo netstat -tulnp | grep 2283 will show you what’s using the port.
• Immich containers not starting or crashing repeatedly:
  • Cause: Configuration error, missing dependencies, resource issues, or previous crash.
  • Solution:
    • Check logs: docker compose logs (for all services) or docker logs immich-server (for a specific service). This is your best friend for debugging! Look for ERROR messages.
    • Check docker compose ps: See which containers are not Up.
    • Verify .env and docker-compose.yml: Double-check all paths, passwords, and settings.
    • Disk space: Ensure you’re not out of disk space.
    • Restart: docker compose down && docker compose up -d
• AI features not working or slow:
  • Cause: AI not enabled, insufficient resources, or background jobs not completed.
  • Solution:
    • Check .env: Ensure IMAGE_GENERATION_ENABLED and FACE_DETECTION_ENABLED are true.
    • Check Immich UI (Administration -> Job Status): Are the background jobs (e.g., Recognize Faces, Generate Thumbnails, Classify Images) running or queued? Give them time.
    • Server Resources: Monitor CPU and RAM usage. If they’re maxed out, your server might be underpowered for your library size.
    • Container logs: Check immich-microservices and immich-machine-learning logs for errors.
• Photos not appearing after import/upload:
  • Cause: Incorrect volume mapping in docker-compose.yml, file permissions, or import process not complete.
  • Solution:
    • Verify Volume Mapping: Ensure the host path in docker-compose.yml matches where your photos are actually stored and that the internal path (/usr/src/app/upload) is correct.
    • Check Permissions: Ensure the Docker user has read/write access to the storage directory on your host.
    • Check Immich CLI output: If using the CLI, confirm it reported successful uploads.
    • Check Job Status in Immich UI: Are Generate Thumbnails and Process Exif jobs running?

For more detailed troubleshooting, the official Immich documentation and their GitHub issues page are invaluable resources!

8. Conclusion: Your Private Photo Sanctuary Awaits! 🌟

Congratulations! You’ve successfully embarked on the journey of building your very own private photo server with Immich. You now have a powerful, intelligent, and secure platform to store, manage, and rediscover your cherished memories, all while retaining complete control and privacy.

Immich is a rapidly evolving project, constantly adding new features and improvements. Keep an eye on their official GitHub repository and community channels for updates and to contribute to its growth.

Embrace the power of self-hosting, reclaim your digital freedom, and enjoy your personalized photo sanctuary! If you found this guide helpful, share it with others who are looking to take back control of their photos. Happy self-hosting! 🚀❤️