Immich self-hosting: RAM na upgrades salama

Unachojenga

Immich ni huduma ya kuhifadhi picha na video inayojiendesha (self-hosted) — mbadala halisi wa Google Photos. Ina programu ya simu inayopakia picha zako za kamera kwa nyuma, timeline, albamu, utambuzi wa sura, na utafutaji wa machine-learning unaoweza kupata "beach" au mtu bila wewe kuweka lebo. Unaiendesha kwenye VPS yako mwenyewe, faili halisi zinabaki kwenye diski yako, na hakuna anayezichunguza ili kukuuzia bidhaa.

Usakinishaji unahusisha container nne kutoka kwenye Docker Compose file ya mradi wenyewe. Sehemu hiyo inachukua dakika kumi. Sehemu nyingine ya mwongozo huu ndipo changamoto zilipo: container ya machine-learning hutumia RAM nyingi kwenye mashine ndogo, faili halisi zinatumia diski haraka, programu ya simu haikubali server ya HTTP ya kawaida, na Immich hutoa mabadiliko yanayovunja mfumo mara kwa mara kiasi kwamba docker compose pull usiojali unaweza kuacha database yako ikiwa haiwezi kuanza. Chukulia mambo hayo manne kwa umakini na Immich itakuwa imara sana. Ukiyapuuza, utapoteza wikendi nzima.

Mahitaji ya awali, na changamoto za kweli

• RAM: hati rasmi zinasema kiwango cha chini ni 6 GB na 8 GB inashauriwa — chukulia 4 GB pamoja na swap kama kiwango cha chini kabisa. Container za immich-server na Postgres zinatumia rasilimali kidogo. Container ya immich-machine-learning ndiyo inayotumia rasilimali nyingi — inapakia mifano ya CLIP na face-recognition kwenye RAM ili kutengeneza search indexes, na kwenye mashine ya 2 GB kernel itazima. Ongeza swap hata kama una 4 GB.
• Diski: itayarishe kwa ajili ya maktaba yako nzima, na ziada kidogo. Picha zako asilia zinanakiliwa zote, na Immich inatengeneza thumbnails na picha za preview (takriban 10–20% ya ziada). Mkoleto wa picha wa 200 GB unahitaji volume ya 300 GB. Postgres ni ndogo ikilinganishwa na hili.
• CPU: VPS yoyote ya kisasa ya KVM inafaa, lakini ML kwenye CPU ni polepole. Uundaji wa smart-search indexing kwa import kubwa unaweza kuchukua saa kadhaa nyuma ya pazia. Hii ni hali ya kawaida; haihitaji GPU.
• Jina la domain linaloelekeza kwenye VPS. App ya simu inapendelea zaidi endpoint ya HTTPS, na unahitaji reverse proxy mbele. Mpangilio huu ni sawa na instance ya self-hosted Nextcloud kwa kutumia Docker, TLS na backups — Immich ni mbadala wa picha kwa seva hiyo ya faili.
• Docker na Compose plugin vilivyosakinishwa — Docker Engine pamoja na Compose v2 plugin kutoka kwenye apt repository ya Docker, kama ilivyoelezwa kwenye mwongozo wetu wa Docker Compose basics.

Hatua ya 1: Ongeza swap kabla ya kufanya jambo lingine lolote

Tatizo la kawaida zaidi la Immich kwenye VPS ndogo ni container ya ML kufiliwa na kumbukumbu (OOM-killed). Toa nafasi kwa kernel ili iweze kufanya kazi vizuri.

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 sasa inapaswa kuonyesha mstari wa Swap: wenye 4.0Gi. Hii haitaongeza kasi ya ML, lakini itazuia container isife wakati wa ku-index kwenye mashine ya GB 4.

Hatua ya 2: Pakua compose na env rasmi — tumia zao, siyo nakala

Immich imefunga matoleo ya huduma zake, na muhimu zaidi, picha ya database ndani ya faili zinazotumwa. Usibandike faili ya compose kutoka kwenye blogu (ikiwemo hii) kama chanzo chako cha uhakika. Pakua mali za toleo (release assets):

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

Hizi zinatoka kwenye toleo lililotiwa alama, hivyo marejeleo ya picha yanaendana. Faili ya compose inafafanua huduma nne, na ni muhimu kujua kila moja ni nini kabla ya kuanza:

