SSD Nodes Learn
Посібники Matt ConnorВід Matt Connor · Оновлено 2026-07-24

Immich self-hosting: RAM та безпечне оновлення

Як уникнути помилки exit 137 при 6 GB RAM, налаштувати порт 2283 через HTTPS та вирішити проблему запуску Immich v3 з pgvecto.rs. Покрокова інструкція.

Що ви створюєте

Immich — це сервіс для самостійного хостингу бекапів фото та відео, повноцінна альтернатива Google Photos. Додаток для телефону завантажує вашу медіабібліотеку у фоновому режимі. Сервіс має часову шкалу, альбоми, розпізнавання облич та пошук на основі машинного навчання, який знаходить об'єкти на кшталт "beach" або конкретну людину без необхідності ручного тегування. Ви запускаєте його на власному VPS; оригінальні файли зберігаються на вашому диску, а сторонні компанії не сканують їх для продажу реклами.

Встановлення виконується за допомогою чотирьох контейнерів через Docker Compose файл проєкту. Цей етап займає десять хвилин. Основна складність полягає в іншому: контейнер машинного навчання споживає багато оперативної пам'яті на слабких серверах, оригінальні файли швидко займають місце на диску, мобільний додаток не працює з HTTP-серверами без шифрування, а часті зміни в Immich можуть призвести до того, що через недбалу docker compose pull база даних не зможе запуститися. Якщо врахувати ці чотири фактори, Immich працюватиме стабільно. Якщо їх ігнорувати — ви втратите цілий вихідний.

Prerequisites, and the honest gotchas

  • RAM: офіційна документація вказує мінімум 6 GB і рекомендовано 8 GB — вважайте 4 GB плюс swap мінімально допустимим рівнем. Контейнери immich-server та Postgres споживають небагато ресурсів. Контейнер immich-machine-learning є найбільш вимогливим — він завантажує моделі CLIP та face-recognition у RAM для створення пошукових індексів; на системі з 2 GB ядро (kernel) завершить його роботу. Додайте swap, навіть якщо у вас є 4 GB.
  • Disk: виділяйте місце під всю вашу бібліотеку з запасом. Оригінальні файли копіюються повністю, крім того Immich створює мініатюри та прев'ю (приблизно +10–20% до об'єму). Для колекції фото у 200 GB потрібен том об'ємом 300 GB. Postgres порівняно з цим займає мало місця.
  • CPU: підійде будь-який сучасний KVM VPS, але ML на CPU працює повільно. Розумне індексування (smart-search) великого імпорту може тривати годинами у фоновому режимі. Це нормально; GPU не є обов'язковим.
  • Доменне ім'я, спрямоване на VPS. Мобільний додаток потребує підключення через HTTPS, тому рекомендується використовувати reverse proxy. Це аналогічна конфігурація, як у self-hosted Nextcloud instance with Docker, TLS and backups — Immich є фото-аналогом цього файлового сервера.
  • Встановлені Docker та Compose plugin — Docker Engine та плагін Compose v2 з офіційного репозиторію apt, як описано в our Docker Compose basics guide.

Step 1: Додайте swap перед іншими діями

Найчастіша причина збоїв Immich на слабких VPS — завершення процесу ML контейнера через OOM-killer. Спочатку виділіть ядру місце для використання пам'яті.

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h

free -h тепер має показувати рядок Swap: з 4.0Gi. Це не пришвидшить ML, але запобігатиме аварійному завершенню контейнера під час індексації на машинах з 4 GB RAM.

Step 2: Завантажте офіційні compose та env — використовуйте оригінали, а не копії

Immich фіксує версії сервісів та, що критично важливо, образ бази даних у своїх файлах. Не використовуйте compose-файл з блогів (включаючи цей) як першоджерело. Завантажте файли релізу:

sudo mkdir -p /opt/immich && cd /opt/immich
sudo wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
sudo wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

