From 0435a933b32679eaf78ae521f2d8ec1d3d4641ce Mon Sep 17 00:00:00 2001 From: FallingLights <fallinglights@nop.si> Date: Wed, 7 May 2025 20:05:44 +0200 Subject: [PATCH] Update README.md to reflect changes in kiosk setup script, including Sway usage, configuration details, and troubleshooting steps --- README.md | 179 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 124 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 6608e12..38ab19d 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,143 @@ -# Alpine Linux Weston/Chromium Kiosk Setup +# Alpine Linux Kiosk Setup Script -This script automates the setup of a minimal Alpine Linux system to function as a digital signage kiosk. It installs and configures Weston (a Wayland compositor), Chromium (web browser), and necessary supporting services to automatically display a specific webpage in fullscreen kiosk mode upon system boot. +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 -* Automated installation and configuration on a base Alpine Linux system. -* Uses the modern Wayland display protocol via the Weston compositor. -* Employs `elogind` for session and seat management. -* Uses `greetd` with `agreety` for lightweight, automatic user login. -* Configurable target URL displayed in Chromium's kiosk mode. -* Includes basic Mesa graphics drivers and essential firmware. -* Checks for the problematic `nomodeset` kernel parameter. +* **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. -## How to Use +## Prerequisites -1. **Download/Save Script:** Obtain the `setup_signage.sh` script and place it on your target Alpine machine (e.g., using `wget`, `scp`, or copy-paste via SSH). -2. **Configure:** - * Edit the script using a text editor (like `nano`): `nano setup_signage.sh` - * Modify the following variables near the top of the script: - * `KIOSK_URL`: Set this to the full URL of the webpage you want to display (e.g., `"https://your-status-board.com"`). - * `SIGNAGE_USER`: You can change the username if desired, but `"signage"` is standard for this setup. - * Save the changes (`Ctrl+O`, `Enter` in nano) and exit (`Ctrl+X`). -3. **Make Executable:** `chmod +x setup_signage.sh` -4. **Run as Root:** `./setup_signage.sh` -5. **Review Output:** Watch the script output for any errors. Pay attention to any warnings, especially regarding `nomodeset`. -6. **Reboot:** If the script completes successfully, reboot the system: `reboot` +* 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. -Upon rebooting, the system should automatically log in as the `signage` user and launch Weston with Chromium displaying the configured `KIOSK_URL`. +## Configuration -## How It Works (Technical Details) +Before running the script, you can adjust the following variables at the top of the `setup-kiosk.sh` file: -The script performs the following main steps: +* `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"`) -1. Checks for root privileges. -2. Checks `/proc/cmdline` for the `nomodeset` kernel parameter and issues a warning if found (as this prevents Weston's DRM backend from working). -3. Updates Alpine package repositories (`apk update`). -4. Runs `setup-wayland-base` to install and configure `elogind`, `eudev`, enable the community repository, and set up related services. -5. Installs core packages: `weston`, `weston-backend-drm`, `weston-shell-desktop`, `chromium`, `mesa-dri-gallium`, `mesa-va-gallium`, `dbus`, fonts, `util-linux` (for dependencies), `linux-firmware`, `greetd`, `greetd-agreety`. -6. Ensures the `dbus` service is enabled and started. -7. Creates the non-root user (`signage` by default) with `/bin/sh` as the shell. -8. Creates Weston configuration (`~/.config/weston.ini`) setting `idle-time=0` (no screen blanking) and specifying Chromium as the client, ensuring the `--ozone-platform=wayland` flag is used. -9. Creates `greetd` configuration (`/etc/greetd/config.toml`) to use `agreety` on VT1, perform autologin for the `signage` user, and set the session command to `/usr/bin/weston`. -10. Modifies `/etc/inittab` to start `/usr/sbin/greetd` on tty1 instead of the default getty/login prompt. -11. Attempts to add `pam_elogind.so` to the PAM configuration (`/etc/pam.d/greetd` or `/etc/pam.d/system-auth`) to ensure `elogind` handles session setup correctly (including `$XDG_RUNTIME_DIR`). +## Usage -## IMPORTANT: `nomodeset` Boot Parameter +1. **Download the script:** + ```bash + wget -O setup-kiosk.sh <URL_TO_YOUR_SCRIPT_RAW_FILE> + # or copy the script content into a file named setup-kiosk.sh + ``` -Weston requires Kernel Mode Setting (KMS) graphics drivers to function with its primary (`drm`) backend. The kernel parameter `nomodeset` **disables** KMS drivers. +2. **Make it executable:** + ```bash + chmod +x setup-kiosk.sh + ``` -**If the setup script warned you about `nomodeset` being present, the graphical kiosk WILL NOT WORK.** +3. **Run as root:** + ```bash + sudo ./setup-kiosk.sh + # or if already root: + # ./setup-kiosk.sh + ``` -You **MUST** remove `nomodeset` from your kernel boot arguments. Edit your bootloader configuration file: +4. **Follow Prompts/Review Output:** The script will output its progress. Pay attention to any warnings, especially regarding `nomodeset` or WayVNC password. -* **Syslinux/Extlinux:** Edit `/boot/extlinux.conf`. Find the line(s) starting with `APPEND` and delete the word `nomodeset`. -* **GRUB:** Edit `/etc/default/grub`. Find the line(s) starting with `GRUB_CMDLINE_LINUX_DEFAULT=` and `GRUB_CMDLINE_LINUX=` and delete the word `nomodeset` from within the quotes. After saving, run `update-grub`. +5. **Change WayVNC Password:** + Edit the signage user's profile: + ```bash + # Replace 'signage' if you changed SIGNAGE_USER + vi /home/signage/.profile + ``` + Uncomment and set the `WAYVNC_PASSWORD` variable: + ```profile + export WAYVNC_PASSWORD="your_very_secure_password_here" + ``` + Save the file. -Reboot after modifying the bootloader configuration. +6. **Reboot:** + ```bash + reboot + ``` + The system should automatically log in and launch the kiosk. -## Troubleshooting +## Post-Installation -If the kiosk doesn't start correctly after rebooting: +### Remote Access (VNC) -1. **Switch TTY:** Press `Alt+F2` (or `F3`, `F4`, etc.) to get to another virtual console login prompt. -2. **Login as Root:** Use the root username and password. -3. **Check Logs & Status:** - * **Greetd:** `cat /var/log/messages | grep greetd` (Look for errors starting or running greetd) - * **Weston:** `cat /home/signage/.local/share/weston/weston.log` (Look for DRM errors, GL errors, client launch errors) - * **XDG Runtime Dir:** `ls -ld /run/user/$(id -u signage)` (Should exist, owned by `signage`, permissions `drwx------`) - * **Services:** `rc-service elogind status && rc-service dbus status` (Both should be started) - * **inittab:** `grep ^tty1 /etc/inittab` (Should show `/usr/sbin/greetd`) - * **Kernel Messages:** `dmesg | tail -n 50` (Look for graphics/DRM driver errors, especially if you suspect `nomodeset` issues) - * **Greetd Config:** `cat /etc/greetd/config.toml` (Verify syntax, command path, user) - * **Weston Config:** `cat /home/signage/.config/weston.ini` (Verify syntax, client path, Chromium flags) \ No newline at end of file +* 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:** + ```bash + # 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):** + ```bash + # 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: + ```bash + # 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. \ No newline at end of file