• immich-server (ghcr.io/immich-app/immich-server, container immich_server) — API na web UI, inayosikiliza kwenye port 2283. Inafunga (mounts) nyota zako (uploads) kwenye /data.
• immich-machine-learning (ghcr.io/immich-app/immich-machine-learning, container immich_machine_learning) — CLIP search na utambuzi wa sura. Inahifadhi (caches) mifano iliyopakuliwa kwenye volume ya model-cache. Hii hutumia nyingi ya kumbukumbu (memory).
• database (container immich_postgres) — Postgres ikiwa na extension ya VectorChord, inayowezesha utafutaji wa ufanani (similarity search). Tag ya picha imefungwa kwa digest ndani ya faili ya compose, kwa mfano ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:.... Mifumo ya zamani ilitumia pgvecto.rs; msaada wake uliondolewa katika Immich v3.0, hivyo chochote unachoweka leo ni VectorChord. Usibadilishe tag hii kwa mkono.
• redis (container immich_redis) — instance ya Valkey/Redis kwa ajili ya foleni za kazi (job queues).

Hatua ya 3: Sanidi .env — mahali picha na database yako zilipo

Fungua .env na uweke mambo manne. Kila kitu chini ya mstari uliowekwa kinabaki kama kilivyo.

# 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

Sheria mbili za kuepuka matatizo. UPLOAD_LOCATION inapaswa kuelekea kwenye diski yako kubwa — ikiwa utaunganisha data volume baadaye, iweke kwenye njia yake ya mount tangu mwanzo, kwa sababu kuhamisha baada ya hapo kutamaanisha kuhamisha thumbnails na kusasisha njia za asset. Pia, DB_DATA_LOCATION lazima iwe kwenye diski ya ndani: Postgres huharibu data ikiwa iko kwenye NFS au SMB share, na hati rasmi zinathibitisha hilo. Ukitumia herufi na namba pekee kwenye DB_PASSWORD, utaepuka aina fulani ya hitilafu za escaping kwenye connection-string.

Hatua ya 4: Uzinduzi wa kwanza na kutengeneza mtumiaji wa admin

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

Matokeo sahihi ni kontena nne, zote running na hatimaye healthy:

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

up wa kwanza huvuta picha (images) za gigabytes kadhaa, hivyo toa muda wa kutosha. Fuatilia maendeleo kwa kutumia sudo docker compose logs -f immich-server; seva itatoa taarifa kuwa inasikiliza kwenye port 2283 itakapokuwa tayari. Sasa fungua http://YOUR_SERVER_IP:2283 kwenye kivinjari (browser). Ziara ya kwanza itaonyesha mwongozo wa Getting Started — akaunti ya kwanza unayotengeneza ndiyo itakuwa admin. Weka nywila (password) imara; akaunti hii inamiliki mipangilio ya seva, usimamizi wa watumiaji, na usanidi wa ML utakaohitaji baadaye.

Hatua ya 5: Programu ya simu na nakala ya akiba ya nyuma

Pakua "Immich" kutoka App Store au Play Store. Kwenye skrini ya kuingia, itakuomba Server Endpoint URL. Ingiza URL kamili ikiwa na scheme, kwa mfano https://photos.example.com (programu itaongeza /api yenyewe). Ingia kwa kutumia akaunti uliyotengeneza, kisha fungua skrini ya Backup ya programu, chagua albamu za kulinda (kawaida Camera na Screenshots), na washa Background backup. iOS hupunguza kasi ya nakala ya akiba ya nyuma kwa kutumia OS — pakiaji wakati programu imefunguliwa (foreground) hufanya kazi kila wakati, lakini pakiaji wa nyuma (background) hutokea OS inaporuhusu.

Hapa ndipo watu wengi hukwama, hivyo soma Hatua ya 6 kabla ya kuanza kutumia programu.

Hatua ya 6: HTTPS kupitia reverse proxy — na sheria ya full-URL

