Extrudex/docs/PI-KIOSK-SETUP.md

Pi 5 Kiosk Setup — Extrudex (Go + React)

Prerequisites

• Raspberry Pi 5 (4 GB or 8 GB)
• MicroSD card (32 GB minimum, Class 10+)
• HDMI touchscreen display
• USB barcode scanner (HID keyboard mode)
• Power supply (27W USB-C recommended)

One-Line Setup

# 1. Install Raspberry Pi OS (64-bit, Desktop)
# 2. Enable SSH and VNC
# 3. Run the automated bootstrap
curl -sSL https://raw.githubusercontent.com/CubeCraft-Creations/Extrudex/dev/scripts/pi-bootstrap.sh | bash

Or follow the manual steps below.

Manual Setup

1. Install Docker

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker pi

Log out and back in for group changes to take effect.

2. Clone and deploy

cd /home/pi
git clone https://code.cubecraftcreations.com/CubeCraft-Creations/Extrudex.git
cd Extrudex
git checkout dev

# Run the deploy script
chmod +x deploy.sh
./deploy.sh

3. Verify services

docker compose -f docker-compose.dev.yml ps
# All three services should be "Up"

Check the health endpoint:

curl http://localhost:5080/health
# Expected: {"status":"ok","db_connected":true,"timestamp":"..."}

4. Configure kiosk auto-start

# Enable the Docker stack service (starts on boot)
sudo cp systemd/extrudex.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable extrudex.service

# Enable the kiosk service (starts Chromium after Docker stack)
sudo cp systemd/extrudex-kiosk.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable extrudex-kiosk.service

5. Configure display server

For Pi 5, Raspberry Pi OS uses Wayland by default. If you encounter X11-specific issues, switch to X11 in raspi-config (Advanced Options → Resolution → X11).

The kiosk service supports both Wayland and X11 display servers.

6. Touchscreen calibration (if needed)

# Install calibration tools
sudo apt install -y xinput-calibrator

# Run calibration, note the device ID and parameters
xinput_calibrator

Add the calibration to ~/.config/labwc/labwc.conf or /etc/X11/xorg.conf.d/ as appropriate for your display server.

USB Barcode Scanner

The USB barcode scanner works as a HID keyboard device — it types scanned codes followed by an Enter keypress. No driver configuration is needed.

On the React frontend, the search input auto-focuses on page load and will capture barcode input immediately. After a touch on another element, tap the search field again to re-focus.

Auto-Refresh on Wake

The React app polls the SSE endpoint every 30 seconds for real-time updates. When the Pi wakes from sleep, the next poll will immediately sync the UI.

The kiosk service has Restart=always and RestartSec=10, so Chromium will restart within 10 seconds of any crash or power cycle.

Touch Gestures

Chromium is launched with --touch-events=enabled and --enable-pinch for native touch gesture support:

• Tap — click/submit
• Two-finger scroll — page scrolling
• Pinch — zoom (disabled in kiosk mode by default; enable if needed)

Troubleshooting

Services not starting

sudo systemctl status extrudex
sudo systemctl status extrudex-kiosk
docker compose -f docker-compose.dev.yml logs

Kiosk shows blank page

• Ensure Docker stack is running: docker compose ps
• Check nginx is serving the React build: curl http://localhost:5081
• Check Chromium logs: journalctl -u extrudex-kiosk -n 50

Barcode not working

• Verify scanner is in HID keyboard mode (most USB scanners default to this)
• Open a text field and scan — you should see digits appear
• Check with dmesg | grep -i usb for device enumeration

PostgreSQL connection refused

docker compose -f docker-compose.dev.yml restart extrudex-db
# Wait 15 seconds, then check health
curl http://localhost:5080/health

Architecture

┌──────────────────────────────────────────────┐
│  Pi 5 (Raspberry Pi OS 64-bit)               │
│                                              │
│  ┌─────────────┐  ┌──────────┐  ┌─────────┐ │
│  │ Chromium    │  │  Nginx   │  │  Go     │ │
│  │ Kiosk       │→│  (React) │→│  API    │ │
│  │ :5081       │  │  :5080   │  │  :8080  │ │
│  └─────────────┘  └──────────┘  └────┬────┘ │
│                                       │      │
│                              ┌────────▼────┐ │
│                              │  PostgreSQL │ │
│                              │  :5432      │ │
│                              └─────────────┘ │
│                                              │
│  ┌──────────┐                                │
│  │  USB     │                                │
│  │ Scanner  │ → HID keyboard → Browser       │
│  └──────────┘                                │
└──────────────────────────────────────────────┘