Skip to content
Immich Kiosk

Installation

There are two main ways to install Kiosk: Docker or Binary.

Section titled “Docker (recommended)”

Option 1: Add Kiosk to your exsiting Immich compose stack.

Section titled “Option 1: Add Kiosk to your exsiting Immich compose stack.”

  1. Add the kiosk service to your Immich docker-compose.yaml file.

  2. Follow from step 3 in option 2 to create the config.yaml file.

Option 2: Create a separate compose file for Kiosk.

Section titled “Option 2: Create a separate compose file for Kiosk.”

  1. Create a directory of your choice (e.g. ./immich-kiosk) to hold the docker-compose.yaml and config file.

    Terminal window
    mkdir ./immich-kiosk
    cd ./immich-kiosk

  2. Download docker-compose.yaml.

    Terminal window
    wget -O docker-compose.yaml https://raw.githubusercontent.com/damongolding/immich-kiosk/refs/heads/main/docker-compose.yaml

    Set Lang to a language code from this list) Set TZ to a TZ identifier from this list

  3. Create the config.yaml file.

    You may use environment variables if preferred.

    Create config dir and download config.yaml file.

    Terminal window
    mkdir ./config
    wget -O ./config/config.yaml https://raw.githubusercontent.com/damongolding/immich-kiosk/refs/heads/main/config.example.yaml

  4. Modify config.yaml file.

    Only the immich_url and immich_api_key are required fields.

  5. Start the container

    Terminal window
     docker compose up -d

Binary

Section titled “Binary”

  1. Download the binary file Vist the latest release and scroll to the assets at the bottom of the release notes. Download the archive file that matches your machines architecture and unarchive.

  2. Create config dir and download config.yaml file.

    Terminal window
    mkdir ./config
    wget -O ./config/config.yaml https://raw.githubusercontent.com/damongolding/immich-kiosk/refs/heads/main/config.example.yaml

  3. Modify config.yaml file.

    Only the immich_url and immich_api_key are required fields.

  4. Start Kiosk

    Terminal window
    ./kiosk

Docker Compose

Section titled “Docker Compose”

When using a config.yaml config file

Section titled “When using a config.yaml config file”
docker-compose.yaml
services:
  immich-kiosk:
    image: ghcr.io/damongolding/immich-kiosk:latest
    container_name: immich-kiosk
    tty: true
    environment:
      LANG: "en_GB"
      TZ: "Europe/London"
    ports:
      - 3000:3000
    volumes:
      - ./config:/config
      # - ./custom.css:/custom.css
      # - ./offline-assets:/offline-assets
    restart: always

When using environment variables