Вони взяті з тегованого релізу, тому посилання на образи будуть актуальними. Compose-файл визначає чотири сервіси. Варто знати призначення кожного з них перед початком роботи:

  • immich-server (ghcr.io/immich-app/immich-server, контейнер immich_server) — API та веб-інтерфейс, працює на порту 2283. Монтує ваші завантаження у /data.
  • immich-machine-learning (ghcr.io/immich-app/immich-machine-learning, контейнер immich_machine_learning) — пошук CLIP та розпізнавання облич. Кешує завантажені моделі у volume model-cache. Цей сервіс споживає багато оперативної пам'яті.
  • database (контейнер immich_postgres) — Postgres з розширенням VectorChord для векторного пошуку. Тег образу зафіксовано через digest безпосередньо у compose-файлі, наприклад ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:.... Старі конфігурації використовували pgvecto.rs; підтримку було видалено в Immich v3.0, тому всі сучасні інсталяції використовують VectorChord. Ніколи не редагуйте цей тег вручну.
  • redis (контейнер immich_redis) — екземпляр Valkey/Redis для черг завдань.

Step 3: Налаштування .env — де зберігаються ваші фото та база даних

Відкрийте .env і налаштуйте чотири параметри. Усе, що нижче позначеної лінії, залишається без змін.

# Where original uploads are stored on the host
UPLOAD_LOCATION=/opt/immich/library

# Where the Postgres data lives. NEVER put this on an NFS/network share.
DB_DATA_LOCATION=/opt/immich/postgres

# "v3" is a floating tag that tracks the latest v3.x. Pin a full tag like
# v3.0.2 instead — then you upgrade on purpose, not by surprise.
IMMICH_VERSION=v3.0.2

# Change this to a long random string. Letters and digits only.
DB_PASSWORD=REPLACE_WITH_A_LONG_RANDOM_STRING

# Set your timezone so timestamps and "on this day" line up
TZ=Europe/London

###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

Два правила, щоб уникнути проблем. UPLOAD_LOCATION має вказувати на ваш великий диск — якщо ви пізніше підключите том для даних, одразу вкажіть його шлях монтування, оскільки перенесення вже налаштованого тому вимагатиме перенесення мініатюр та оновлення шляхів до активів. DB_DATA_LOCATION має бути на локальному диску: використання NFS або SMB для Postgres призводить до пошкодження даних, про що прямо сказано в документації. Якщо у DB_PASSWORD використовувати лише літери та цифри, ви уникнете помилок екранування у рядках підключення.

Step 4: Перший запуск та створення адміністратора

cd /opt/immich
sudo docker compose up -d
sudo docker compose ps

Правильним результатом є чотири контейнери, усі у стані running і згодом healthy:

NAME                      STATUS
immich_machine_learning   Up (healthy)
immich_postgres           Up (healthy)
immich_redis              Up (healthy)
immich_server             Up (healthy)

Перший up завантажує кілька гігабайт образів, тому зачекайте. Стежте за прогресом за допомогою sudo docker compose logs -f immich-server; коли сервер буде готовий, він залогує прослуховування порту 2283. Тепер відкрийте http://YOUR_SERVER_IP:2283 у браузері. При першому візиті з'явиться майстер Getting Started — перший створений вами обліковий запис стане адміністратором. Встановіть надійний пароль; цей обліковий запис керує налаштуваннями сервера, користувачами та конфігурацією ML, яка знадобиться пізніше.

Step 5: Мобільний додаток та фонове резервне копіювання

Встановіть "Immich" з App Store або Play Store. На екрані входу потрібно ввести Server Endpoint URL. Введіть повну URL-адресу, включаючи схему, наприклад https://photos.example.com (додаток автоматично додасть /api). Увійдіть за допомогою створеного облікового запису, потім відкрийте екран Backup у додатку, виберіть альбоми для захисту (зазвичай Camera та Screenshots) і увімкніть Background backup. iOS обмежує фонове резервне копіювання на рівні ОС — завантаження у фоновому режимі виконуються лише тоді, коли це дозволяє система, тоді як завантаження у передньому плані працюють завжди.

Саме на цьому етапі часто виникають проблеми, тому прочитайте Step 6, перш ніж намагатися налаштувати додаток.

Step 6: HTTPS через reverse proxy — та правило повного URL