Programu ya simu inahitaji HTTPS. Weka reverse proxy mbele ya port 2283 na ukomatishe TLS hapo. Kama tayari unatumia container nyingi, Traefik yenye TLS ya kiotomatiki kwa programu nyingi za Docker ndiyo chaguo bora zaidi — kundi moja la label hutoa njia ya photos.example.com kwenda kwenye container ya immich-server na kupata cheti kwa ajili yako. Kama unapendelea nginx, mwongozo wa Let's Encrypt kwa kutumia Certbot na nginx utakupa cheti na block ya proxy_pass http://127.0.0.1:2283;. Mpangilio mmoja wa proxy ni muhimu kwa Immich: ongeza kikomo cha ukubwa wa faili linalopakiwa, kwa sababu video za simu ni kubwa. Kwenye nginx, hiyo ni client_max_body_size 50000M; ndani ya server block — kiwango cha kawaida cha 1 MB hukataa upakiaji wa video kwa 413 Request Entity Too Large.

Sheria inayotumiwa na programu: endpoint lazima ifikike na, kwa vitendo, lazima iwe HTTPS. Endpoint za http://, au IP ya moja kwa moja bila port, ndizo chanzo cha kosa la "the app cannot reach the server" — kosa hili limefafanuliwa hapa chini.

Hatua ya 7: Maktaba ya nje dhidi ya nyota (uploads) — kuingiza mti wa picha uliopo

Kuna njia mbili za picha kuingia kwenye Immich, na ni tofauti.

• Uploads ni rasilimali ambazo Immich inazimiliki. Programu au uploader wa wavuti unanakili faili ndani ya UPLOAD_LOCATION. Immich inaweza kuzibadilisha majina, kuzisogeza, au kuzifuta.
• External libraries ni uingizaji wa kusoma tu (read-only) wa faili ambazo tayari zipo kwenye folda kwenye seva yako — mti wa Pictures wa zamani, au export ya NAS. Immich inaweka alama (index) mahali zilipo na kuzionyesha kwenye timeline, lakini haibadilishi au kufuta faili asilia kamwe.

Ili kuingiza mti uliopo, uunganishe (mount) katika hali ya kusoma tu (read-only) ndani ya container ya seva. Hariri docker-compose.yml chini ya immich-server: na uongeze volume:

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

:ro inahakikisha kuwa Immich haiwezi kamwe kugusa faili asilia. Recreate container kwa kutumia sudo docker compose up -d, kisha kwenye web UI nenda kwenye avatar yako → Administration → External Libraries → Create Library, chagua mtumiaji anayemiliki, bofya Add chini ya Folders, na uweke njia ya container — /mnt/media/photos, siyo njia ya host /srv/photos. Bofya Scan. Kutumia njia ya host badala ya njia ya container ndiyo kosa namba moja la maktaba ya nje; scan haitapata kitu na itatoa ripoti ya rasilimali sifuri.

Hatua ya 8: Nidhamu ya maboresho inayohitajika na Immich

Hii ndiyo sehemu inayotofautisha Immich inayofanya kazi vizuri na ile iliyoharibika. Immich hutoa toleo jipya haraka na hairudishi nyuma marekebisho (backport) wala kusaidia kurudisha toleo la zamani (downgrade). Kufuatilia tag ya v3 bila mpangilio hatimaye kutaharibu database yako. Nidhamu inayohitajika:

1. Weka toleo maalum (Pin a version). Weka IMMICH_VERSION kwenye tag mahususi kama v3.0.2, usitumie v3 inayovuta v3.x mpya kila wakati.
2. Soma maelezo ya toleo (release notes) kila wakati kabla ya kuboresha. Mabadiliko yanayovunja mfumo — hasa mabadiliko ya database au vector-extension — yanatajwa hapo. Toleo la v3.0 ni mfano wa wazi: liliondoa pgvecto.rs kabisa, hivyo mtu yeyote aliyekuwa akitumia extension ya zamani alilazimika kumaliza uhamishaji wa VectorChord (uliyoanzishwa kwenye v1.133) kabla ya kuweza kuendelea.
3. Nakili database kwanza (Hatua ya 9). Kila wakati, na zaidi ikiwa maelezo yanataja database.
4. Chukua faili mpya ya compose pia. IMMICH_VERSION huweka tu picha za server na ML. Picha ya Postgres imewekwa kwa digest ndani ya docker-compose.yml, hivyo toleo linalohitaji extension mpya ya database hutoa faili mpya ya compose. Pakua tena mali zote mbili za toleo, weka tena thamani zako za .env, kisha boresha.
5. Sasisha programu za simu (mobile clients) wakati huo huo. Server inaweza kuwasiliana tu na toleo lake kuu (major version) linalolingana, na app inasaidia toleo la sasa na la kuu lililopita. Server iliyozidi app itaonyesha Your app major version is not compatible with the server! kwenye simu mpaka usisashe app, hivyo ni salama zaidi kusasisha app kwanza.

Amri halisi, baada ya kuwa na faili mpya:

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

Hatua ya 9: Backups — database dump PAMOJA na originals, na uifanyie majaribio

Backup ya Immich ina vitu viwili, na kimoja bila kingine hakina faida. Database huhifadhi muundo wa albamu, nyuso, search indexes, na ramani kutoka kwenye asset hadi kwenye file. Originals directory huhifadhi picha halisi. Ukirejesha kimoja bila kingine, utapata picha bila mpangilio au shell tupu inayoelekeza kwenye files ambazo hazipo.

Fanya dump ya database kwa kutumia pg_dump ndani ya Postgres container — database ya immich pekee, siyo cluster nzima:

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

Kisha backup UPLOAD_LOCATION — mti mzima wa /opt/immich/library, na hasa subfolders za library/, upload/ na profile/ — kwa kutumia restic, rsync au borg kwenda kwenye mashine nyingine au object storage. Fanya database kwanza na files baadae, ili dump isirejelee picha ambayo file backup bado haijainakili. Libraries za nje unazizihifadhi kando kwenye vyanzo vyake halisi; Immich haimiliki hizo libraries.

Sasa sehemu ambayo kila mtu huipuuza: jaribu kurejesha (test the restore). Kurejesha lazima kufanyika kwenye stack mpya ambayo server yake haijawahi kuanza, kwenye Postgres image ambayo vector extension yake inaendana na dump — ndiyo maana usipange DB image tag kwa kubahatisha. Kwenye box mpya lenye compose na .env sawa, futa hali yoyote ya zamani, washa database pekee, kisha pakia dump:

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 ya search_path siyo ya lazima kwenye VectorChord database — ukiacha, kurejesha kutakatika katikati. Stack inapojitokeza ikiwa na originals zako, fungua web UI: ikiwa picha na albamu zako zipo, backup yako inafanya kazi. Kama hujawahi kufanya hivi, huna backup — una matumaini tu.

Njia za kushindwa, pamoja na maandishi utakayoyaona

Container ya ML imeuawa na OOM-killer. sudo docker compose logs immich-machine-learning inaisha ghafla, docker compose ps inaonyesha Restarting, na kodi ya kutoka ni 137. sudo dmesg | grep -i oom inathibitisha: Out of memory: Killed process ... (python3). Kazi za kutafuta na kutambua sura zitasimama. Sababu ni RAM ndogo mno kwa mifano (models). Suluhisho, kwa mpangilio: ongeza swap (Hatua ya 1); ongeza RAM kwenye VPS; au, ikiwa huwezi kabisa, zima ML kwenye Administration → Settings → Machine Learning Settings kwa kuzima Smart Search na Facial Recognition — utabaki na nakala (backups) na albamu, lakini utapoteza utafutaji kwa maudhui. Kuondoa huduma ya immich-machine-learning kwenye compose file kuna matokeo sawa.

Postgres inakataa kuanza baada ya kuhitimu (upgrade). Logi ya seva inarudia mstari kama 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. — au, kwenye mifumo ya zamani, The pgvecto.rs extension is not available in this Postgres instance.. Sababu ni picha ya database ambayo toleo la extension ni la zamani kuliko data iliyohitimu, mara nyingi kutokana na kuhariri image tag kwa mkono au kurejesha dump mpya kwenye picha ya zamani. Suluhisho ni kutumia picha ya Postgres inayolingana — chukua compose file kutoka kwenye toleo linalolingana na database yako, usirudishe nyuma (downgrade), na urejeshe kwenye picha inayokubalika tu.

App ya simu imeshindwa kuifikia seva. Skrini ya kuingia inaonyesha kosa la muunganisho / Server is not reachable baada ya kuingiza URL. Sababu tatu: umeandika http:// wakati proxy inahudumia https:// pekee; umeunganisha moja kwa moja kwenye backend lakini umeacha port, hivyo inajaribu example.com (port 443) badala ya example.com:2283; au reverse proxy haipitishi /api. Suluhisho ni kuingiza URL kamili ya https://photos.example.com na kuhakikisha inafunguka kwenye kivinjari cha simu kwanza. Ikiwa kivinjari kinafanya kazi lakini app haifanyi kazi, proxy inaondoa njia (path) au cheti ni cha kujisaini (self-signed) — app hukataa vyeti visivyoaminika.

