Immich Kiosk

Immich Kiosk is a purpose‑built, lightweight slideshow engine that consumes media from an Immich server. Built in Go and served as a single‑binary, the application abstracts the complexity of retrieving, caching, and rendering high‑resolution photos and videos in a kiosk‑friendly format. From a developer’s perspective, the project is designed to be dropped into any environment that can run a Go binary—be it a Raspberry Pi, a Docker host, or an Unraid VM—without the need for additional runtime dependencies.

Technical Stack

• Language & Runtime: Go 1.22+, leveraging the net/http standard library for HTTP communication and html/template for templating. The binary is statically linked, simplifying distribution.
• Data Layer: Immich’s REST API serves as the sole data source; Kiosk does not maintain its own database. It uses OAuth‑style API keys (KIOSK_IMMICH_API_KEY) and base URL (KIOSC_IMMICH_URL) for authentication.
• Containerization: Official Docker images are provided, built on scratch or minimal Alpine layers. The CI pipeline automatically publishes to Docker Hub and GitHub Container Registry, ensuring reproducible builds.
• Cross‑Platform: The binary is compiled for Linux/arm64, amd64, and Windows, enabling deployment on ARM‑based kiosks or conventional desktops.

Core Capabilities

• Dynamic Slideshow: Supports auto‑play, manual navigation, and configurable transition effects. The UI is responsive and works in full‑screen mode on touch devices.
• Media Caching: Implements a simple LRU cache to reduce API calls and bandwidth usage. Cached thumbnails are stored in memory or on disk based on configuration.
• Extensible API Endpoints: Exposes a minimal HTTP API (/api/slides) that returns JSON metadata, allowing external services to trigger slide changes or fetch current state.
• Webhooks & Callbacks: Listens for Immich webhooks (e.g., new photo upload) to refresh the slideshow in real time. Developers can hook into these events for custom workflows.

Deployment & Infrastructure

• Self‑Hosting: Requires only a reachable Immich server and an API key. No database or message broker is needed, which keeps the deployment footprint small.
• Scalability: Stateless by design; multiple instances can run behind a load balancer to serve different kiosks or regions. The caching strategy keeps memory usage predictable even under high load.
• Infrastructure as Code: Sample Unraid templates and Docker Compose files are provided, making it trivial to spin up a new kiosk instance via YAML or Docker CLI.

Integration & Extensibility

• Plugin System: While the core is minimal, developers can extend functionality by wrapping Kiosk in a reverse proxy that injects custom headers or modifies responses. The API surface is intentionally simple to encourage lightweight wrappers.
• Custom Themes: The UI uses CSS variables and a themeable layout. Custom stylesheets can be injected through environment variables or mounted volumes.
• SDK‑Like Interface: The Go client library (immichkiosk/client) exposes typed functions for fetching albums, photos, and videos, enabling developers to build companion apps or dashboards.

Developer Experience

• Configuration: All settings are exposed as environment variables, making CI/CD integration straightforward. The README provides a clear table mapping YAML keys to ENV vars.
• Documentation: Dedicated docs at docs.immichkiosk.app cover API usage, configuration, and troubleshooting. The project’s issue tracker is active, with quick response times from the maintainer.
• Community & Support: The project is integrated into the Immich Discord ecosystem, offering real‑time help. Community contributions are welcomed via GitHub PRs.

Use Cases

• Public Exhibits: Museums or galleries can run a Kiosk instance on a dedicated screen, pulling the latest media from an internal Immich server without exposing the full backend.
• Family Photo Booths: Home users can set up a Raspberry Pi to display recent family photos in a loop, automatically updating when new images are uploaded.
• Retail Displays: Stores can showcase product imagery or promotional videos by feeding the kiosk from an Immich instance that aggregates media from multiple suppliers.

Advantages

• Zero‑Configuration Backend: No database or message queue setup—developers can focus on the front‑end presentation.
• Performance: Static binary with minimal dependencies ensures fast startup and low memory overhead, ideal for resource‑constrained kiosks.
• Open Source & Licensing: Released under an MIT license, allowing unrestricted commercial use and modification.
• Integration Friendly: The simple REST interface and webhook support make it easy to embed within larger automation pipelines or micro‑service architectures.

Immich Kiosk delivers a production‑ready, developer‑friendly slideshow solution that bridges the gap between Immich’s powerful media server and the tactile demands of kiosk hardware. Its minimal footprint, clear API surface, and extensible design make it an attractive choice for anyone needing a reliable photo/video display in a self‑hosted environment.