Skip to content

Immich -- Runbook

Quick Reference

Item Value
LXC 127 @ 192.168.1.127
URL https://photos.eva-00.network
Health curl http://192.168.1.127:2283/api/server/ping
Vault secret/data/immich
Deploy Forgejo Actions > Deploy Immich

Check Service Status

ssh [email protected] docker compose -f /opt/immich/docker-compose.yml ps

Restart Services

ssh [email protected] docker compose -f /opt/immich/docker-compose.yml restart

View Logs

Via Loki (preferred)

{container_name="immich_server"}
{container_name=~"immich.*"} |= "error"

Via SSH (fallback)

ssh [email protected] docker compose -f /opt/immich/docker-compose.yml logs -f --tail 100

Fresh Redeploy

Trigger via Forgejo Actions with force_clean=true, or manually:

ssh [email protected]
cd /opt/immich
docker compose down
rm -rf /opt/immich/database /opt/immich/model-cache

Then re-run the workflow. It will re-create the admin user and configure OIDC.

Warning: This does NOT delete photos on urahara. To fully reset, also clear /mnt/pve/urahara/immich/ on the Proxmox host.

Memory / Performance

LXC resource allocation

Resource Value Notes
RAM 8192 MB ML inference needs 4-6 GB during initial processing
Swap 1024 MB Safety net for ML processing peaks
Cores 4 ML benefits from more cores

ML processing

Initial import of a large photo library will be slow (CPU-only ML). Expect:

  • Face detection: ~1-3 seconds per photo
  • CLIP embedding: ~1-2 seconds per photo
  • A 10,000 photo library: ~6-12 hours for full ML processing

Processing happens in the background and doesn't block photo browsing.

Logs

Log Contents Location Query Format
Server API requests, job processing Docker stdout {container_name="immich_server"} JSON
ML Model loading, inference Docker stdout {container_name="immich_machine_learning"} text
PostgreSQL DB queries, errors Docker stdout {container_name="immich_postgres"} text

Access: Grafana > Explore > Loki > Enter query

Common Tasks

Force re-run ML jobs

In the Immich web UI: Administration > Jobs > Queue all for each job type (Smart Search, Face Detection, etc.)

Check storage usage

ssh [email protected] du -sh /mnt/immich/upload/
ssh [email protected] du -sh /opt/immich/database/
ssh [email protected] du -sh /opt/immich/model-cache/

Database maintenance

ssh [email protected] docker exec immich_postgres vacuumdb --all --analyze -U postgres

Update Immich version

Change IMMICH_VERSION in the .env file (or leave as release for latest), then:

ssh [email protected]
cd /opt/immich
docker compose pull
docker compose up -d

Or re-run the Forgejo Actions workflow.

Troubleshooting

OIDC login not working

  1. Check PocketID client exists and callback URLs include both https://photos.eva-00.network/auth/login and app.immich:///oauth-callback
  2. Verify mobile redirect URI is app.immich:///oauth-callback (NOT https://immich.app/oauth-callback — the Universal Link does not work on iOS, the browser opens immich.app website instead of returning to the app)
  3. Verify OIDC config: curl -H "x-api-key: <API_KEY>" http://192.168.1.127:2283/api/system-config | jq .oauth
  4. Check server logs: {container_name="immich_server"} |= "oauth"

ML models not loading

Check if model cache has data:

ssh [email protected] ls -la /opt/immich/model-cache/

If empty, restart the ML container to trigger re-download:

ssh [email protected] docker restart immich_machine_learning

Photos not appearing after upload

  1. Check job queue in web UI: Administration > Jobs
  2. Check server logs for processing errors
  3. Verify upload directory is accessible: ls /mnt/immich/upload/

Out of memory during ML processing

If ML processing causes OOM, check host kernel:

ssh [email protected] "dmesg | tail -50 | grep -i oom"

Fix: increase LXC RAM via pct set 127 --memory 12288

iOS app can't connect

  1. Verify the server URL in the app: https://photos.eva-00.network
  2. For OIDC login, ensure the app shows the "Login with Pocket-ID" button
  3. Check that mobileRedirectUri is app.immich:///oauth-callback (not https://immich.app/oauth-callback)
  4. Ensure PocketID client callback URLs include app.immich:///oauth-callback

Custom theme not visible

  1. Custom CSS is served at /custom.css — verify with curl http://192.168.1.127:2283/custom.css
  2. No server restart needed — changes apply immediately
  3. Hard refresh the browser (Cmd+Shift+R) to bypass cache
  4. Theme CSS lives in services/immich/apple-theme.css and is applied via the playbook's system-config API PUT
  5. Override --immich-ui-* variables (hex format). No !important needed — /custom.css loads after bundled styles so cascade order handles priority
  6. Scope light mode to :root:not(.dark), .light and dark mode to .dark