Debian mini PC browser appliance

A locked kiosk that boots straight into Kousen CommandCenter.

This project documents and automates the setup for a small Linux mini PC that powers on, skips the desktop, launches Chromium in kiosk mode, and opens https://kousen.cc as a family-friendly LAN command center.

Follow The Install View Repository

Power On BIOS hands off to Debian.

Auto Login An unprivileged user starts X.

Kiosk Browser Chromium opens full screen.

CommandCenter Cards launch Plex, KousenTV, and more.

What This Project Does

Kousen Kiosk is the appliance layer for Kousen CommandCenter. It does not host the web app. It configures a mini PC so the web app feels like the device's native interface.

Goal

Single-purpose browser

The device should boot directly into https://kousen.cc without exposing a normal desktop, launcher, file manager, or terminal to the kiosk user.

Security

Separate admin and kiosk users

The installer creates an unprivileged kiosk account for the browser. Maintenance stays with the Debian admin user created during install.

Recovery

SSH stays available

The first version keeps recovery practical. You can SSH into the admin user, pull repo updates, rerun the installer, or disable kiosk auto-login.

Hardware And Design Choices

The build was tested on a GMKtec NucBox 7 with an Intel Pentium Silver N6005, 16 GB RAM, and a 1 TB M.2 2242 SATA SSD. The scripts are generic enough for other x86_64 mini PCs.

Why Debian minimal?

Debian stable minimal is lean, predictable, and avoids a full desktop stack. Ubuntu Server LTS should also work, but Debian keeps this appliance setup simpler.

No GNOME, KDE, XFCE, or other desktop environment
Only the display, browser, network, audio, and recovery pieces needed
Package-managed Chromium, Xorg, Openbox, NetworkManager, and PipeWire

USB-C limitation

The NucBox 7 USB-C port should be treated as power input only. The manual labels it Type-C DC IN ONLY, so USB-C video output should not be expected.

Use HDMI for video
Use HDMI, analog, or USB for audio
A USB-C monitor may power the device without carrying video

Step-by-step Install

These are the installation choices used during the actual mini PC setup, rewritten as a repeatable guide. The goal is a clean Debian install that can be managed over SSH and then converted into a kiosk.

Flash Debian to a USB installer

Download the Debian stable amd64 netinst ISO and flash it to an 8 GB or larger USB drive with a tool such as balenaEtcher. The amd64 image is correct for normal 64-bit Intel and AMD mini PCs.

Boot the mini PC from USB

Connect a monitor, keyboard, USB installer, and Ethernet if available. On the GMKtec box, use F7 for the boot menu or Esc for BIOS/UEFI setup. Choose the USB installer.

Choose the primary network interface

If Debian shows multiple interfaces, pick the wired Ethernet port that has the cable connected. On the tested box, Debian showed Realtek Ethernet interfaces such as enp1s0 and enp2s0, plus Intel Wi-Fi such as wlo1. If DHCP fails, go back and try the other Ethernet port.

Lock direct root login

When the installer asks for a root password, leave it blank. Debian will lock direct root login and grant administrative access to the first normal user through sudo.

Create the admin user

Create a maintenance user for SSH, updates, recovery, WiFi setup, and future changes. In the tested install, the full name was Kousen Admin and the username was kousen. Do not name this user kiosk; the installer creates that browser-only user later.

Use the whole internal SSD

Choose Guided - use entire disk, select the internal M.2 SATA SSD, and choose All files in one partition. Avoid encrypted LVM for this appliance because it would require a passphrase at boot.

Leave proxy blank

When Debian asks for HTTP proxy information, leave it blank unless your network specifically requires a proxy.

Select only server utilities

On the software selection screen, deselect Debian desktop environment and GNOME. Keep SSH server and standard system utilities selected.

Log in after reboot

After the installer finishes and the mini PC reboots, log in as the admin user created earlier. At the shell prompt, install Git and clone the public repo.

sudo apt-get update
sudo apt-get install -y git ca-certificates
git clone https://github.com/npkousen/kousen-kiosk.git
cd kousen-kiosk

Run the kiosk installer

The installer provisions Chromium, Xorg, Openbox, NetworkManager, PipeWire, the home key, WiFi helper, audio helper, kiosk auto-login, and GRUB boot cleanup.

sudo ./scripts/install.sh
sudo reboot

