Build, boot, display.
About
·
Features
·
Quick Start
·
Keyboard Shortcuts
·
Documentation
DisplayOS is a lightweight, security-focused Linux distribution based on Debian Bookworm, built for digital signage and kiosk systems.
It produces a bootable ISO image that installs an unattended system booting directly into a fullscreen browser displaying a configurable URL. The build is driven entirely by a single configuration file (config.env) and a set of modular shell scripts that wrap Debian's live-build framework.
- Zero-touch deployment - Build once, deploy anywhere with preseeded installation
- Offline-first - Complete installation from live media, no network required
- Security by default - Non-root desktop, locked root account, kernel hardening
- Modern audio - PipeWire with PulseAudio compatibility for reliable audio control
- Reproducible - Configuration-driven builds ensure consistency across deployments
- 🚀 Fully unattended installer with preseeded Debian installer
- 💿 Offline installation from live media
- 🔐 Non-root autologin with sudo privileges for administration
- 🌐 Browser kiosk mode (Firefox ESR or Chromium)
- 🔊 PipeWire audio with PulseAudio compatibility
- 📺 Configurable display URL via environment variables
- 🎨 Custom branding (wallpaper, GRUB theme, product name)
- 🔧 SSH access for remote administration
- 📦 Working package manager with pre-configured APT repositories
- A Debian-based Linux host (Debian 12+, Ubuntu 22.04+, or similar)
- Root access (via
sudo) - At least 15 GB of free disk space
- Internet connection (for downloading Debian packages during build)
Build dependencies are installed automatically by the build script.
git clone https://github.com/OnlyDrey/DisplayOS.git
cd DisplayOS
chmod +x build.sh scripts/*.shEdit config.env to set your kiosk URL, username, password, and other options:
nano config.envKey variables:
| Variable | Default | Description |
|---|---|---|
KIOSK_URL |
https://example.com |
URL displayed in the fullscreen browser |
SET_USERNAME |
displayos |
Username for the autologin user (has sudo) |
SET_PASSWORD |
(empty) | User password; leave empty to auto-generate |
DEFAULT_BROWSER |
firefox-esr |
firefox-esr or chromium |
ENABLE_SSH |
yes |
Enable SSH server on the installed system |
See Configuration Reference for all available variables.
sudo ./build.shOr override variables at build time:
sudo -E KIOSK_URL="https://dashboard.example.com" SET_USERNAME="kiosk" SET_PASSWORD="changeme" ./build.shThe output ISO is placed at:
output/DisplayOS-bookworm-amd64-unattended.iso
sudo dd if=output/DisplayOS-bookworm-amd64-unattended.iso of=/dev/sdX bs=4M status=progress
syncReplace /dev/sdX with your USB device.
| Shortcut | Action |
|---|---|
Ctrl+Alt+T |
Open terminal |
Ctrl+Alt+W |
Open Wi‑Fi configuration (nmtui in terminal) |
Comprehensive documentation is available in the docs/ directory:
| Document | Description |
|---|---|
| Configuration Reference | Complete variable reference for config.env |
| Audio Configuration | PipeWire setup and troubleshooting |
| System Behavior | Runtime behavior and boot sequence |
| Build Process | Step-by-step build pipeline explanation |
| Troubleshooting | Common issues and solutions |
| Customization | How to customize branding and behavior |
| Installer Branding | Theming the Debian installer UI |
| Host Requirements | Build host dependencies and requirements |
| Directory Structure | Repository and runtime file layout |
| Development | Contributing and extending the build |
DisplayOS/
├── build.sh # Build orchestrator (entrypoint)
├── config.env # All configuration variables
├── scripts/ # Numbered build stages (00 through 10)
├── assets/ # Wallpaper, splash, logo, installer header
├── docs/ # Detailed documentation
├── config/ # Generated at build time by live-build
└── output/ # Build artifacts (ISO, log, config dump)
DisplayOS is licensed under the GNU General Public License v3.0.
DisplayOS builds upon: