Docker Compose: як підняти Immich для self-hosted зберігання фото з PostgreSQL і Redis

Immich Docker Compose – це практичний спосіб швидко розгорнути локальне сховище фото з окремими контейнерами для застосунку, PostgreSQL і Redis. Така схема підходить для homelab, де потрібен контроль над даними, нормальні бекапи і передбачуване оновлення без залежності від чужої хмари.

Нижче – робочий сценарій: підготовка каталогів, compose-файл, змінні середовища, запуск, перевірка і типові збої. Акцент не на тому, як просто запустити контейнери, а на тому, як не зламати бібліотеку фото при першому ж оновленні або перенесенні на інший сервер.

У зв’язці Immich, Immich відповідає за веб-інтерфейс, API і обробку медіа, PostgreSQL зберігає метадані, а Redis тримає кеш і черги фонових задач. Для домашньої інфраструктури це нормальний баланс між простотою і керованістю.

Що підготувати перед запуском Immich

Для Immich Docker Compose достатньо Linux-хоста з Docker Engine і плагіном Docker Compose, окремого каталогу під конфіг і окремого диска або розділу під бібліотеку. Фото і база даних мають жити не всередині контейнерів, а в bind mount або named volume, інакше відновлення після збою перетворюється на лотерею.

На практиці найчастіше ламається не сам застосунок, а шар зберігання. Якщо каталог з медіа лежить на повільному USB-диску або мережевому CIFS-монтуванні, індексація і генерація прев’ю починають гальмувати. Для невеликого homelab це ще терпимо, але при великій бібліотеці дрібні затримки дуже швидко накопичуються.

Базова структура каталогів може бути такою:

mkdir -p ~/immich/{postgres,redis,library,profile}
cd ~/immich

Каталог library краще одразу винести на файлову систему з нормальними правами доступу і передбачуваною поведінкою при великій кількості файлів. Для PostgreSQL важливо уникати випадкових chmod на живій базі – після цього контейнер інколи стартує, але потім сипле помилки по WAL.

Immich Docker Compose: базове налаштування з PostgreSQL і Redis

Найпростіший варіант – тримати всі сервіси в одному compose-стеку. Це дає прозору схему мережі, зрозумілий restart policy і нормальний порядок оновлення. Для homelab цього вистачає, поки Immich не починає конкурувати за ресурси з іншими важкими сервісами на тому ж хості.

Створіть файл docker-compose.yml:

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:release
    restart: unless-stopped
    depends_on:
      - redis
      - database
    ports:
      - "2283:2283"
    environment:
      DB_HOSTNAME: database
      DB_USERNAME: immich
      DB_PASSWORD: strongpassword
      DB_DATABASE_NAME: immich
      REDIS_HOSTNAME: redis
      UPLOAD_LOCATION: /usr/src/app/upload
    volumes:
      - ./library:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro

  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:release
    restart: unless-stopped
    volumes:
      - ./profile:/cache

  redis:
    container_name: immich_redis
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - ./redis:/data

  database:
    container_name: immich_postgres
    image: tensorchord/pgvecto-rs:pg14-v0.2.0
    restart: unless-stopped
    environment:
      POSTGRES_USER: immich
      POSTGRES_PASSWORD: strongpassword
      POSTGRES_DB: immich
    volumes:
      - ./postgres:/var/lib/postgresql/data

networks:
  default:
    name: immich_network

Такий compose-файл відображає типову схему Immich: сервер, окремий контейнер машинного навчання, Redis і PostgreSQL. Якщо розгортання йде за reverse proxy, публікацію порту можна прибрати і віддати трафік через Traefik, Nginx Proxy Manager або звичайний Nginx.

Окремий момент – контейнер бази. Для Immich зазвичай використовують PostgreSQL-сумісний образ з підтримкою векторного пошуку. Саме тут не варто самовільно міняти образ на довільний postgres без перевірки сумісності. На дрібному стенді це іноді стартує, але частина функцій пошуку або міграцій потім відвалюється не відразу, а після оновлення.

Як винести секрети і шляхи в .env

Для Immich Docker Compose краще відразу винести паролі, часовий пояс і шляхи в .env. Це спрощує перенесення стека між вузлами і зменшує ризик редагувати compose-файл під час оновлення. Головне – не зберігати .env у публічному репозиторії.

DB_USERNAME=immich
DB_PASSWORD=strongpassword
DB_DATABASE_NAME=immich
UPLOAD_LOCATION=./library
TZ=Europe/Kyiv

Після цього змінні можна підставити у compose-файл:

environment:
  DB_HOSTNAME: database
  DB_USERNAME: ${DB_USERNAME}
  DB_PASSWORD: ${DB_PASSWORD}
  DB_DATABASE_NAME: ${DB_DATABASE_NAME}
  REDIS_HOSTNAME: redis
  UPLOAD_LOCATION: /usr/src/app/upload
  TZ: ${TZ}

Окремо варто тримати в голові, що шлях до бібліотеки для контейнера і шлях на хості – не одне й те саме. Помилка в bind mount часто виглядає як порожня бібліотека після рестарту. Дані не зникли, але контейнер дивиться вже в інший каталог.

Запуск стека і первинна ініціалізація

Після підготовки compose-файлу стек піднімається стандартно. Якщо контейнери стартують у правильному порядку, веб-інтерфейс Immich стає доступним на опублікованому порту. Перший запуск може бути повільнішим через ініціалізацію бази, кешу і внутрішніх задач.

1. Перейдіть у каталог зі стеком.
2. Запустіть контейнери у фоновому режимі.
3. Дочекайтесь стабільного стану всіх сервісів.

