Standard installation on Linux

This guide covers Linux releases supplied with install.sh and signed, architecture-specific .tar.gz packages. Obtain the release from your Wallboard server or administrator.

Before you start

• Use a 64-bit Linux system with glibc: AMD64 (x86_64) for Intel/AMD PCs or ARM64 (aarch64) for devices such as Raspberry Pi. A 64-bit processor running a 32-bit operating system is not sufficient.
• Have systemd, Bash, Python 3, OpenSSL, and administrator access available. A non-root user needs sudo. Installing directly from a server also requires curl.
• Install the operating system's graphics drivers. You can run the installer locally or over SSH. For the initial automatic kiosk setup, a user must already be logged in to an active local X11 or Wayland desktop session, which the installer uses for graphical setup.
• Connect the device to the network and confirm the address of the Wallboard server you will use for registration.
• Allow space for the downloaded package, temporary extraction, installed application, and downloaded content.

The installer checks the host's libraries against the selected release. For example, a release may report This build requires glibc >= 2.34 and GLIBCXX >= 3.4.29. This line describes the package requirements; installation fails only if a subsequent check finds that the host does not meet them. The required versions can change between releases.

The installer can install missing dependencies using the package manager on Debian/Ubuntu, RHEL/Fedora, SUSE, and Arch systems. This does not guarantee compatibility with every distribution, graphics driver, or device. Check your intended hardware and operating system with your Wallboard provider before deployment.

Kiosk setup is enabled by default

Save your work before installing. On Wayland, installation switches the device to a dedicated Wallboard kiosk session after the installer exits, which can end the current desktop session. For a desktop installation without kiosk setup, add --desktop to the installation command.

Install from your Wallboard server

curl is required on the device

curl must be installed on the Linux device before you run the installation command below, whether you use a local terminal or SSH.

Use this method if your server publishes an active Linux release. If the installer URL is unavailable, ask your administrator for a Linux installation package and use Install from a ZIP package.

1. In the Wallboard interface, open Settings → Downloads and find the Linux card.
2. Click the card's Copy URL icon. In the copy window, change Format from Link to Curl command, then click Copy. The command already contains the address of your current Wallboard server.
3. Open a terminal on the Linux device, or connect to the device over SSH if SSH access is already configured. Paste the copied command and press Enter.
4. Enter your administrator password when requested.
5. Wait for the installer to download the package for your architecture, verify its signature and contents, and configure the player. After a successful installation, the player starts automatically.

If your interface does not offer Curl command, use this single command instead. Replace the example server address in both places:

curl -fsSL 'https://your-wallboard-server.example/api/storage/update/jscore/linux/install.sh' | bash -s -- --server-url='https://your-wallboard-server.example/' --no-pause-on-success

Use the installer supplied by your trusted Wallboard server over HTTPS. The command runs it with Bash, rather than sh, and does not require a separate variable or a manually saved installer file.

The server address is used for the first device registration. Reinstalling does not change an existing device registration or move the device to another server. To move a registered device, follow Move a device to another server.

Install from a ZIP package

1. Obtain the Linux installation ZIP from Settings → Downloads on a server that offers the Linux client, or from your administrator.

2. Extract the ZIP into one directory. The release contains:

   install.sh
   linux-client_amd64.tar.gz
   linux-client_arm64.tar.gz
   version.txt

3. Open a terminal in that directory and run:

   bash install.sh --server-url "https://your-wallboard-server.example"

4. Enter your administrator password when requested, then wait for installation to complete. Press Enter if prompted.

The installer automatically selects the correct architecture. Keep install.sh and the archives from the same release together; do not extract the .tar.gz files manually. If the matching archive is present, it is verified and used without downloading another copy. An invalid local archive is rejected rather than replaced automatically.

Package installation can work offline if all required system dependencies are already installed. Downloading missing dependencies, registering the device, and receiving content require access to the relevant services.

