How to Run Immich for Self-Hosted Photo Storage

How to Run Immich for Self-Hosted Photo Storage: Your Ultimate Guide

Tired of subscription fees and privacy concerns with cloud-based photo storage? Ready to take back control of your precious memories? If you’re a self-hosting enthusiast or just dipping your toes into the homelab world, Immich is a name you absolutely need to know. It’s a powerful, open-source, self-hosted photo and video backup solution that offers a remarkable alternative to giants like Google Photos or Apple Photos. At OpenClaw Resource, we believe in empowering you with the knowledge to build your own digital fortress, and Immich is a cornerstone of a robust self-hosted media strategy.

This comprehensive guide will walk you through everything you need to know to get Immich up and running, ensuring your photos are safe, private, and entirely under your command.

Why Choose Immich for Self-Hosted Photo Storage?

Before we dive into the “how,” let’s quickly discuss the “why.” Immich isn’t just another photo gallery. It’s designed to be a full-featured replacement for commercial cloud services, offering:

Complete Control: Your data stays on your hardware, in your home. No third-party access, no data mining.
Feature Parity (and Beyond): Immich boasts AI-powered object and facial recognition, automatic backup from mobile devices, shared albums, timeline view, map view, and even a robust API for integrations.
Open Source: The community-driven nature means constant development, transparency, and a vibrant support network.
Cost-Effective: Beyond your initial hardware investment, there are no recurring fees for storage.

Prerequisites: What You’ll Need

To successfully run Immich, you’ll need a few essential components. Don’t worry, most homelabbers will already have these or similar setups.

A Server: This can be anything from a Raspberry Pi 4 (for smaller libraries and lighter usage) to a more robust mini-PC like an Intel NUC, or a dedicated server running Proxmox or ESXi. The key is sufficient CPU power for AI tasks and enough RAM. We recommend at least 8GB RAM for a smooth experience.
Operating System: A Linux-based OS is preferred. Ubuntu Server, Debian, or your favorite distribution will work perfectly.
Docker and Docker Compose: Immich is containerized, making deployment incredibly straightforward. Ensure you have Docker and Docker Compose installed on your server.
Ample Storage: Photos and videos consume significant space. Plan for plenty of HDD or SSD storage. Consider a RAID setup (e.g., RAID 1 or RAID 5/6) for data redundancy using tools like TrueNAS SCALE or a software RAID solution.
Networking Basics: A basic understanding of networking, including port forwarding if you plan to access Immich from outside your home network (though we recommend a VPN for security).

Step-by-Step Immich Deployment with Docker Compose

This guide focuses on the most common and recommended deployment method: Docker Compose.

1. Prepare Your Server Environment

First, ensure your server is up to date and has Docker and Docker Compose installed. If you’re new to Docker, here’s a quick way to install it on Ubuntu:

sudo apt update
sudo apt upgrade -y
sudo apt install ca-certificates curl gnupg lsb-release -y
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y
sudo usermod -aG docker $USER # Add your user to the docker group
newgrp docker # Apply group changes immediately

Verify installations:

docker --version
docker compose version

2. Create Your Immich Directory and Docker Compose File

Choose a location on your server for your Immich configuration and data. We recommend creating a dedicated directory:

mkdir ~/immich
cd ~/immich

Now, create a docker-compose.yml file. You can find the latest official docker-compose.yml on the Immich GitHub repository. For simplicity, here’s a basic structure you can adapt. Use nano docker-compose.yml to create and edit the file:

version: "3.8"

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:release
    command: ["start-server.sh"]
    volumes:
      - immich_data:/usr/src/app/upload
      - /path/to/your/photos:/mnt/photos # Mount an external drive for existing photos
    env_file:
      - .env
    ports:
      - 2283:3001 # Immich web UI
    depends_on:
      - immich-redis
      - immich-database
      - immich-microservices
    restart: always

  immich-microservices:
    container_name: immich_microservices
    image: ghcr.io/immich-app/immich-microservices:release
    command: ["start-microservices.sh"]
    volumes:
      - immich_data:/usr/src/app/upload
      - /path/to/your/photos:/mnt/photos # Mount an external drive for existing photos
    env_file:
      - .env
    depends_on:
      - immich-redis
      - immich-database
    restart: always

  immich-web:
    container_name: immich_web
    image: ghcr.io/immich-app/immich-web:release
    environment:
      - VITE_SERVER_URL=http://localhost:2283 # Adjust if using a reverse proxy
    ports:
      - 3000:3000 # Immich web client
    restart: always

  immich-redis:
    container_name: immich_redis
    image: redis/redis-stack-server:latest
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - immich_redis:/data
    restart: always

  immich-database:
    container_name: immich_database
    image: postgres:15-alpine
    env_file:
      - .env
    volumes:
      - immich_database:/var/lib/postgresql/data
    restart: always

volumes:
  immich_data:
  immich_redis:
  immich_database:

Important Customizations:

/path/to/your/photos: Change this to the actual path on your server where your existing photos are stored, or where you want to store new uploads. This is crucial for Immich to access your media.
Ports: If port 2283 or 3000 are in use, change them to available ports.

3. Create Your `.env` File

Next, create a .env file in the same directory (nano .env) to store environment variables, especially sensitive ones like passwords. Replace the bracketed values with strong, unique passwords.

DB_HOSTNAME=immich-database
DB_USERNAME=postgres
DB_PASSWORD=[YOUR_POSTGRES_PASSWORD]
DB_DATABASE_NAME=immich
DB_PORT=5432

REDIS_HOSTNAME=immich-redis
REDIS_PASSWORD=[YOUR_REDIS_PASSWORD]
REDIS_PORT=6379

JWT_SECRET=[YOUR_JWT_SECRET]

Save both files.

4. Deploy Immich

With your docker-compose.yml and .env files ready, navigate to your ~/immich directory and run:

docker compose up -d

This command will download all necessary Docker images and start the Imm

How to Run Immich for Self-Hosted Photo Storage