Raspberry Pi 5 Photo Frame: ImmichFrame Kiosk Mode Setup Guide (Chromium + Docker + Autostart)

Last updated on 25 Sep 2025 📧 Subscribe
Contents hide
1 ✅ Prerequisites
2 🧰 Step 1: Install Required Packages for Chromium Kiosk Mode
3 🔁 Step 2: Enable Autologin
4 📜 Step 3: Create the Kiosk Script
5 🔓 Step 4: Make the Script Executable
6 🚀 Step 5: Auto-Launch Script at Boot
7 🧠 Step 6: Tell X11 to Run the Kiosk Script
8 🧱 Step 7: Configure Xorg Driver (Optional for HDMI framebuffer)
9 🖥️ Step 8: Set Display Resolution (Optional)
10 🔄 Step 9: Reboot and Test
11 ✅ PART 1 – Install Docker on Raspberry Pi 5
11.1 1. Switch to Root
11.2 2. Install Required Packages
11.3 3. Install Docker
11.4 4. Add Your User to Docker Group
12 ✅ PART 2 – Install Immich Server via Docker
12.1 1. Create the Immich Project Directory
12.2 2. Download the Docker Compose File and Environment Config
12.3 3. Edit the Environment File
12.4 4. Start Immich Server
12.5 5. Get Your Pi IP Address
13 ✅ PART 3 – Install ImmichFrame
13.1 1. Create Directory Structure
13.2 2. Create the docker-compose.yml file
13.3 3. Create and Edit Settings.yml
13.4 4. Start ImmichFrame
13.5 📝 Ending Paragraphs for the Article
13.6 🛒 Shopping List (with Affiliate Links)
13.7 Related
13.8 Discover more from NAS Compares

This guide turns your Raspberry Pi 5 into a dedicated photo frame powered by Immich, using Chromium in kiosk mode. It boots directly into full-screen ImmichFrame via Docker. Tested with Raspberry Pi OS 64-bit Lite.

✅ Prerequisites

  • Raspberry Pi 5 with Raspberry Pi OS Lite (64-bit)

  • SSH access (e.g., via ssh frame.local)

  • Internet connection

  • Docker & Docker Compose installed

  • Immich server already running (can be on same or different device)

🧰 Step 1: Install Required Packages for Chromium Kiosk Mode

SSH into the Pi and become root:

sudo -i

Update packages and install the minimum required X11 tools and Chromium:

apt update && apt full-upgrade -y
apt install --no-install-recommends xserver-xorg xinit chromium-browser unclutter -y

🔁 Step 2: Enable Autologin

Run the Raspberry Pi configuration tool:

sudo raspi-config

Navigate the following:

  1. System Options

  2. Boot / Auto Login

  3. Select: Console Autologin

Then exit and reboot (optional):

sudo reboot

📜 Step 3: Create the Kiosk Script

Create the script file:

nano /home/ed/kiosk.sh

Paste this content to launch Chromium in kiosk mode and restart if it crashes:

#!/bin/bash

# Prevent screen blanking and hide the cursor
xset -dpms
xset s off
xset s noblank
unclutter -idle 0.5 -root &

# Start the browser in kiosk mode with additional flags
/usr/bin/chromium-browser --noerrdialogs --incognito --kiosk --start-maximized --start-fullscreen http://192.168.1.40:8777

# Re-run this script if Chromium crashes
exec "$0"

Save and exit (Ctrl+X, then Y, then Enter).

🔓 Step 4: Make the Script Executable

chmod +x /home/ed/kiosk.sh

🚀 Step 5: Auto-Launch Script at Boot

Edit the .bash_profile of the autologin user:

nano /home/ed/.bash_profile

Add this to the bottom:

if [ -z "$DISPLAY" ] && [ "$(tty)" = "/dev/tty1" ]; then
startx
fi

🧠 Step 6: Tell X11 to Run the Kiosk Script

Create .xinitrc file:

nano /home/ed/.xinitrc

Add this single line:

/home/ed/kiosk.sh

🧱 Step 7: Configure Xorg Driver (Optional for HDMI framebuffer)

If display doesn’t show properly, do this:

cd /etc/X11
sudo nano xorg.conf

Add this content:

Section "Device"
Identifier "RaspberryPi-Driver"
Driver "fbdev"
EndSection

🖥️ Step 8: Set Display Resolution (Optional)

If display is not fullscreen:

Check supported resolutions:

xrandr

Then:

sudo nano /boot/firmware/config.txt

Add:

hdmi_group=2
hdmi_mode=82 # 1920x1080p @ 60 Hz

Adjust based on your monitor if needed.

🔄 Step 9: Reboot and Test

sudo reboot

On reboot, the Raspberry Pi should:

  • Log in automatically

  • Start X

  • Launch Chromium in fullscreen

  • Load the ImmichFrame interface

Now we can install Immich server and frame app.

✅ PART 1 – Install Docker on Raspberry Pi 5

1. Switch to Root

sudo -i

2. Install Required Packages

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget nano ca-certificates gnupg lsb-release

3. Install Docker

curl -sSL https://get.docker.com | sh

4. Add Your User to Docker Group

Replace pi with your actual user if different:

sudo usermod -aG docker pi
newgrp docker

✅ PART 2 – Install Immich Server via Docker

1. Create the Immich Project Directory

sudo mkdir -p /opt/stacks/immich
cd /opt/stacks/immich

2. Download the Docker Compose File and Environment Config

wget --server-response https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml -O docker-compose.yml
wget --server-response https://github.com/immich-app/immich/releases/latest/download/example.env -O .env

