143 lines
No EOL
7 KiB
Markdown
143 lines
No EOL
7 KiB
Markdown
# 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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
chmod +x setup-kiosk.sh
|
|
```
|
|
|
|
3. **Run as root:**
|
|
```bash
|
|
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:
|
|
```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.
|
|
|
|
6. **Reboot:**
|
|
```bash
|
|
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:**
|
|
```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. |