Linux agent (PromoBrowser) — Installation

PromoBrowser is a kiosk-style browser based on Python + PyQt5 / QtWebEngine. It runs fullscreen, with no desktop (boots directly on VT7), via a systemd service.

Requirements

• Debian 12 (Bookworm) or higher, or Ubuntu 22.04 LTS or higher.
• Root access (to install system packages and register the service).
• Python 3.11+ (included in Debian 12 / Ubuntu 22.04).
• No desktop environment needed.

Quick install (recommended)

Run as root:

curl -fsSL https://rds.digitalsignagerds.com/install.sh | bash

The script:

1. Installs system packages:
   • PyQt5 + QtWebEngine + gstreamer (player)
   • python3-xlib, xorg, xinit (minimal X session)
   • gpsd + gpsd-clients (optional GPS module — if a USB GPS is plugged in, it's auto-detected via USBAUTO=true)
   • onboard (on-screen keyboard for touchscreens, shown automatically when opening the Settings dialog)
   • scrot (screenshot utility; used by the remote screenshot system from RDS)
2. Creates the venv at /opt/promobrowser/.venv with --system-site-packages.
3. Registers the kiosk-browser systemd service.
4. Configures auto-start on VT7.
5. Enables gpsd.socket (socket activation) — the daemon starts on demand when the agent or a client requests it.

After installing:

systemctl start kiosk-browser
chvt 7

chvt 7 switches the active virtual console so you can see the browser on screen. Skip it if your machine boots with a graphical environment already active.

Manual install

git clone --branch main --depth 1 https://github.com/promotienda/promobrowser.git
cd promobrowser
sudo bash install.sh
systemctl start kiosk-browser
chvt 7

Development (no service)

To try the agent without installing it as a service:

bash run.sh

Auto-installs dependencies and starts X automatically if no display is detected.

Verification

systemctl status kiosk-browser        # service status
journalctl -u kiosk-browser -f        # live systemd logs
tail -f /tmp/kiosk.log                # application logs

If everything is correct, you should see the fullscreen browser on VT7 with the default URL (or your home URL if already configured).

Initial configuration

On first boot the agent opens a blank browser and waits for you to link the device:

1. Open settings — two equivalent ways:
   • Keyboard: type 12345 (the combo works at any time, even with the web page focused).
   • Touchscreen / mouse: tap 5 times in the top-left corner within 2 seconds.
2. A numpad asks for the passcode. Default is 0000. Change it from the Security tab as soon as possible.
3. Go to the Server tab:
   • Server URL — https://rds.digitalsignagerds.com (default).
   • Username — the user Promotienda created for you.
   • Device ID — the RDSXXXX you assigned to this device in the web panel.
   • Press Test Connection — checks credentials and registers the device with the server.
4. Kiosk configuration (Web / Playlist mode, home URL, whitelist, passcode) is managed from the web panel — the device receives it on its next heartbeat.

Minimum version