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.