Deploying Immich Kiosk

Introduction

Immich Kiosk is a lightweight web application designed to transform any screen into a digital photo frame that displays images from your Immich photo library. Perfect for repurposing old tablets, smart displays, or any device with a web browser, Immich Kiosk provides a beautiful, automated slideshow of your memories.

Built as a companion to Immich (the self-hosted Google Photos alternative), Immich Kiosk connects to your Immich server’s API and displays photos based on your preferences - whether that’s specific albums, random selections, favorites, or memories from this day in past years.

Key highlights of Immich Kiosk:

Immich Integration: Connects directly to your Immich server API
Multiple Display Modes: Show random photos, specific albums, or memories
Customizable Transitions: Various transition effects between photos
Configurable Timing: Set display duration for each photo
Ken Burns Effect: Subtle zoom and pan for dynamic displays
Time and Date Overlay: Optional clock display on screen
Weather Integration: Show current weather conditions
Favorites Support: Display only your starred photos
Album Selection: Choose specific albums to display
Memory Lane: Show photos from this day in history
Responsive Design: Adapts to any screen size
Low Resource Usage: Minimal requirements for embedded devices

This guide walks through deploying Immich Kiosk on Klutch.sh using Docker, creating a cloud-hosted photo frame display.

Why Deploy Immich Kiosk on Klutch.sh

Deploying Immich Kiosk on Klutch.sh provides several advantages for digital photo displays:

Centralized Access: Host your kiosk display centrally and access it from multiple devices simultaneously.

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Immich Kiosk without manual server configuration.

HTTPS by Default: Secure connections ensure your Immich API credentials are protected.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Always Available: Your photo display URL remains accessible from anywhere.

Custom Domains: Assign a memorable domain for easy device configuration.

Multiple Displays: Run multiple kiosk configurations for different rooms or purposes.

Prerequisites

Before deploying Immich Kiosk on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your Immich Kiosk configuration
A running Immich server with photos
An Immich API key (generated in Immich settings)
Basic familiarity with Docker and containerization concepts

Understanding Immich Kiosk Architecture

Immich Kiosk is designed for simplicity:

Web Application: A lightweight web server that generates the slideshow interface.

Immich API Client: Connects to your Immich server to fetch photos and metadata.

Client-Side Display: The actual slideshow runs in the viewer’s browser.

No Local Storage: Photos are streamed from Immich, no local caching required.

Preparing Your Repository

To deploy Immich Kiosk on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

immich-kiosk-deploy/
├── Dockerfile
├── config.yaml
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM damongolding/immich-kiosk:latest

# Set environment variables for Immich connection
ENV KIOSK_IMMICH_URL=${KIOSK_IMMICH_URL}
ENV KIOSK_IMMICH_API_KEY=${KIOSK_IMMICH_API_KEY}

# Display settings
ENV KIOSK_INTERVAL=${KIOSK_INTERVAL:-30}
ENV KIOSK_TRANSITION_DURATION=${KIOSK_TRANSITION_DURATION:-1}
ENV KIOSK_IMAGE_ZOOM=${KIOSK_IMAGE_ZOOM:-true}

# Content settings
ENV KIOSK_SHOW_FAVORITES=${KIOSK_SHOW_FAVORITES:-false}
ENV KIOSK_SHOW_MEMORIES=${KIOSK_SHOW_MEMORIES:-true}

# Timezone
ENV TZ=${TZ:-UTC}

# Expose port
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/ || exit 1

Configuration File (config.yaml)

For more advanced configuration, create a config.yaml:

# Immich server connection
immich:
  url: "${KIOSK_IMMICH_URL}"
  api_key: "${KIOSK_IMMICH_API_KEY}"

# Display settings
display:
  interval: 30  # Seconds between photos
  transition_duration: 1  # Transition animation duration
  image_zoom: true  # Ken Burns effect
  show_date: true  # Show photo date
  show_time: true  # Show current time
  clock_format: 12  # 12 or 24 hour format

# Content settings
content:
  show_favorites: false
  show_memories: true
  albums: []  # Specific album IDs to display

# Weather (optional)
weather:
  enabled: false
  api_key: ""
  location: ""

# Localization
locale:
  language: "en"
  timezone: "UTC"

Environment Variables Reference