Section titled “When using environment variables”
docker-compose.yaml
services:
  immich-kiosk:
    image: ghcr.io/damongolding/immich-kiosk:latest
    container_name: immich-kiosk
    environment:
      LANG: "en_GB"
      TZ: "Europe/London"
      # Required settings
      KIOSK_IMMICH_API_KEY: "****"
      KIOSK_IMMICH_URL: "****"
      # External url for image links/QR codes
      KIOSK_IMMICH_EXTERNAL_URL: ""
      # Clock
      KIOSK_SHOW_TIME: false
      KIOSK_TIME_FORMAT: 24
      KIOSK_SHOW_DATE: false
      KIOSK_DATE_FORMAT: YYYY/MM/DD
      KIOSK_CLOCK_SOURCE: client
      # Kiosk behaviour
      KIOSK_REFRESH: 60
      KIOSK_DISABLE_SCREENSAVER: false
      KIOSK_OPTIMIZE_IMAGES: false
      KIOSK_USE_GPU: true
      # Asset sources
      KIOSK_SHOW_ARCHIVED: false
      KIOSK_ALBUM: "ALBUM_ID,ALBUM_ID,ALBUM_ID"
      KIOSK_ALBUM_ORDER: random
      KIOSK_EXCLUDED_ALBUMS: "ALBUM_ID,ALBUM_ID,ALBUM_ID"
      KIOSK_EXPERIMENTAL_ALBUM_VIDEO: false
      KIOSK_PERSON: "PERSON_ID,PERSON_ID,PERSON_ID"
      KIOSK_REQUIRE_ALL_PEOPLE: false
      KIOSK_EXCLUDED_PEOPLE: "PERSON_ID,PERSON_ID,PERSON_ID"
      KIOSK_DATE: "DATE_RANGE,DATE_RANGE,DATE_RANGE"
      KIOSK_TAG: "TAG_VALUE,TAG_VALUE,TAG_VALUE"
      KIOSK_MEMORIES: false
      KIOSK_BLACKLIST: "ASSET_ID,ASSET_ID,ASSET_ID"
      # FILTER
      KIOSK_DATE_FILTER: ""
      # UI
      KIOSK_DISABLE_NAVIGATION: false
      KIOSK_DISABLE_UI: false
      KIOSK_FRAMELESS: false
      KIOSK_HIDE_CURSOR: false
      KIOSK_FONT_SIZE: 100
      KIOSK_BACKGROUND_BLUR: true
      KIOSK_BACKGROUND_BLUR_AMOUNT: 10
      KIOSK_THEME: fade
      KIOSK_LAYOUT: single
      KIOSK_SHOW_USER: false
      # Sleep mode
      # KIOSK_SLEEP_START: 22
      # KIOSK_SLEEP_END: 7
      # KIOSK_SLEEP_DIM_SCREEN: false
      # Transistion options
      KIOSK_TRANSITION: none
      KIOSK_FADE_TRANSITION_DURATION: 1
      KIOSK_CROSS_FADE_TRANSITION_DURATION: 1
      # Image display settings
      KIOSK_SHOW_PROGRESS: false
      KIOSK_IMAGE_FIT: contain
      KIOSK_IMAGE_EFFECT: smart-zoom
      KIOSK_IMAGE_EFFECT_AMOUNT: 120
      KIOSK_USE_ORIGINAL_IMAGE: false
      # Image metadata
      KIOSK_SHOW_OWNER: false
      KIOSK_SHOW_ALBUM_NAME: false
      KIOSK_SHOW_PERSON_NAME: false
      KIOSK_SHOW_PERSON_AGE: false
      KIOSK_SHOW_IMAGE_TIME: false
      KIOSK_IMAGE_TIME_FORMAT: 24
      KIOSK_SHOW_IMAGE_DATE: false
      KIOSK_IMAGE_DATE_FORMAT: YYYY-MM-DD
      KIOSK_SHOW_IMAGE_DESCRIPTION: false
      KIOSK_SHOW_IMAGE_EXIF: false
      KIOSK_SHOW_IMAGE_LOCATION: false
      KIOSK_HIDE_COUNTRIES: "HIDDEN_COUNTRY,HIDDEN_COUNTRY"
      KIOSK_SHOW_IMAGE_ID: false
      KIOSK_SHOW_IMAGE_QR: false
      KIOSK_SHOW_MORE_INFO: true
      KIOSK_SHOW_MORE_INFO_IMAGE_LINK: true
      KIOSK_SHOW_MORE_INFO_QR_CODE: true
      # More info actions
      KIOSK_LIKE_BUTTON_ACTION: favorite
      KIOSK_HIDE_BUTTON_ACTION: tag
      # Kiosk settings
      KIOSK_PORT: 3000
      KIOSK_BEHIND_PROXY: false
      KIOSK_WATCH_CONFIG: false
      KIOSK_FETCHED_ASSETS_SIZE: 1000
      KIOSK_HTTP_TIMEOUT: 20
      KIOSK_PASSWORD: ""
      KIOSK_CACHE: true
      KIOSK_PREFETCH: true
      KIOSK_ASSET_WEIGHTING: true
    ports:
      - 3000:3000
    restart: always

When checking config.yaml into a repository

Section titled “When checking config.yaml into a repository”

It is recommended to avoid checking-in any secrets.

  1. Create a docker-compose.env file.

    Terminal window
    touch docker-compose.env

  2. Remove secrets from config.yaml (and docker-compose.yaml) - generally immich_url and immich_api_key.

  3. Include your secrets in docker-compose.env.

    Terminal window
    KIOSK_IMMICH_API_KEY=SECRET_KEY
    KIOSK_IMMICH_URL=SECRET_URL

  4. Update docker-compose.yaml to include env_file:.

    services:
      immich-kiosk:
        env_file:
          - docker-compose.env

  5. Add docker-compose.env to .gitignore.