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

Update README.md to reflect changes in kiosk setup script, including Sway usage, configuration details, and troubleshooting steps

Browse source
This commit is contained in:
FallingLights 2025-05-07 20:05:44 +02:00
parent 684b51d7c2
commit 0435a933b3
1 changed files with 124 additions and 55 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

179
README.md
View file

@ -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 ## Features
* Automated installation and configuration on a base Alpine Linux system. * **Minimal Base:** Leverages Alpine Linux for a small footprint.
* Uses the modern Wayland display protocol via the Weston compositor. * **Wayland Native:** Uses Sway for a modern display server environment.
* Employs `elogind` for session and seat management. * **Chromium Kiosk:** Launches Chromium in full-screen kiosk mode.
* Uses `greetd` with `agreety` for lightweight, automatic user login. * **Autologin:** Uses `greetd` with `agreety` to automatically log in the signage user and start Sway.
* Configurable target URL displayed in Chromium's kiosk mode. * **Remote Access:** Includes WayVNC for remote desktop access to the kiosk session (password configuration required for security).
* Includes basic Mesa graphics drivers and essential firmware. * **VM Friendly:** Includes `open-vm-tools` for better integration when run in VMware.
* Checks for the problematic `nomodeset` kernel parameter. * **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). * A fresh installation of Alpine Linux (standard or extended).
2. **Configure:** * Internet connectivity during the script execution to download packages.
* Edit the script using a text editor (like `nano`): `nano setup_signage.sh` * The script must be run as the `root` user.
* 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`
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. ## Usage
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`).
## 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`. 5. **Change WayVNC Password:**
* **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`. 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. * 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).
2. **Login as Root:** Use the root username and password. * You will be prompted for the `WAYVNC_PASSWORD` you set in `/home/<SIGNAGE_USER>/.profile`.
3. **Check Logs & Status:**
* **Greetd:** `cat /var/log/messages | grep greetd` (Look for errors starting or running greetd) ### Troubleshooting
* **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------`) The script provides a list of troubleshooting steps at the end of its execution. Key logs and checks include:
* **Services:** `rc-service elogind status && rc-service dbus status` (Both should be started)
* **inittab:** `grep ^tty1 /etc/inittab` (Should show `/usr/sbin/greetd`) * **Greetd logs:** `grep greetd /var/log/messages | tail -n 20`
* **Kernel Messages:** `dmesg | tail -n 50` (Look for graphics/DRM driver errors, especially if you suspect `nomodeset` issues) * **Sway log:** `cat /home/<SIGNAGE_USER>/.local/share/sway/sway-greetd.log` (replace `<SIGNAGE_USER>` with your chosen user)
* **Greetd Config:** `cat /etc/greetd/config.toml` (Verify syntax, command path, user) * **Sway config syntax check:**
* **Weston Config:** `cat /home/signage/.config/weston.ini` (Verify syntax, client path, Chromium flags) ```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.