Variable	Required	Default	Description
`KIOSK_IMMICH_URL`	Yes	-	URL of your Immich server
`KIOSK_IMMICH_API_KEY`	Yes	-	Immich API key for authentication
`KIOSK_INTERVAL`	No	30	Seconds between photo transitions
`KIOSK_TRANSITION_DURATION`	No	1	Transition animation duration in seconds
`KIOSK_IMAGE_ZOOM`	No	true	Enable Ken Burns zoom effect
`KIOSK_SHOW_FAVORITES`	No	false	Only show favorited photos
`KIOSK_SHOW_MEMORIES`	No	true	Show “on this day” memories
`KIOSK_ALBUMS`	No	-	Comma-separated album IDs
`TZ`	No	UTC	Timezone for clock display
`LANG`	No	en	Interface language

Deploying Immich Kiosk on Klutch.sh

Once your repository is prepared, follow these steps to deploy Immich Kiosk:

Get Your Immich API Key

Generate an API key in Immich:

Log into your Immich web interface
Go to Account Settings > API Keys
Click “New API Key”
Give it a name like “Kiosk”
Copy the generated key

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile config.yaml .dockerignore
git commit -m "Initial Immich Kiosk deployment configuration"
git remote add origin https://github.com/yourusername/immich-kiosk-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “photo-frame” or “immich-kiosk”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Immich Kiosk Dockerfile.

Configure HTTP Traffic

Immich Kiosk serves its web interface over HTTP. In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 3000

Set Environment Variables

In the environment variables section, add:

Variable	Value
`KIOSK_IMMICH_URL`	`https://your-immich-server.com`
`KIOSK_IMMICH_API_KEY`	Your Immich API key
`KIOSK_INTERVAL`	`30` (or your preferred duration)
`KIOSK_SHOW_MEMORIES`	`true`
`TZ`	Your timezone (e.g., `America/New_York`)

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

Detect your Dockerfile automatically
Build the container image
Start the Immich Kiosk container
Provision an HTTPS certificate

Access Your Kiosk

Once deployment completes, access your Immich Kiosk at https://your-app-name.klutch.sh. Open this URL on any device you want to use as a photo frame.

Configuring Display Modes

Random Photos

Display random photos from your entire library:

KIOSK_SHOW_FAVORITES=false
KIOSK_ALBUMS=

Favorites Only

Show only photos you’ve starred in Immich:

KIOSK_SHOW_FAVORITES=true

Specific Albums

Display photos from specific albums:

Get album IDs from Immich (from the URL when viewing an album)
Configure with comma-separated IDs:

KIOSK_ALBUMS=album-id-1,album-id-2

Memories (On This Day)

Show photos from this day in previous years:

KIOSK_SHOW_MEMORIES=true

Setting Up Display Devices

Raspberry Pi

Install Raspberry Pi OS Lite
Install a minimal browser (Chromium)
Configure auto-start with kiosk URL
Disable screen blanking

Old Tablet

Install a kiosk browser app
Configure with your Kiosk URL
Enable “Stay Awake” in developer options
Mount in a frame or stand

Smart Display

Many smart displays support web apps:

Add as a custom web shortcut
Open in full-screen mode
Some support auto-refresh

Browser on PC

Simply open the URL in any modern browser:

Press F11 for full-screen mode
Disable notifications
Consider using a dedicated user profile

Customization Options

Clock and Date

Show or hide time overlays:

display:
  show_date: true
  show_time: true
  clock_format: 12  # or 24

Transition Effects

Customize how photos change:

display:
  transition_duration: 1.5  # Longer fade
  image_zoom: true  # Ken Burns effect

Multiple Kiosks

Deploy multiple instances with different configurations:

Living room: Family albums
Kitchen: Recipe photos
Office: Travel memories

Troubleshooting Common Issues

Photos Not Loading

Symptoms: Blank screen or loading spinner.

Solutions:

Verify Immich URL is accessible from Klutch.sh
Check API key is correct and not expired
Ensure Immich server allows external API access
Review browser console for errors

Wrong Photos Showing

Symptoms: Unexpected photos appear.

Solutions:

Check album ID configuration
Verify favorites filter setting
Ensure Immich has photos matching your criteria

Slow Transitions

Symptoms: Photos take too long to load.

Solutions:

Check network connection to Immich server
Reduce photo quality if bandwidth limited
Ensure adequate resources for Immich server

Clock Shows Wrong Time

Symptoms: Time display is incorrect.

Solutions:

Set correct timezone in environment variables
Verify TZ variable uses valid timezone identifier

Additional Resources

Conclusion

Deploying Immich Kiosk on Klutch.sh gives you a centralized digital photo frame service that can display your Immich photos on any device with a web browser. The combination of Immich’s powerful photo management and Kiosk’s elegant display creates a seamless way to enjoy your memories throughout your home or office.

Whether you’re repurposing old tablets, setting up a dedicated photo frame, or just want a beautiful screensaver, Immich Kiosk on Klutch.sh provides an always-available, easily-configurable photo display solution.