rc/fri-alpine-signage
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
fri-alpine-signage/README.md

7.3 KiB
Raw Blame History

Alpine Linux Kiosk Setup Script

This script automates the setup of a minimal, Wayland-based kiosk on Alpine Linux. It configures the system to automatically log in a dedicated user and launch a full-screen Chromium browser displaying a specified URL. It uses Sway as the Wayland compositor, greetd for autologin, and WayVNC for remote access.

Features

  • Minimal Base: Leverages Alpine Linux for a small footprint.
  • Wayland Native: Uses Sway for a modern display server environment.
  • Chromium Kiosk: Launches Chromium in full-screen kiosk mode.
  • Autologin: Uses greetd with agreety to automatically log in the signage user and start Sway.
  • Configurable Remote Access (WayVNC):
    • TLS Authenticated: Option to enable username/password authentication for WayVNC, secured with self-signed TLS certificates generated by the script.
    • Passwordless: Option for passwordless VNC access (use with caution on trusted networks or with SSH tunneling).
  • VM Friendly: Includes open-vm-tools for better integration when run in VMware.
  • Customizable: Key settings like KIOSK URL, signage user, and WayVNC options can be configured.
  • Dynamic Step Logging: Script output clearly indicates progress with dynamic step numbering.
  • Colorized Output: Script output uses colors for better readability.

Prerequisites

  • A fresh installation of Alpine Linux (standard or extended).
  • Internet connectivity during the script execution to download packages.
  • The script must be run as the root user.

Configuration

Before running the script, you can adjust the following variables at the top of the setup-kiosk.sh file:

  • KIOSK_URL: The URL that Chromium will display. (Default: "https://example.com")
  • SIGNAGE_USER: The dedicated user account for the kiosk. (Default: "signage")

WayVNC Configuration:

  • WAYVNC_ENABLE_TLS_AUTH:
    • Set to true (default) to enable username/password authentication for WayVNC. This will also generate self-signed TLS certificates for encryption. openssl package will be installed.
    • Set to false for passwordless VNC access. WayVNC will start without requiring authentication.
  • WAYVNC_PASSWORD_TO_SET:
    • Used only if WAYVNC_ENABLE_TLS_AUTH is true.
    • Set a strong password here. (Default: "burek123" - CHANGE THIS!)
    • If left blank and TLS auth is enabled, the script will use an INSECURE default password "changeme" and issue a critical warning.
  • WAYVNC_USERNAME: The username for VNC authentication if WAYVNC_ENABLE_TLS_AUTH is true. (Default: "signage_vnc")
  • WAYVNC_LISTEN_ADDRESS: The IP address WayVNC listens on. (Default: "0.0.0.0" for all interfaces)
  • WAYVNC_PORT: The port WayVNC listens on. (Default: "5900")

Usage

  1. Download the script:

    wget -O setup-kiosk.sh <URL_TO_YOUR_SCRIPT_RAW_FILE>
# or copy the script content into a file named setup-kiosk.sh

  2. Review and Edit Configuration: Open setup-kiosk.sh and adjust the configuration variables, especially WayVNC settings, to your needs. Ensure you set a strong WAYVNC_PASSWORD_TO_SET if WAYVNC_ENABLE_TLS_AUTH is true.

  3. Make it executable:

    chmod +x setup-kiosk.sh

  4. Run as root:

    sudo ./setup-kiosk.sh
# or if already root:
# ./setup-kiosk.sh

  5. Follow Prompts/Review Output: The script will output its progress. Pay attention to any warnings, especially regarding nomodeset or WayVNC password settings.

  6. Reboot:

    reboot

    The system should automatically log in and launch the kiosk.

Post-Installation

Remote Access (VNC)

  • If WAYVNC_ENABLE_TLS_AUTH was true:
    • Connect to the kiosk using a VNC client to the IP address of your Alpine Linux machine on the port specified by WAYVNC_PORT (default 5900).
    • You will be prompted for the WAYVNC_USERNAME and WAYVNC_PASSWORD_TO_SET configured in the script.
    • Your VNC client will likely warn about an untrusted certificate because it's self-signed by the script. You will need to review and accept this certificate to proceed.
  • If WAYVNC_ENABLE_TLS_AUTH was false:
    • Connect to the kiosk using a VNC client to the IP address and port. No password will be required.
    • SECURITY WARNING: This mode is insecure. It's highly recommended to restrict network access to the VNC port (e.g., using a firewall) or access it exclusively via an SSH tunnel.

Troubleshooting

The script provides a list of troubleshooting steps at the end of its execution. Key logs and checks include:

  • Greetd logs: grep greetd /var/log/messages | tail -n 20
  • Sway log: cat /home/<SIGNAGE_USER>/.local/share/sway/sway-greetd.log
  • Sway config syntax check: 
    # Replace 'signage' if needed
su - signage -c "export XDG_RUNTIME_DIR=/run/user/$(id -u signage) && sway -C -c /home/signage/.config/sway/config"
  • WayVNC Configuration (if TLS auth enabled): cat /home/<SIGNAGE_USER>/.config/wayvnc/config
  • Required user groups: groups <SIGNAGE_USER> (should include video and input)
  • Manually test Sway (on TTY2, after stopping greetd): 
    rc-service greetd stop # Stop greetd on TTY1
# Switch to TTY2 (Alt+F2), log in as <SIGNAGE_USER>
dbus-run-session sway -d

Modifying Chromium Flags

Chromium is launched with --disable-gpu by default for compatibility. To try enabling GPU acceleration:

  1. Edit the Sway configuration file: vi /home/<SIGNAGE_USER>/.config/sway/config
  2. Find the exec /usr/bin/chromium ... line and remove or comment out --disable-gpu.
  3. Save, then reload Sway (Mod+Shift+c or swaymsg reload) or reboot.

Kernel Parameter nomodeset

If the script warns about nomodeset, Wayland (and Sway) will not function correctly. Remove this parameter from your bootloader configuration (e.g., /etc/default/grub or /boot/extlinux.conf), update your bootloader, and reboot.

Script Breakdown

The script performs the following major steps:

  1. Root Check & Initial Info.
  2. nomodeset Check.
  3. Package Repositories Update.
  4. Wayland Base Setup (elogind, eudev).
  5. Package Installation: Installs Sway, Chromium, greetd, WayVNC, etc. openssl is installed conditionally if TLS auth for WayVNC is enabled.
  6. D-Bus Service Setup.
  7. open-vm-tools Service Setup.
  8. Signage User Creation (with video and input group membership).
  9. User Profile Configuration.
  10. WayVNC Configuration:
    • If WAYVNC_ENABLE_TLS_AUTH is true: Generates self-signed TLS keys/certificates and creates /home/<SIGNAGE_USER>/.config/wayvnc/config with authentication enabled.
    • If false: Skips WayVNC config file creation, ensuring WayVNC starts without its internal authentication.
  11. Sway Configuration: Creates ~/.config/sway/config to autostart Chromium and WayVNC (launch arguments for WayVNC depend on the auth setting).
  12. Greetd Configuration for autologin.
  13. Inittab Configuration to launch greetd on tty1.
  14. PAM Configuration for elogind session management.
  15. Final Information & Troubleshooting.

License

This script is provided as-is. Feel free to use and modify it.