Immich for Cloudron (Custom OAuth Fork)

A fork of the official Cloudron app package for Immich — a high-performance, self-hosted photo and video management solution. This fork adds custom OAuth provider support and unlocked admin dashboard settings.

Why This Fork?

The official Cloudron Immich package locks certain settings behind a config file and only supports Cloudron's built-in OIDC provider. This fork changes that:

• Unlocked Admin Dashboard — all settings are managed via the database instead of a config file, so you can change them directly from the Immich admin UI
• Custom OAuth Providers — connect any OAuth2/OIDC provider (e.g. authentik, Keycloak, Authelia) instead of being limited to Cloudron's built-in OIDC
• Smart OIDC Handling — if you configure a custom OAuth provider, Cloudron's OIDC settings are automatically skipped on restart so your config is preserved

What is Immich?

Immich is a self-hosted photo and video backup solution with a mobile-first experience, designed as a private alternative to Google Photos.

Key Features

• Auto Backup — automatic photo and video backup from mobile apps
• Multi-User Support — separate libraries and sharing between users
• Machine Learning — facial recognition, smart search, and object detection
• RAW Support — HEIC, HEIF, DNG, Apple ProRAW
• Search — by metadata, objects, faces, and image tags
• Albums & Sharing — create, organize, and share albums
• Map View — browse photos by location with reverse geocoding
• Video Support — full video playback and transcoding via FFmpeg

Mobile Apps

Platform	Link
Android	Google Play
iOS	App Store

Cloudron Integration

This package runs Immich on Cloudron with:

• Automatic TLS — Cloudron handles HTTPS termination
• Automatic backups — persistent data at /app/data/ is backed up by Cloudron
• PostgreSQL addon — managed database provided by Cloudron
• Redis addon — managed Redis for caching and job queues
• Email addon — outbound email via Cloudron's mail system (optional)
• OIDC addon — Cloudron SSO with automatic fallback for custom OAuth providers
• Database-driven config — admin dashboard settings are fully editable

Addons Used

Addon	Purpose
localstorage	Persistent storage for uploads, thumbnails, and encoded videos
postgresql	Database for users, assets, albums, metadata, and system config
redis	Caching, job queues, and pub/sub
sendmail	Outbound email for notifications and sharing (optional)
oidc	Single sign-on via Cloudron or custom OAuth provider

Exposed Ports

Port	Protocol	Purpose
2283	HTTP	Web UI and API (proxied by Cloudron)

Installation

Prerequisites

• A running Cloudron instance
• Cloudron CLI installed (npm install -g cloudron)
• Docker Desktop running and logged in
• A Docker Hub account

Quick Start

1. Clone this repository:

   git clone https://github.com/stalecontext/immich-cloudron-custom-oauth.git
   cd immich-cloudron-custom-oauth
   

2. Login to Cloudron:

   cloudron login
   

3. Run the install script:

   ./install.bat
   

   Follow the prompts to choose your subdomain (e.g. photos.example.com).

4. Create your admin account:

   • Visit https://your-subdomain/ and create your first admin user.

Updating

When you want to update to a newer version of Immich:

1. Bump the versions:

   • CloudronManifest.json → version and upstreamVersion
   • Dockerfile → ARG IMMICH_VERSION=

2. Build and push:

   ./deploy.bat
   

3. Update the running app:

   ./update-cloudron.bat
   

Custom OAuth Setup

To use a custom OAuth provider instead of Cloudron's built-in OIDC:

1. Install the app and let it start with Cloudron's default OIDC
2. Open the Immich admin dashboard → Settings → OAuth Authentication
3. Replace the issuer URL, client ID, and client secret with your custom provider's values
4. Save — on the next container restart, the startup script detects a non-Cloudron issuer and preserves your custom config

Project Structure

immich-cloudron-custom-oauth/
├── CloudronManifest.json         # Cloudron app manifest
├── Dockerfile                    # Multi-stage build (Cloudron base + Immich from source)
├── start.sh                      # Container startup script (config → database)
├── env.sh                        # Environment variable mapping (Cloudron → Immich)
├── immich-admin.sh               # Wrapper for immich-admin CLI commands
├── supervisor/
│   ├── server.conf               # supervisord: Immich server (Node.js)
│   └── machine-learning.conf     # supervisord: Machine learning (Python)
├── DESCRIPTION.md                # App description for Cloudron dashboard
├── POSTINSTALL.md                # Post-install message shown in Cloudron
├── CHANGELOG.md                  # Version history
├── deploy.bat                    # Build & push Docker image to Docker Hub
├── update-cloudron.bat           # Update running Cloudron app
├── install.bat                   # First-time install to Cloudron
├── configure-cloudron.bat        # One-time Docker Hub setup
├── cloudron-wrapper.bat          # Windows env wrapper for Cloudron CLI
├── renovate.json5                # Renovate config for automated version updates
└── logo.png                      # App icon

How It Works

The Dockerfile builds Immich from source in multiple stages:

1. Base — Installs system dependencies (FFmpeg, libvips, libheif, Node.js, Python) on cloudron/base:5.0.0, downloads geodata, and builds the machine learning environment
2. Server — Compiles the Immich server (TypeScript → JavaScript)
3. Web — Builds the Immich web frontend (SvelteKit)
4. Plugins — Builds core plugins using mise
5. Final — Assembles everything into the runtime image with startup scripts

The start.sh script runs on every container start:

• Creates required directories and sets permissions
• Maps Cloudron environment variables to Immich config via env.sh
• Prepares PostgreSQL extensions (pgvecto.rs / VectorChord)
• Starts both server and machine-learning processes via supervisord
• Waits for the server to be healthy
• Reads current config from the database, applies Cloudron overlay settings (external domain, OIDC, SMTP), and upserts the merged config back — preserving any custom OAuth provider config

Architecture

Immich runs two processes managed by supervisord:

• Server — Node.js application serving the web UI, API, and background job processing
• Machine Learning — Python service for facial recognition, smart search, CLIP embeddings, and object detection

Both use PostgreSQL for the database and Redis for caching, job queues, and pub/sub messaging.

Configuration

Immich is configured through its admin interface at Administration → Settings. Key areas:

• Storage Template — customize how uploaded files are organized on disk
• Machine Learning — facial recognition, smart search, and duplicate detection
• OAuth Authentication — configure any OIDC-compatible identity provider
• Job Concurrency — tune background processing performance
• Notifications — email settings for sharing and alerts
• Map & Reverse Geocoding — location-based features
• FFmpeg — video transcoding settings

All uploads and persistent data are stored in /app/data/ and survive container restarts and Cloudron backups.

Links

• Immich — immich.app
• Immich Source — github.com/immich-app/immich
• Immich Docs — immich.app/docs
• Cloudron Docs — docs.cloudron.io
• Cloudron Forum — forum.cloudron.io/category/151/immich
• Docker Hub — hub.docker.com/r/stalecontext/immich-custom-oauth-cloudron

License

This Cloudron packaging is provided as-is. Immich itself is licensed under GNU AGPL v3.