To check the package before installing it:

bash install.sh --verify-only

This checks the selected archive's signature and file integrity without installing it. It does not test graphics compatibility or application startup.

Installation options

Check the options supported by your downloaded release:

bash install.sh --help

Option	What it does
--kiosk	Explicitly selects the default kiosk setup: desktop locking on X11 or a dedicated kiosk session on Wayland.
--desktop	Installs without preparing kiosk locking. Unprovision an existing dedicated kiosk first, as described in Return to the desktop.
--server-url URL or --server-url=URL	Sets the server for first registration. If the matching archive is missing beside the installer, downloads it from that server. Preserves an existing registration.
--verify-only	Checks the matching archive's signature, files, and version, then exits without installing or requesting administrator rights. Verification tools are still required; use --server-url if the archive needs to be downloaded.
--no-pause-on-success	Skips the final Enter prompt after success. Interactive failures remain visible until Enter is pressed.
--no-pause	Skips the final Enter prompt after both success and failure.
--pause	Enables the final Enter prompt in an interactive terminal.
--no-color	Disables terminal colors. The NO_COLOR environment variable is also supported.
--sudo-password-stdin	Lets sudo read its password from standard input when elevation is needed. Use a saved install.sh, rather than streaming the script through curl. Do not put passwords in command arguments. Ignored when already running as root.
-h, --help	Displays the available options and exits.
graphical-user	Optional username appended to the command to select an existing graphical user. That user must have an active local X11 or Wayland session; the installer does not create or log in to a desktop session.

Choose either --kiosk or --desktop. If neither is supplied, kiosk setup is enabled. In an interactive terminal, the installer normally waits for Enter before starting the player.

For example, install without kiosk setup and start the player without a final prompt after success:

bash install.sh --desktop --server-url "https://your-wallboard-server.example" --no-pause-on-success

For installation using the copied curl command, append options such as --desktop after the existing installer arguments at the end of the command. The --sudo-password-stdin option requires downloading the script to a file first.

Start install.sh from the file manager

Behavior varies between desktop environments

Starting install.sh by clicking it can work differently depending on your desktop environment, file manager, and their settings. The available actions and permission options may have different names, and some file managers open scripts in a text editor instead of running them. If no suitable launch option is available, use the terminal command above.

You can also start install.sh by clicking it in a file manager that supports running shell scripts. Open the extracted package directory, double-click install.sh, and choose Run in Terminal if prompted. Some file managers offer Run in Terminal in the file's right-click menu instead.

If needed, open the file's Properties → Permissions and allow it to execute as a program. If clicking opens a text editor or your file manager does not offer script execution, use the terminal command above. Keep the matching .tar.gz archive beside install.sh.

When starting this way, enter your Wallboard server address in the application if prompted. Enter your administrator password in the installer terminal and press Enter when installation finishes.

Register the device

For a new device, the player uses the server address supplied to the installer. If prompted for a server address, enter your Wallboard server. When the four-digit activation code appears, use it to add the device in the Wallboard interface.

Follow Device registration to complete registration and assign the device to your customer. Reinstalling over an existing installation preserves its registration.

Startup and kiosk mode

The default installation configures kiosk behavior according to the active display session:

Display session	Default installation behavior
X11	Runs the player in the selected user's desktop session and prepares desktop locking. The graphical user must be logged in for playback. Configure desktop auto-login separately if the device must start playback without a manual login after boot.
Wayland	Sets up a dedicated Wallboard kiosk session and configures it to start at boot. The transition happens after the installer exits.

For an installation that uses the normal desktop without preparing kiosk locking:

bash install.sh --desktop --server-url "https://your-wallboard-server.example"

This mode also needs a local graphical login. A Lock command cannot enforce kiosk restrictions on a device that was not prepared for kiosk mode.

To select a particular graphical user when automatic selection is ambiguous, append the username:

bash install.sh --server-url "https://your-wallboard-server.example" myuser