Мобільному додатку обов'язково потрібен HTTPS. Встановіть reverse proxy перед портом 2283 і завершіть TLS на ньому. Якщо ви вже використовуєте кілька контейнерів, Traefik з автоматичним TLS для кількох Docker-додатків — найзручніший варіант: один блок label спрямовує photos.example.com на контейнер immich-server і автоматично отримує сертифікат. Якщо ви віддаєте перевагу nginx, інструкція Let's Encrypt з Certbot та nginx допоможе отримати сертифікат та блок proxy_pass http://127.0.0.1:2283;. Для Immich важливе одне налаштування проксі: збільште ліміт розміру завантаження, оскільки відео з телефону мають великий розмір. В nginx це client_max_body_size 50000M; всередині server block — значення за замовчуванням 1 MB призводить до помилки 413 Request Entity Too Large при завантаженні відео.

Правило, яке застосовує додаток: endpoint має бути доступним і, на практиці, обов'язково через HTTPS. Помилка "the app cannot reach the server" виникає через використання http:// endpoint або прямої IP-адреси без вказання порту — це описано нижче як окремий тип помилки.

Step 7: Зовнішні бібліотеки проти завантажень — імпорт існуючої структури фотографій

Існує два способи додавання фотографій до Immich, і вони відрізняються.

  • Uploads — це активи, якими керує Immich. Додаток або веб-інтерфейс копіює файл у UPLOAD_LOCATION. Immich може перейменовувати, переміщувати та видаляти їх.
  • External libraries — це імпорт файлів лише для читання, які вже знаходяться в папці на вашому сервері (наприклад, стара структура Pictures або експорт з NAS). Immich індексує їх на місці та відображає в часовій шкалі, але ніколи не змінює та не видаляє оригінали.

Щоб імпортувати існуючу структуру, підмонтуйте її в режим read-only у контейнер сервера. Відредагуйте docker-compose.yml у розділі immich-server: та додайте volume:

  immich-server:
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /etc/localtime:/etc/localtime:ro
      - /srv/photos:/mnt/media/photos:ro

Параметр :ro гарантує, що Immich ніколи не зможе змінити оригінали. Перестворіть контейнер за допомогою sudo docker compose up -d, потім у веб-інтерфейсі перейдіть у меню вашого аватара → Administration → External Libraries → Create Library, виберіть користувача, натисніть Add у розділі Folders і введіть шлях всередині контейнера — /mnt/media/photos, а не шлях хост-системи /srv/photos. Натисніть Scan. Використання шляху хост-системи замість шляху контейнера — це найпоширеніша помилка при роботі з зовнішніми бібліотеками; у такому разі сканування не знайде жодного активу.

Step 8: Дисципліна оновлення, необхідна для Immich

Цей етап визначає стабільність роботи Immich. Immich оновлюється швидко; розробники не здійснюють backport виправлень і не підтримують відкат версій (downgrades). Використання тегу v3 без фіксації версії призведе до пошкодження бази даних. Необхідна дисципліна:

  1. Фіксуйте версію. Встановлюйте IMMICH_VERSION на конкретний тег, наприклад v3.0.2, а не на плаваючий тег v3, який завжди завантажує останню версію v3.x.
  2. Завжди читайте release notes перед оновленням. Там вказано несумісні зміни (breaking changes), особливо щодо бази даних або розширень vector-extension. Приклад — реліз v3.0: було повністю видалено pgvecto.rs. Користувачі зі старим розширенням мали завершити міграцію на VectorChord (впроваджену в v1.133) перед оновленням.
  3. Спочатку зробіть резервну копію бази даних (Step 9). Це обов'язково, особливо якщо в примітках згадується база даних.
  4. Завантажуйте новий compose file. IMMICH_VERSION фіксує лише образи server та ML. Образ Postgres фіксується через digest всередині docker-compose.yml, тому версії, що потребують нових розширень бази даних, постачаються з новим compose file. Завантажте обидва файли релізу, застосуйте ваші значення .env та виконайте оновлення.
  5. Оновлюйте мобільні клієнти одночасно з сервером. Сервер підтримує лише свою мажорну версію, а додаток — поточну та попередню мажорні версії. Якщо сервер оновлено раніше за додаток, на телефоні з'явиться помилка Your app major version is not compatible with the server!. Найбезпечніше спочатку оновити додаток.

Команди для виконання після підготовки нових файлів:

cd /opt/immich
sudo docker compose pull
sudo docker compose up -d
sudo docker image prune

Step 9: Резервне копіювання — дамп бази даних ПЛЮС оригінали, та перевірка

Резервна копія Immich складається з двох частин; кожна з них окремо є марною. База даних містить структуру альбомів, обличчя, індекси пошуку та зв'язок між об'єктом та файлом. Директорія originals містить самі фотографії. Відновлення лише однієї частини призведе до результату: або фото без організації, або порожню структуру, що посилається на відсутні файли.

Зробіть дамп бази даних за допомогою pg_dump всередині контейнера Postgres — саме базу immich, а не весь кластер:

sudo docker exec -t immich_postgres pg_dump --clean --if-exists \
  --dbname=immich --username=postgres | gzip > /opt/immich/immich-db-$(date +%F).sql.gz

Потім зробіть резервну копію UPLOAD_LOCATION — усього дерева /opt/immich/library, зокрема підпапок library/, upload/ та profile/ — за допомогою restic, rsync або borg на інший пристрій або в object storage. Спочатку робіть дамп бази даних, а потім — файлів. Це гарантує, що дамп не посилатиметься на фото, яке ще не скопійовано у файлову копію. Зовнішні бібліотеки потрібно резервувати окремо у їхньому первинному джерелі; Immich не є їхнім власником.

Тепер етап, який усі пропускають: перевірте відновлення. Відновлення має виконуватися на чистому стеку, сервер якого ніколи не запускався, на образі Postgres, чиє розширення vector сумісне з дампом — саме тому не можна довільно обирати тег образу БД. На чистому пристрої з тим самим compose та .env видаліть усі старі дані, запустіть лише базу даних, а потім завантажте дамп:

cd /opt/immich
sudo docker compose down -v
sudo docker compose pull
sudo docker compose create
sudo docker start immich_postgres
sleep 10
gunzip --stdout immich-db-2026-07-15.sql.gz |
  sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" |
  sudo docker exec -i immich_postgres psql --dbname=immich --username=postgres --single-transaction --set ON_ERROR_STOP=on
sudo docker compose up -d

Перезапис sed для search_path є обов'язковим для бази даних VectorChord — якщо пропустити цей крок, відновлення перерветься. Коли стек запуститься з вашими оригіналами, відкрийте web UI: якщо фото та альбоми на місці, резервна копія працює. Якщо ви ніколи не проводили цю перевірку, у вас немає резервної копії — у вас є лише надія.

Режими відмови та відповідні рядки

Контейнер ML завершено через OOM-kill. sudo docker compose logs immich-machine-learning переривається, docker compose ps вказує на Restarting, а код виходу — 137. sudo dmesg | grep -i oom підтверджує це: Out of memory: Killed process ... (python3). Після цього завдання пошуку та розпізнавання облич зупиняються. Причина: недостатньо RAM для моделей. Способи вирішення (у порядку пріоритетності): додайте swap (Крок 1); збільште обсяг RAM на VPS; або, якщо це неможливо, вимкніть ML у Administration → Settings → Machine Learning Settings, вимкнувши Smart Search та Facial Recognition — ви збережете бекапи та альбоми, але втратите пошук за вмістом. Видалення сервісу immich-machine-learning із compose file дасть такий самий результат.

Postgres не запускається після оновлення. У логах сервера повторюється рядок на кшталт The database currently has VectorChord 0.5.3 activated, but the Postgres instance only has 0.4.2 available. This most likely means the extension was downgraded. — або, у старіших стеках, The pgvecto.rs extension is not available in this Postgres instance.. Причина: образ бази даних має версію розширення старішу за версію оновлених даних. Це зазвичай стається через ручну зміну тегу образу або відновлення дампу нової версії на старий образ. Рішення: використовуйте образ Postgres, який відповідає вашим даним — візьміть compose file з релізу, що відповідає вашій базі даних; не виконуйте downgrade і відновлюйте дані лише на сумісний образ.