Installer Screen Choices

This table summarizes the choices made during the photographed Debian installation.

Installer screen	Recommended choice	Reason
Primary network interface	Wired Ethernet first, Wi-Fi later	Ethernet makes the base install and first repo clone simpler. Wi-Fi is configured after the kiosk tools are installed.
Root password	Leave blank	Locks direct root login and uses the admin user with `sudo`.
Admin user	Use a normal maintenance account, not `kiosk`	The installer owns the `kiosk` user and keeps it unprivileged.
Partition method	`Guided - use entire disk`	The device is a dedicated appliance. A plain install is easiest to recover.
Partition scheme	`All files in one partition`	Simple layout, no benefit from separate partitions for this use case.
HTTP proxy	Blank	Normal home networks do not need a proxy.
Software selection	`SSH server` and `standard system utilities` only	A full desktop creates unwanted escape routes and UI surfaces.

How The Finished Kiosk Works

After installation, the mini PC becomes a managed browser appliance rather than a general-purpose desktop.

Boot polish

The installer hides the GRUB menu, quiets Linux boot messages, and starts the kiosk session automatically on tty1.

Universal home key

Home, browser Home, Ctrl+Alt+Home, Super+Home, and F12 return Chromium to https://kousen.cc, even from Plex.

WiFi

Run sudo kousen-configure-wifi, choose the SSID, and enter the password. The saved connection persists across reboots.

Audio

PipeWire and WirePlumber are started for Chromium. On boot, the kiosk prefers HDMI audio, then built-in analog, then the first available sink.

Bluetooth

The tested hardware exposes a Bluetooth controller. A Bluetooth remote should work if it pairs as a keyboard or media remote.

Updates

SSH into the admin account, run git pull, rerun sudo ./scripts/install.sh, and reboot. CommandCenter card updates happen in the separate CommandCenter repo.

Useful Commands

These are the commands used most often after the kiosk is installed.

Update the kiosk

ssh kousen@kousen-kiosk.local
cd ~/kousen-kiosk
git pull
sudo ./scripts/install.sh
sudo reboot

Configure WiFi

sudo kousen-configure-wifi
ping -c 3 github.com
sudo reboot

Inspect audio

sudo kousen-configure-audio
sudo kousen-configure-audio auto

Disable kiosk auto-login

cd ~/kousen-kiosk
sudo ./scripts/disable-kiosk.sh
sudo reboot

Troubleshooting Notes From The Build

These are the real issues encountered during the first install and the fixes that were added to the repo.

Chromium crashed to a blinking cursor

Chromium failed before the page loaded because the minimal session was missing pieces it expected. The launcher now sets explicit XDG directories, disables crash reporter prompts, and runs Chromium through dbus-run-session.

Browser only filled half the screen

X detected the monitor correctly, but Chromium behaved poorly under bare X. Openbox was added as a tiny window manager, and the launcher now detects the active display geometry with xrandr.

Network was not ready when Chromium opened

The launcher waits up to 60 seconds for NetworkManager before opening the browser, which reduces first-boot offline pages on Wi-Fi.

Plex captured the home key

The first home key used simulated typing, which Plex could capture in search. The current home key uses Chromium's localhost debugging API to navigate directly back to CommandCenter.

HDMI audio did not play

ALSA saw HDMI hardware, but the minimal install had no PipeWire session. The installer now adds PipeWire, WirePlumber, and an automatic audio selector.

USB-C monitor showed no image

The NucBox 7 USB-C port is power-only. Use HDMI for video. A USB-C monitor may power the mini PC while still requiring HDMI for picture and sound.

Public repo note: keep WiFi passwords, SSH private keys, tokens, VPN configs, and personal recovery notes out of this repository. The scripts and public LAN shortcut patterns are fine to publish; credentials are not.

Quick Reference

A compact view of the working target state.

boot target: Debian minimal
kiosk URL: https://kousen.cc
admin user: created during Debian install
kiosk user: kiosk, created by installer, no sudo
display: HDMI, auto-detected by xrandr
browser: Chromium kiosk mode
window manager: Openbox
network: NetworkManager, Ethernet or WiFi
audio: PipeWire/WirePlumber, HDMI preferred
home key: Home / XF86HomePage / Ctrl+Alt+Home / Super+Home / F12
update flow: git pull -> sudo ./scripts/install.sh -> reboot