That user must have an active local X11 or Wayland session. Naming a user does not create or log in to a desktop session.

Return to the desktop

To remove kiosk provisioning while keeping the application installed, run the following from SSH or a text console:

sudo wallboard-player-configure --unprovision

This restores the saved desktop configuration and can interrupt playback. An existing dedicated kiosk must be unprovisioned before changing it to a --desktop installation.

Updates and removal

Use Wallboard's device update management for normal application updates. The updater checks the signing key, architecture, build mode, and compatibility with the installed updater. If it requests an installer upgrade or reports an incompatible baseline, rerun the appropriate full installation package. An application update alone cannot prepare an unconfigured device for kiosk mode.

If an update fails signature or compatibility checks, obtain the appropriate package from your administrator. Do not disable verification or delete update state files to force installation. You do not need to uninstall the player before a normal update or a full installer rerun.

Remove the application

To remove the application while keeping its registration and downloaded content:

wallboard-uninstall --keep-data

Use SSH or a text console if the dedicated kiosk is active. The uninstaller requests administrator rights and confirmation. Using --purge-data instead also removes the device's registration and content, so the device will need to be registered again. If removal reports an error, keep the displayed log and contact support before reinstalling.

Removal options

Check the options supported by the uninstaller installed on your device:

wallboard-uninstall --help

Option	What it does
--keep-data	Keeps local device registration, certificates, logs, and downloaded content for a later installation.
--purge-data	Deletes local device data as well as removing the application. A later installation must be registered as a new device.
--yes, -y	Skips the final removal confirmation. Does not select whether to delete data or bypass administrator authentication.
--no-pause	Skips the final Enter prompt after removal succeeds or fails.
--pause	Enables the final Enter prompt in an interactive terminal.
--no-color	Disables terminal colors. The NO_COLOR environment variable is also supported.
-h, --help	Displays the available options and exits.

Choose either --keep-data or --purge-data. Without either option, interactive removal asks whether to delete existing device data, with No as the default; noninteractive removal keeps the data. The separate data question can still appear with --yes, so always select a data option when scripting removal.

To remove the player while preserving its data, without removal confirmation or a final Enter prompt:

sudo wallboard-uninstall --keep-data --yes --no-pause

To remove the player and delete its local registration and content:

sudo wallboard-uninstall --purge-data --yes --no-pause

Administrator authentication may still be required. Neither --yes nor --no-pause suppresses a sudo password prompt.

Troubleshooting

Symptom	What to check
Installer URL returns an error or is not available	Confirm the server address and ask the administrator whether a Linux release is available and activated. Use its matching ZIP package if needed.
No active graphical user is found	Log in locally to an X11 or Wayland desktop. With multiple users, specify the intended active user's name.
Host glibc or GLIBCXX is too old	Use a compatible operating system or a release approved for that system. Do not replace individual system libraries manually.
Archive signature, version, or architecture verification fails	Obtain a complete matching release. A new install.sh with an older local archive will not work.
The player has not opened after a successful installation	Finish any final Enter prompt first; startup is deferred until the installer exits. In desktop/X11 mode, confirm that the graphical user is still logged in.
The screen stays black or returns to the login screen	Collect the installer and service logs below. Check the graphics driver and kiosk startup error with support.
Lock reports that the device was not set up as kiosk	The installed application is missing successful kiosk provisioning. An application update alone does not add it. Check how the device was installed and any installer error before repeating the setup.

After installation has obtained administrator rights, it prints the detailed log's path, such as /var/log/wallboard-install.ABCDEFGH.log. Use that exact path to inspect a failed step.

Collect startup logs with:

sudo journalctl -b \
  -u wallboard-player.service \
  -u wallboard-kiosk-wayland.service \
  -u wallboard-kiosk-x11.service \
  --no-pager

Include the client version, operating system, architecture, installation method, and exact error when contacting support.