Repository navigation
Migrate the browser block from X11 to Wayland (v3) - #207
Merged
Merged
Conversation
The block no longer starts its own X server. Chromium runs with
--ozone-platform=wayland against the socket that a companion display
(compositor) block exposes on a shared /run volume.
- Replace the X11 packages and the startx/Xwrapper setup with the Mesa
GL/GBM/VA-API drivers
- Map the host GIDs of /dev/dri, /dev/video* and /dev/snd/* into the
container so the unprivileged chromium user can use the GPU, V4L2
video decode and ALSA
- ENABLE_GPU now enables GPU rendering and best-effort hardware video
decode; DISABLE_VIDEO_DECODE opts out of decode
- Add /diagnostics/{version,gpu,media} endpoints, gated behind
ENABLE_DIAGNOSTICS (off by default)
- Take /screenshot through the DevTools protocol instead of scrot
- Move to debian:13.2-slim and chrome-launcher 1.x
Change-type: major
Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
Change-type: patch Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
Drop fincm3 and 32-bit raspberrypi3, add generic-amd64 and generic-aarch64, make raspberrypi4-64 the default device type, and publish a raspberrypi3-64 block. Change-type: major Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
Chromium binds its DevTools endpoint to localhost only and ignores --remote-debugging-address outside headless mode, so mapping the port never made it reachable from another host. With ENABLE_REMOTE_DEBUG=1 a small TCP relay forwards REMOTE_DEBUG_PORT to Chromium. The relay adds no authentication or encryption. Change-type: minor Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
Chromium's Vulkan backend does not work with the Ozone Wayland platform. The options for bringing it back after v3 are recorded in docs/todo-vulkan-wayland.md. Change-type: major Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
/diagnostics/report returns a single text file with device and host info, runtime config, Chromium GPU and media state, and recent block and Chromium logs, for attaching to bug reports. Diagnostics move into src/diagnostics.js. Change-type: minor Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
Delete startx.sh and the unused X.org config for the Raspberry Pi 5. ROTATE_DISPLAY, ROTATE_DELAY, TOUCHSCREEN, WINDOW_SIZE, WINDOW_POSITION, SHOW_CURSOR and DISPLAY_NUM no longer exist; rotation and resolution are now configured on the display block. The migration guide maps the old variables to the new ones. Change-type: major Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
The image no longer installs the PulseAudio ALSA bridge or sets PULSE_SERVER. HDMI and the 3.5mm jack work with no extra container. The migration guide shows how to add the audio block back in a derived image. Change-type: major Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
The display block deletes and recreates the Wayland socket on every restart, which left Chromium disconnected. start.sh now supervises the session and relaunches it when the socket's inode changes. Change-type: patch Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
mesa-va-drivers only provides VA-API for AMD/gallium, so on Intel devices libva exposed zero decode profiles and Chromium fell back to software for every codec. Install Intel's own VA driver (intel-media-va-driver for Gen8+, i965-va-driver for older parts) on amd64; libva auto-selects the right one per GPU. Also bundle vainfo and surface its output in the diagnostics report (plus a /diagnostics/vainfo endpoint) so VA profiles can be inspected directly. Verified on i3-7100U (Kaby Lake): H.264 and HEVC now decode via VaapiVideoDecoder (hardware: true). Change-type: minor Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
Change-type: patch Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
Use bh.cr/balenasolutions for v3 image references, update the balena.yml usage snippet for the display block, point the repository, logo and package.json URLs at balenasolutions/browser, and drop the balenalabs name from the default landing page. Change-type: patch Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
rahul-thakoor
force-pushed
the
v3-dev/wayland-migration
branch
from
October 1, 2026 13:41
46f2d6d to
036f235
Compare
Change-type: patch Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
rahul-thakoor
requested review from
alanb128,
chrisys,
samuel-duffield1 and
shaunmulligan
October 1, 2026 14:28
start.sh printed the VERSION file but never exported it, so server.js had nothing to serve on /version or in the diagnostics report. Change-type: patch Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
Add an endpoint overview, group endpoints, and correct /gpu and /kiosk to POST. Change-type: patch Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
Change-type: patch Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
Lay out the browser block horizontally and highlight it, mute the other groups, and give every node explicit colours so it reads in dark mode. Use consistent two-line group titles, label the V4L2 path as H.264 decode on Pi 3/4 only, and show the Wayland socket without its configurable path. Change-type: patch Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
rahul-thakoor
marked this pull request as ready for review
October 6, 2026 01:46
FLAGS replaces the whole flag set, which also dropped --ozone-platform=wayland. Chromium then fell back to X11, exited with "Missing X server or $DISPLAY", and the block failed with ECONNREFUSED on the debug port and restarted in a loop. Add the Wayland flag unless FLAGS sets its own --ozone-platform, and document that FLAGS replaces the kiosk defaults so additive flags belong in EXTRA_FLAGS. Change-type: patch Signed-off-by: rahul-thakoor <13220877+rahul-thakoor@users.noreply.github.com>
alanb128
approved these changes
Oct 8, 2026
alanb128
left a comment
alanb128
left a comment
Contributor
There was a problem hiding this comment.
Docs and README look good!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
v3 of the browser block. Chromium now runs as a Wayland client instead of starting its own X server. It renders through a companion display (compositor) block that shares the Wayland socket on a
/runvolume. This is a breaking release; the full upgrade path is indocs/migrating-from-v2.md.Breaking changes
displayservice (bh.cr/balenasolutions/display-<arch>), share a volume at/run, and setXDG_RUNTIME_DIR/WAYLAND_DISPLAYonbrowser.bh.cr/balenasolutions:browser-raspberrypi3-64,browser-raspberrypi4-64,browser-raspberrypi5,browser-generic-aarch64andbrowser-generic-amd64.fincm3, 32-bitraspberrypi3,arm32images.ROTATE_DISPLAY,ROTATE_DELAY,TOUCHSCREEN,WINDOW_SIZE,WINDOW_POSITION,SHOW_CURSORandDISPLAY_NUM. Rotation and resolution are now set on the display block (DISPLAY_ROTATION/DISPLAY_RESOLUTION/DISPLAY_SCALE).FORCE_VULKAN. Chromium's Vulkan backend doesn't work with Ozone Wayland; seedocs/todo-vulkan-wayland.md.FLAGS/EXTRA_FLAGSthat use X11-only switches need review.New
ENABLE_GPU=1turns on GPU rendering plus best-effort hardware video decode (V4L2 on Raspberry Pi; VA-API on x86, including Intel's iHD/i965 drivers).DISABLE_VIDEO_DECODE=1turns decode off and keeps GPU rendering./diagnostics/*endpoints (ENABLE_DIAGNOSTICS=1):version,gpu,media,vainfo, andreport, a single text bundle to attach to bug reports.ENABLE_REMOTE_DEBUG=1). It has no authentication, so only use it on trusted networks./screenshotuses the DevTools protocol and works under Wayland.balena.ymlusage snippet, repository/logo URLs,package.jsonand the default landing page now point atbalenasolutions.Tested on
Raspberry Pi 3 (64-bit): H.264 hardware decode
pi3-64-balena browser-block diagnost.txt
Raspberry Pi 4 : with touchscreen
browser-block-raspberrypi4-64-balenaOS_7.4.0-diagnostics-2026-10-06T115617Z.txt
Raspberry Pi 5: GPU rendering (H.264 falls back to software decode)
browser-block-raspberrypi5-balenaOS_8.0.9_rev1-diagnostics-2026-10-06T123653Z.txt
generic-amd64 (Intel i3-7100U): H.264/HEVC through
VaapiVideoDecoderbrowser-block-generic-amd64-balenaOS_6.9.2-diagnostics-2026-10-06T112521Z.txt
browser-block-generic-amd64-balenaOS_8.0.9_rev2-diagnostics-2026-10-06T113658Z.txt