Disk imejaa katikati ya uingizaji (import). Upakiaji unaanza kushindwa, picha ndogo (thumbnails) zinakuwa tupu, na logi zinaonyesha ENOSPC: no space left on device au, kutoka Postgres, could not extend file ... No space left on device. df -h inaonyesha volume ya UPLOAD_LOCATION ikiwa 100%. Hii ndiyo sababu unapaswa kupanga ukubwa wa disk kabla ya kuingiza maktaba kubwa. Rudisha hali ya kawaida kwa kuunganisha volume kubwa zaidi, kusimamisha stack, kuhamisha UPLOAD_LOCATION kwenda humo, kusasisha .env, na kuanza tena — au panua disk iliyopo ikiwa mtoa huduma wako unaruhusu. Postgres inaweza kukwama ikiwa imejaa, hivyo futa nafasi na uwashe tena container ya database kabla ya kudhani kuna uharibifu wa data.

FAQ

Immich inahitaji RAM na disk kiasi gani?

Mahitaji rasmi ya Immich ni RAM ya chini kabisa ya 6 GB na 8 GB inayopendekezwa — 4 GB pamoja na swap ndiyo kiwango cha chini kwa maktaba ndogo, na sanidi swap wakati wowote kwa sababu container ya machine-learning hutumia nguvu kubwa. Kwa disk, panga ukubwa wa maktaba yako nzima pamoja na takriban 10–20% kwa ajili ya thumbnails na previews zilizozalishwa, kwenye storage ya ndani — usiweke kamwe directory ya data ya Postgres kwenye network share. Ikiwa bado unaamua nini kingine cha kuendesha, mwongozo wa kile cha self-host katika 2026 unaonyesha matumizi ya Immich kulinganisha na huduma nyingine.

Je, ninaweza kuendesha Immich bila GPU?

Ndiyo. Container ya machine-learning inaweza kufanya kazi kwenye CPU — GPU huongeza kasi ya indexing ya smart-search na, kwa toleo sahihi la image, transcoding ya video. Kwenye CPU, indexing ya kwanza ya maktaba kubwa inaweza kuchukua saa kadhaa kwa nyuma, lakini haizuia backups au browsing. Ikiwa mashine yako haina nguvu ya kutosha kwa ML, unaweza kuzima Smart Search na Facial Recognition kwenye mipangilio ya admin na kuacha kila kitu kingine.

Je, ninawezaje kuongeza toleo la Immich kwa usalama?

Panga IMMICH_VERSION kwenye tag mahususi kama v3.0.2, soma maelezo ya toleo (release notes) kabla ya kila upgrade, na fanya backup ya database kwanza. Kwa sababu image ya Postgres imepangwa ndani ya docker-compose.yml badala ya IMMICH_VERSION, pakua tena compose file na example.env kutoka kwenye toleo unalolenga na uweke tena thamani zako, kisha run docker compose pull && docker compose up -d. Usiache toleo liwe bila kudhibitiwa — Immich inaweza kuwa na mabadiliko yanayovunja mifumo na haikubali kurudisha toleo la zamani (downgrades).

Je, ninapaswa ku-backup nini hasa?

Vitu viwili, pamoja: pg_dump ya immich database na directory nzima ya UPLOAD_LOCATION originals. Database inahifadhi albums, nyuso, na ramani ya asset-to-file; directory inahifadhi picha halisi, na urejeshaji (restore) unahitaji vyote viwili pamoja na image ya database yenye vector extension inayolingana. Fanya database dump kwanza na nakala ya faili pili, na jaribu urejeshaji kwenye mashine ya majaribio angalau mara moja — backup ambayo haijajaribiwa si backup.

Je, ninawezaje kuingiza (import) folder yangu ya picha iliyopo?

Mount folder hiyo kama read-only ndani ya container ya immich-server kama volume ya ziada (kwa mfano - /srv/photos:/mnt/media/photos:ro), tengeneza upya container, kisha kwenye Administration → External Libraries tengeneza maktaba na uongeze njia ya container /mnt/media/photos. Immich huindex faili mahali zilipo na haibadilishi au kufuta faili hizo. Kosa la kawaida ni kuingiza njia ya host badala ya njia ya container, jambo linalofanya scanning isipate kitu.