Skip to content

Immich - Photo Management

Immich is a self-hosted photo and video backup solution with mobile apps.

Quick Reference

Property Value
URL (External) https://photos.bogocat.com
URL (Internal) http://photos.bogocat.com (via ingress)
Namespace immich
Auth Authentik OIDC (native)
Storage NFS mount for photos

Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Immich                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │   Server    │  │  Microsvcs  │  │   Machine Learning  │ │
│  │  (API/Web)  │  │ (thumbnails)│  │   (face detection)  │ │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘ │
│         │                │                     │            │
│         └────────────────┼─────────────────────┘            │
│                          │                                  │
│                   ┌──────▼──────┐                           │
│                   │  PostgreSQL │                           │
│                   │  (metadata) │                           │
│                   └─────────────┘                           │
│                                                             │
│  Storage: /photos (NFS mount)                               │
└─────────────────────────────────────────────────────────────┘

Authentication

OAuth/OIDC Configuration (Authentik)

Immich uses native OIDC integration with Authentik, providing: - MFA enforcement through Authentik - Mobile app support via custom redirect URI - Automatic user provisioning

Authentik Setup:

Setting Value
Provider Name immich-oauth
Application Slug immich
Client Type Confidential
Redirect URIs app.immich:///oauth-callback, https://photos.bogocat.com/auth/login, https://photos.bogocat.com/user-settings

Immich Admin Settings (Administration > OAuth):

Setting Value
Issuer URL https://auth.bogocat.com/application/o/immich/.well-known/openid-configuration
Client ID uffM5FYjeqF5w5onXtnrhmn0WOCqnQ15k4ggPw8D
Client Secret (stored in Authentik)
Scope openid email profile
Auto Register Enabled
Auto Launch Enabled
Mobile Redirect Override Enabled

Permission Mapping

┌─────────────────────────────────────────────────────────────┐
│              OAuth Login Permission Flow                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  User logs in via Authentik                                 │
│           │                                                 │
│           ▼                                                 │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Email Match Check                                    │   │
│  │   Authentik email ←→ Existing Immich user email     │   │
│  └───────────────────────┬─────────────────────────────┘   │
│                          │                                  │
│         ┌────────────────┴────────────────┐                │
│         │                                 │                │
│         ▼                                 ▼                │
│   ┌───────────┐                    ┌───────────┐          │
│   │  MATCHED  │                    │ NO MATCH  │          │
│   │           │                    │           │          │
│   │ Login to  │                    │ Create    │          │
│   │ existing  │                    │ new user  │          │
│   │ account   │                    │ (standard)│          │
│   └───────────┘                    └───────────┘          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Role Claims (Optional):

Authentik can pass claims to control Immich permissions:

Claim Purpose Values
immich_role Admin status admin or user
immich_quota Storage quota (GiB) Number
preferred_username Storage label Username string

To use role claims, configure them in the Authentik provider's scope mapping.

User Types

User Type How Created Permissions
Admin (you) Pre-existing + email match Full admin
Standard User Auto-registered via OAuth Own library only
Shared User Admin creates manually Access to shared albums

Mobile App Setup

  1. Install Immich app (iOS/Android)
  2. Server URL: https://photos.bogocat.com
  3. Tap "Login with OAuth"
  4. Authenticates via Authentik in browser
  5. Redirects back to app (via app.immich:///oauth-callback)

Kubernetes Resources

# Check pods
kubectl get pods -n immich

# Check logs
kubectl logs -n immich -l app.kubernetes.io/name=immich-server

# Check storage
kubectl get pvc -n immich

Backup

Photos stored on NFS are backed up via ZFS snapshots on the NAS.

Database backup: 

kubectl exec -n immich deploy/immich-server -- \
  pg_dump -U immich immich > immich-backup.sql

Troubleshooting

OAuth Login Fails

  1. Check Authentik provider redirect URIs include all three URLs
  2. Verify issuer URL is accessible: curl https://auth.bogocat.com/application/o/immich/.well-known/openid-configuration
  3. Check Immich logs: kubectl logs -n immich -l app.kubernetes.io/name=immich-server

Mobile App Can't Login

  1. Ensure "Mobile redirect URI override" is enabled in Immich
  2. Verify app.immich:///oauth-callback is in Authentik redirect URIs
  3. Try clearing app data and re-authenticating

User Not Admin After OAuth Login

  1. User was auto-created before admin account existed
  2. Fix: Admin manually promotes user in Immich admin panel