Мобільний додаток не може з'єднатися з сервером. Після введення URL на екрані входу з'являється помилка з'єднання / Server is not reachable. Три причини: ви ввели http:// замість https:// (який обслуговується проксі; або ви підключилися безпосередньо до backend, не вказавши порт, тому запит пішов на example.com (порт 443) замість example.com:2283; або reverse proxy не перенаправляє /api. Вирішення: введіть повний URL https://photos.example.com і спочатку перевірте його завантаження у браузері телефону. Якщо браузер працює, а додаток — ні, то проксі видаляє шлях або сертифікат є самопідписаним — додаток відхиляє неперевірені сертифікати.

Закінчилося місце на диску під час імпорту. Завантаження переривається, мініатюри стають порожніми, а в логах з'являється ENOSPC: no space left on device або (для Postgres) could not extend file ... No space left on device. df -h показує, що том UPLOAD_LOCATION заповнений на 100%. Саме тому необхідно розраховувати розмір диска перед імпортом великої бібліотеки. Вирішення: підключіть більший том, зупиніть stack, перенесіть UPLOAD_LOCATION на нього, оновіть .env і запустіть знову — або розширте існуючий диск, якщо це дозволяє провайдер. Postgres може заблокуватися при переповненні диска, тому спочатку звільніть місце та перезапустіть контейнер бази даних, перш ніж припускати пошкодження даних.

FAQ

Скільки RAM та дискового простору потрібно Immich?

Офіційні вимоги Immich: мінімум 6 GB RAM та рекомендовано 8 GB. Практичний мінімум для невеликої бібліотеки — 4 GB з урахуванням swap. У будь-якому разі налаштуйте swap, оскільки контейнер machine-learning викликає пікові навантаження. Для дискового простору плануйте обсяг, що дорівнює розміру всієї бібліотеки плюс приблизно 10–20% на згенеровані мініатюри та прев'ю на локальному сховищі. Ніколи не розміщуйте директорію з даними Postgres на мережевій шарі. Якщо ви ще обираєте інші сервіси, посібник з self-hosting у 2026 році порівнює навантаження Immich з іншими сервісами.

Чи можна запустити Immich без GPU?

Так. Контейнер machine-learning стабільно працює на CPU. GPU лише прискорює індексацію smart-search та, за умови використання відповідного образу, транскодування відео. При використанні CPU початкова індексація великої бібліотеки може тривати кілька годин у фоновому режимі, але це не перериває процес резервного копіювання або перегляду. Якщо ваш пристрій занадто слабкий для ML, ви можете вимкнути Smart Search та Facial Recognition у налаштуваннях адміністратора, залишивши всі інші функції.

Як безпечно оновити Immich?

Зафіксуйте IMMICH_VERSION на конкретному тегу, як-от v3.0.2, перед кожним оновленням читайте release notes та спочатку зробіть резервну копію бази даних. Оскільки образ Postgres зафіксовано всередині docker-compose.yml, а не через IMMICH_VERSION, заново завантажте compose file та example.env з потрібної версії, застосуйте ваші налаштування та запустіть docker compose pull && docker compose up -d. Не залишайте версію плаваючою (floating) — Immich випускає версії з несумісними змінами (breaking changes) і не підтримує відкат (downgrade).

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

Дві речі разом: pg_dump бази даних immich та всю директорію UPLOAD_LOCATION originals. База даних містить альбоми, обличчя та відповідність між активами та файлами; директорія містить самі фотографії. Для відновлення потрібні обидва компоненти, а також образ бази даних з сумісним векторним розширенням. Спочатку зробіть дамп бази даних, а потім копіюйте файли. Хоча б раз протестуйте відновлення на тестовому пристрої — неперевірена резервна копія не є резервною копією.

Як імпортувати мою існуючу папку з фото?

Змонтуйте папку в режимі read-only у контейнер immich-server як додатковий volume (наприклад, - /srv/photos:/mnt/media/photos:ro), перестворіть контейнер, а потім у розділі Administration → External Libraries створіть бібліотеку та додайте шлях контейнера /mnt/media/photos. Immich індексує файли на місці та ніколи не змінює та не видаляє їх. Найпоширеніша помилка — введення шляху хоста замість шляху контейнера, через що сканування не знаходить файлів.

#immich#photos#docker#self-hosting#backups