cd ~/immich
docker compose pull
docker compose up -d
docker compose ps

Далі потрібно відкрити веб-інтерфейс за адресою хоста і створити адміністративний обліковий запис. Після цього вже можна додавати мобільні клієнти, імпортувати бібліотеку і налаштовувати резервне копіювання.

Є сенс не поспішати з масовим завантаженням фотографій у перші хвилини після запуску. Поки стек доганяє фонові задачі, великі імпорти можуть створити хибне враження, що сервер повільний сам по собі. Часто вузьке місце тут не CPU, а випадкові операції на диску.

Як перевірити, що Immich працює коректно

Перевірка Immich Docker Compose не зводиться до відкриття веб-сторінки. Треба переконатися, що піднялися всі контейнери, база приймає з’єднання, Redis не перезапускається по колу, а файли реально записуються в змонтований каталог на хості.

docker compose ps
docker compose logs --tail=100 immich-server
docker compose logs --tail=100 database
docker compose logs --tail=100 redis

Після входу в інтерфейс варто виконати коротку функціональну перевірку:

1. Завантажити кілька тестових фото.
2. Переконатися, що файли з’явилися в каталозі library.
3. Перевірити, що прев’ю і мініатюри генеруються без помилок.
4. Подивитися, чи немає повторних рестартів контейнерів.

Якщо фото видно в інтерфейсі, але на диску немає нових файлів, проблема майже завжди в volume mapping. Якщо є файли, але веб-інтерфейс показує помилки по індексації, тоді вже варто дивитися логи серверного контейнера і стан бази.

Де Immich Docker Compose зазвичай ламається

Найтиповіші збої в такому стеку пов’язані з трьома речами: права на каталоги, неузгоджені оновлення контейнерів і слабкий диск під бібліотеку. Саме ці проблеми дають більшість дивних симптомів – від завислих задач до пошкоджених прев’ю і довгих повторних індексацій.

Проблеми з PostgreSQL після оновлення

Якщо контейнер бази оновили невчасно або замінили образ без перевірки, Immich може не пройти міграції. Тут не допомагає бездумний restart. Спочатку потрібен backup каталогу бази або дамп, і лише потім будь-які експерименти.

Redis працює, але черги стоять

Коли Redis стартує, це ще не означає, що фонова обробка здорова. Якщо черги не розгрібаються, варто перевірити машинне навчання і логи серверного контейнера. У невеликих інсталяціях цю проблему часто маскує той факт, що інтерфейс зовні відповідає нормально.

Медіатека на мережевому сховищі

Immich можна прив’язати до NAS, але для активної бібліотеки це не завжди вдалий варіант. На NFS із хорошою мережею ще можна жити, а от CIFS із нестабільними атрибутами файлів регулярно приносить сюрпризи. Для cold storage підхід нормальний, для постійної індексації – вже спірний.

Нестиковка версій контейнерів

Оновлювати окремо лише один сервіс у стеку – погана ідея. Якщо вже оновлювати Immich Docker Compose, то комплектом, з перевіркою release notes і знімком даних перед змінами. Локальна фотобібліотека – не той сервіс, де варто економити на бекапах.

Що саме потрібно резервувати

У стеку Immich резервувати треба не тільки файли фотографій. Мінімальний набір – каталог бібліотеки, дані PostgreSQL і, за потреби, кеш або профілі, якщо не хочеться повторно проганяти частину важких задач. Без бази даних набір JPEG і HEIC на диску не дає повноцінного відновлення сервісу.

Практичний мінімум для бекапу такий:

• каталог library з оригіналами і похідними файлами;
• дамп PostgreSQL або файловий backup каталогу бази при зупиненому контейнері;
• compose-файл і .env;
• за потреби каталог profile для machine learning.

Оптимальна схема для homelab – окремий snapshot файлової системи плюс регулярний дамп бази. Копіювати живий каталог PostgreSQL побайтово без розуміння стану транзакцій – погана практика. Воно іноді відновлюється, але покладатися на це не варто.

Коли цей підхід уже не дуже підходить

Immich Docker Compose добре працює як self-hosted фотосховище для одного сервера або невеликого homelab-кластера без складної оркестрації. Якщо ж сервіс починає залежати від зовнішніх мережевих томів, агресивного autoscaling або кількох вузлів з різними ролями, Compose стає більше тимчасовим компромісом, ніж нормальною цільовою схемою.

До певного масштабу простий стек вигідний саме прозорістю. Видно, де база, де кеш, де медіа. Але коли потрібні жорсткі політики розміщення, окремі пулі дисків під hot і cold data, тонкий контроль ресурсів і централізовані секрети, логічніше дивитися в бік більш формалізованого розгортання.

Для більшості домашніх інсталяцій межа настає не по кількості користувачів, а по обсягу бібліотеки і швидкості диска. Якщо імпорт фото йде місяцями, а фонові задачі постійно наздоганяють потік нових файлів, спочатку варто вирішити питання I/O, а не шукати магію в параметрах Compose.

Що в підсумку

Immich Docker Compose закриває типовий сценарій self-hosted фототеки без зайвої складності: окремий сервіс, окрема база, окремий Redis і зрозумілі каталоги для даних. Слабке місце тут не сам Compose, а недооцінка дискової підсистеми, бекапів і дисципліни оновлень.

Якщо стек розгорнутий на локальному диску, дані винесені в постійні томи, а перед оновленням робиться backup, схема працює передбачувано. Далі вже має сенс додавати reverse proxy, зовнішній доступ, моніторинг і автоматизацію резервного копіювання. Офіційний сайт проєкту: immich.app. Офіційні релізи: Immich Releases.