Displays

Any screen with a modern browser can be a Lantern wall display: it opens /display on your Lantern, shows a pairing code, and an admin enters the code on the app’s Displays page (DSP-1). This page covers a dedicated display first, on a mini PC with the display package or on a Raspberry Pi with the image built from it, then other devices, then how to keep a display going for years.

A mini PC: the display package

Any small computer that runs Debian 13 (Trixie) can be a dedicated display: a mini PC, a NUC, or an old laptop. The lantern-display package turns it into one (DSP-10): at boot it opens your Lantern’s /display in Chromium, full screen, with no desktop. The server stays on your Docker host; the PC only shows it.

Installing.

Install Debian 13 from its netinst image. At Software selection, untick the desktop environment and GNOME, and keep standard system utilities; tick SSH server if you want to reach the PC from a computer. Create a user of your own.
Copy lantern-display_X.Y.Z_all.deb from a Lantern release (or build it, below) to the PC, then install it:
Terminal window
```
sudo apt install ./lantern-display_X.Y.Z_all.deb
```
It asks for your Lantern’s address, the one you open the app at, such as https://lantern.example.com, and brings Chromium and the cage compositor with it.
Restart. The PC boots into the display and shows a pairing code: pair it as below.

Changing the address. Plug in a keyboard, press Ctrl+Alt+F2, sign in, and run sudo dpkg-reconfigure lantern-display. The display restarts at the new address.

Turning the screen. For a screen mounted on its side or upside down, sudo dpkg-reconfigure lantern-display also asks for the rotation: 90, 180, or 270 degrees. The picture turns, and so does a touch screen’s touch. 90 and 270 are the two quarter turns: if the picture comes out upside down, choose the other one. The setting is the rotate= line in /etc/lantern-display/lantern.txt. A screen plugged in later turns at the next restart.

What the package does by itself:

Restarts the browser if it exits, and the PC if the system hangs, where it has a hardware watchdog (most Intel and AMD mini PCs do).
Installs security updates for the OS and the browser every day, from Debian’s repositories, and restarts at 04:00 when an update needs it. Those repositories and your Lantern are the only places it connects to; the browser’s metrics, sign-in, translation, Safe Browsing, and other background services are off.
Never blanks the screen. Use the display’s night mode for the dark hours (its settings in the app).

It comes back by itself after a power cut; set the PC’s firmware to power on when power returns (often Restore on AC power loss in its BIOS settings). sudo apt purge lantern-display gives the console back to its login prompt.

Building the package

The package holds only scripts and settings, so one file (all) serves every architecture, amd64 and arm64 alike. Any machine with Docker builds it, unprivileged, in a few seconds:

scripts/build-display-package.sh 1.2.0

It writes lantern-display_1.2.0_all.deb and its .sha256 to out/display/. The package’s files are in display-package/ (its README describes them). CI builds it and checks what’s in it (scripts/display-package.test.ts).

Raspberry Pi: the Lantern display image

A Raspberry Pi 4 (2 GB or more) or Raspberry Pi 5, a screen (HDMI, or the official Touch Display 2), and a microSD card of 16 GB or more. The image is Raspberry Pi OS Lite (Trixie, 64-bit) with the display package installed, so it boots straight into the display, full screen, with no desktop (DSP-10). The server stays on your Docker host; the Pi only shows it.

Flashing. In Raspberry Pi Imager:

Choose the image:
- From a Lantern release, start Imager with the release’s repository file (rpi-imager --repo https://GITEA_HOST/OWNER/lantern/releases/download/vX.Y.Z/lantern-display.json) and pick Lantern display.
- Or choose Use custom with the downloaded .img.xz.
Edit the settings Imager offers: set the Wi-Fi network (skip it for Ethernet), the hostname, and a user and password of your own. Turn on SSH there only if you want to reach the Pi from a computer.
Write the card.

Pointing it at your Lantern. Before the first boot, open the card’s bootfs drive on your computer and edit lantern.txt: after server=, put the address you open Lantern at, such as server=https://lantern.example.com. Without it, the Pi shows a page saying how to set it. You can change it the same way later.

Turning the screen. For a screen mounted on its side or upside down, set rotate= in the same file to 90, 180, or 270 degrees; the picture turns, and so does a touch screen’s touch. 90 and 270 are the two quarter turns: if the picture comes out upside down, use the other one.

Pairing. Put the card in the Pi and switch it on. Within about a minute and a half the screen shows a pairing code. In the Lantern app, open Displays, choose Pair a display, enter the code, and name the display. A code lasts 10 minutes, and the screen shows a new one by itself.

What the image does by itself:

Restarts the browser if it exits, and the Pi if the system hangs (the hardware watchdog).
Installs security updates for the OS and the browser every day, from Debian’s and Raspberry Pi’s repositories, and restarts at 04:00 when an update needs it. Those repositories and your Lantern are the only places it connects to; the browser’s metrics, sign-in, translation, Safe Browsing, and other background services are off.
Keeps its logs in memory, sparing the SD card; they go at each restart.
Never blanks the screen. Use the display’s night mode for the dark hours (its settings in the app).

It comes back by itself after a power cut. To maintain it, plug in a keyboard and switch to the second console (Ctrl+Alt+F2), or SSH in if you turned it on.

Building the image

The image is built from pi-image/stage-lantern/ with Raspberry Pi’s pi-gen, with the display package installed in it, which the script builds first. It needs Docker that can run privileged containers with loop devices (root Docker; rootless Docker and the CI runners can’t), about 30 GB of disk, and about an hour:

LANTERN_ICON_SOURCE=https://lantern.example.com/icons/icon-192.png scripts/build-pi-image.sh 1.2.0

It writes to out/pi-image/:

lantern-display-1.2.0-arm64.img.xz and its .sha256;
lantern-display.json, the Imager repository file;
lantern-display.png, the icon Imager shows, from the instance you named.

and the package it installed, to out/display/.

A second argument sets the URL prefix the repository file points at, such as the release’s download folder (docs/gitea.md, “Releases”). CI checks the image’s definition (scripts/pi-image.test.ts), not the image.

A display nobody touches

A plain monitor works too, with no keyboard, mouse, or touch panel: behind a two-way mirror, for example. Pair it as above: the code shows on the screen, and you enter it in the app. Then open Displays in the app, open the display, and set it up for a screen nobody taps:

No touch: on. The display shows no tabs, buttons, or mouse pointer, so its screen has the room, and its keyboard never comes up.
Opens on: the screen it shows all day, such as Home or a calendar view. It moves on to each new day by itself.
Screensaver: turn off Show the screensaver. It’s on by default and starts after the display’s idle minutes, and with no touch nothing ends it, so the display would show photos for good. Leave it on only for a photo frame.
Night mode: dims the display, or turns it black, on a schedule that starts and ends by itself.

To use another screen, or to wake the display during the night-mode hours, turn No touch off in the app and use a touch screen or a mouse.

Other computers

On Debian, use the display package above. Any other Linux computer with Chromium will do too: start Chromium in kiosk mode at boot, for example with the same compositor the image uses (cage -- chromium --kiosk https://lantern.example.com/display) as a systemd service, or with your desktop’s autostart. Keep the screen from blanking, and let Lantern’s night mode dim it.

Tablets

Android tablets: a kiosk browser app (one that locks to a single site and keeps the screen on), pointed at https://<your Lantern>/display.
Fire tablets: the same, with a kiosk browser from the Amazon Appstore.
iPads: open the address in Safari, add it to the Home Screen, open it from there, and lock it with Guided Access (Settings > Accessibility > Guided Access).

Keeping it going

Mounting: at eye height where the family passes, out of direct sun, with the cable routed down the wall. A Pi can sit behind the screen on a VESA mount.
Power: the official power supply for the Pi (5 V 3 A for a Pi 4, 5 V 5 A for a Pi 5); a weak one causes freezes and SD card corruption.
Screen burn-in: night mode switches the display off or dims it overnight; on OLED screens, use the off setting.
Batteries: a tablet left on its charger day and night can swell its battery over months. Charge it on a smart plug that cycles (a few hours on, a few off), or use battery-free hardware such as a Pi with a monitor.