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

7 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.
  • Remote Access: Includes WayVNC for remote desktop access to the kiosk session (password configuration required for security).
  • VM Friendly: Includes open-vm-tools for better integration when run in VMware.
  • Customizable: Key settings like the KIOSK URL, signage user, and WayVNC password 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_PASSWORD_TO_SET: Leave this blank in the script for better security. The script will remind you to set it manually in the user's ~/.profile after setup. If you must pre-set it, ensure it's a strong password.
  • 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. Make it executable:

    chmod +x setup-kiosk.sh

  3. Run as root:

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

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

  5. Change WayVNC Password: Edit the signage user's profile:

    # Replace 'signage' if you changed SIGNAGE_USER
vi /home/signage/.profile

    Uncomment and set the WAYVNC_PASSWORD variable:

    export WAYVNC_PASSWORD="your_very_secure_password_here"

    Save the file.

  6. Reboot:

    reboot

    The system should automatically log in and launch the kiosk.

Post-Installation

Remote Access (VNC)

  • 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_PASSWORD you set in /home/<SIGNAGE_USER>/.profile.

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 (replace <SIGNAGE_USER> with your chosen user)
  • 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"
  • Required user groups: groups <SIGNAGE_USER> (should include video and input)
  • Manually test Sway (on TTY2, after stopping greetd): 
    # Stop greetd on TTY1
rc-service greetd stop
# Switch to TTY2 (Alt+F2), log in as signage user
# Then, as signage user:
dbus-run-session sway -d

Modifying Chromium Flags

Chromium is launched with --disable-gpu by default for compatibility, especially in VMs. If you have working 3D acceleration and want to try enabling GPU acceleration for potentially better performance:

  1. Edit the Sway configuration file: 
    # Replace 'signage' if needed
vi /home/signage/.config/sway/config
  2. Find the exec /usr/bin/chromium ... line.
  3. Remove or comment out the --disable-gpu flag.
  4. You might also want to remove --ignore-gpu-blocklist.
  5. Save the file.
  6. You can reload Sway without rebooting (if you can access a terminal or via VNC): swaymsg reload or by pressing Mod+Shift+c (if you kept the default keybinding). Otherwise, reboot.

Kernel Parameter nomodeset

If the script warns about nomodeset being present in your kernel command line (/proc/cmdline), Wayland (and thus Sway) will not function correctly. You must remove this parameter from your bootloader configuration (e.g., /etc/default/grub for GRUB, or /boot/extlinux.conf for syslinux/extlinux) and update your bootloader, then reboot.

Script Breakdown

The script performs the following major steps:

  1. Root Check: Ensures it's run as root.
  2. nomodeset Check: Warns if nomodeset is active.
  3. Package Repositories: Updates Alpine's package repositories.
  4. Wayland Base Setup: Installs alpine-conf and runs setup-wayland-base (which enables community repo and installs elogind, eudev).
  5. Package Installation: Installs Sway, Chromium, Mesa drivers, D-Bus, fonts, firmware, greetd, WayVNC, and open-vm-tools.
  6. D-Bus Service: Enables and starts the D-Bus service.
  7. open-vm-tools Service: Enables and starts the open-vm-tools service.
  8. Signage User Creation: Creates the specified SIGNAGE_USER, their home directory, and adds them to video and input groups for necessary permissions.
  9. User Profile Configuration: Creates a ~/.profile for the signage user, mainly for setting the WAYVNC_PASSWORD environment variable.
  10. Sway Configuration: Creates a Sway config file (~/.config/sway/config) that:
    • Sets basic Sway options.
    • Explicitly enables and powers on display outputs.
    • Configures mouse cursor hiding.
    • Autostarts Chromium in kiosk mode pointing to KIOSK_URL.
    • Autostarts WayVNC.
    • Sets minimal keybindings for debugging/control.
  11. Greetd Configuration: Configures greetd (/etc/greetd/config.toml) to automatically log in the SIGNAGE_USER and launch Sway.
  12. Inittab Configuration: Modifies /etc/inittab to start greetd on tty1 instead of a regular login getty.
  13. PAM Configuration: Attempts to add pam_elogind.so to the PAM stack for proper session management with elogind.
  14. Final Information & Troubleshooting: Prints a summary and troubleshooting tips.