3. Edit the Environment File

nano .env

Set values like:

  • UPLOAD_LOCATION=./library

  • DB_DATA_LOCATION=./postgres

  • Update DB_PASSWORD to a secure value.

  • Change TZ if needed.

  • Set IMMICH_VERSION=release for latest.

4. Start Immich Server

docker compose pull
docker compose up -d

5. Get Your Pi IP Address

hostname -I

Visit Immich in your browser:

http://<your-pi-ip>:2283

✅ PART 3 – Install ImmichFrame

1. Create Directory Structure

sudo mkdir -p /opt/stacks/immichframe/config
cd /opt/stacks/immichframe

2. Create the docker-compose.yml file

nano docker-compose.yml

Paste and modify (example with correct Album ID and API key):

version: "3.8"

services:
immichframe:
container_name: immichframe
image: ghcr.io/immichframe/immichframe:latest
restart: unless-stopped
ports:
- "8777:8080"
environment:
TZ: "Europe/London"
ImmichServerUrl: "http://192.168.1.40:2283"
ApiKey: "PRJnxrfelfmbSDXeY9aC9wfTVyHm3RfWffjayTUWtYs"
AuthenticationSecret: "test"
ImageZoom: "true"
Interval: "10"
TransitionDuration: "2"
Albums: "a6a4fc49-4dfe-4e05-a259-4791fee4f413"
ShowMemories: "false"
ShowFavorites: "false"
ImagesFromDays: ""
ImagesFromDate: ""
ImagesUntilDate: ""
ShowClock: "true"
ClockFormat: "HH:mm"
ShowImageDesc: "true"
ShowImageLocation: "true"
ShowPhotoDate: "true"
PhotoDateFormat: "dd/MM/yyyy"
RenewImagesDuration: "30"
DownloadImages: "false"
RefreshAlbumPeopleInterval: "12"
PrimaryColor: "#f5deb3"
BaseFontSize: "17px"
Style: "none"
Layout: "splitview"

3. Create and Edit Settings.yml

nano /opt/stacks/immichframe/config/Settings.yml

Fill in as:

General:
AuthenticationSecret: test
DownloadImages: true
RenewImagesDuration: 30
Webcalendars: [] RefreshAlbumPeopleInterval: 12
PhotoDateFormat: dd/MM/yyyy
ImageLocationFormat: 'City,State,Country'
WeatherApiKey: ''
UnitSystem: metric
WeatherLatLong: '51.509865,-0.118092'
Language: en
Interval: 45
TransitionDuration: 2
ShowClock: true
ClockFormat: 'HH:mm'
ShowProgressBar: true
ShowPhotoDate: true
ShowImageDesc: true
ShowPeopleDesc: true
ShowAlbumName: true
ShowImageLocation: true
PrimaryColor: '#f5deb3'
SecondaryColor: '#000000'
Style: none
BaseFontSize: 17px
ShowWeatherDescription: true
ImageZoom: true
ImagePan: false
ImageFill: false
Layout: splitview

Accounts:
- ImmichServerUrl: http://192.168.1.40:2283
ApiKey: PRJnxrfelfmbSDXeY9aC9wfTVyHm3RfWffjayTUWtYs
Albums:
- a6a4fc49-4dfe-4e05-a259-4791fee4f413
ShowMemories: false
ShowFavorites: false
ShowArchived: false
ImagesFromDays: null
ImagesFromDate: null
ImagesUntilDate: null
Rating: null
ExcludedAlbums: [] People: []

4. Start ImmichFrame

cd /opt/stacks/immichframe
docker compose pull
docker compose up -d

Visit in browser:

http://<your-device-ip>:8777

📝 Ending Paragraphs for the Article

This guide transforms your Raspberry Pi 5 and a touch screen into a powerful, customizable smart photo frame, using Immich as the backend and Chromium kiosk mode as the frontend. Unlike off-the-shelf solutions like Kodak or Framo, this setup gives you full control — filters, albums, time ranges, and even remote access via SSH.

ImmichFrame lets you display the photos that matter most — from specific people, events, or timelines — and do it with a polished, responsive interface. You can also use external storage, NAS, or cloud syncing depending on your needs.

Whether you’re repurposing a display, making a gift, or building a smart home dashboard, this open-source photo frame project is one of the most rewarding DIY Raspberry Pi builds out there.

If you enjoyed this project, consider supporting the channel by using the affiliate links in the shopping list above. They help keep these guides free and regularly updated. Thanks for reading — and happy building!

🛒 Shopping List (with Affiliate Links)

Products shown or required in the setup:



If you like this service, please consider supporting us.
We use affiliate links on the blog allowing NAScompares information and advice service to be free of charge to you. Anything you purchase on the day you click on our links will generate a small commission which is used to run the website. Here is a link for Amazon and B&H. You can also get me a ☕ Ko-fi or old school Paypal. Thanks! To find out more about how to support this advice service check HERE   If you need to fix or configure a NAS, check Fiver   Have you thought about helping others with your knowledge? Find Instructions Here  

☕ WE LOVE COFFEE ☕

Or support us by using our affiliate links on Amazon UK and Amazon US
     

locked content ko-fi subscribe

Discover more from NAS Compares

Subscribe to get the latest posts sent to your email.


DISCUSS with others your opinion about this subject.
ASK questions to NAS community
SHARE more details what you have found on this subject
CONTRIBUTE with your own article or review. Click HERE
IMPROVE this niche ecosystem, let us know what to change/fix on this site
EARN KO-FI Share your knowledge with others and get paid for it! Click HERE

ASK YOUR QUESTIONS HERE!