Documentation menu

Deploying a WebKit Application

Keep the engine prefix, native ABI, assets, and session environment aligned with the application installed on the device.

A WebKit deployment includes more than a shared library next to the application. The bridge depends on a particular WPE installation, whose subprocess executables and resources must remain available at their configured prefix. Preparing that complete runtime first makes later page-loading failures easier to distinguish from Hera connection or scene problems.

Engine Build Prefix

The provided engine build installs WPE into an isolated prefix rather than replacing distribution libraries. Use the same prefix at build and deployment, because WebKit configures subprocess paths for that location. HERA_WPE_PREFIX lets the app-owned scripts discover the installation for pkg-config during native builds and shared-library lookup in the launcher; it does not rewrite embedded subprocess paths after the engine has been built.

The native bridge must match the target's architecture, libc, and WPE 2.0 ABI, and its runtime version check requires WPEWebKit 2.54 or newer. The package separately checks private bridge ABI 2 before creating a view. Deploying the Rust application and bridge together keeps both checks aligned.

Application Directory Layout

The browser expects its executable and libhera-wpe.so in one directory, with fonts.json and assets/ beside them. Its launcher belongs at scripts/run-pi.sh, resolving the application directory through its own location. The Rust build helper stages the manifest and assets into the release output, but the bridge and launcher still need to accompany the executable in your installed layout.

Native toolbar icons come from the application's registered font assets. Set HERA_FONT_REGISTRY on the daemon and relevant clients to matching manifests and identical bytes, and keep manifest-relative paths intact. HERA_FONT_PATH must also agree with the daemon when configuring the default native face. These settings affect Hera text; fonts rendered inside web content remain the engine's responsibility.

Desktop Session Environment

The client needs access to Hera's socket and the render-node/EGL facilities used for offscreen production. The launcher defaults HERA_SOCKET_PATH to /tmp/hera.sock and supplies XDG_RUNTIME_DIR from the user's session when it is absent. It reuses DBUS_SESSION_BUS_ADDRESS when available, otherwise owning a temporary bus through dbus-run-session.

The target also needs the matching WPE runtime dependencies, EGL and GLES libraries, xkbcommon, and D-Bus support. Run the browser as an unprivileged client in an existing Hera session; WebKit does not need ownership of Hera's display or a separate privileged browser service.

Diagnostic Export Options

Use the browser's --cpu option, or set HERA_WEBKIT_CPU=1 before creating a view, to force CPU export instead of the preferred DMA-BUF path. This setting affects the application's page buffers; it is independent of HERA_PRESENT_MODE, which selects Hera's final display presentation path.

HERA_WEBKIT_FULL_DAMAGE=1 is a separate comparison setting that forces full producer composition and full image damage. It can help identify a problem in partial-damage continuity without changing the export transport. The first-frame log reports DMA-BUF or CPU readback so you can confirm which path actually ran.

Browser Feature Scope

The current application provides the single-view navigation and input behavior described in the introduction. Applications that need downloads, popup windows, permission prompts, clipboard integration, touch, or IME must supply additional platform work and user-facing behavior. The package's engine handle alone does not establish those application policies.

For a deployment failure, start with verification and troubleshooting before changing buffer lifetime or weakening the production process environment.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • apps/browser/scripts/run-pi.sh
  • apps/browser/src/config.rs
  • crates/webkit/native/Dockerfile
  • crates/webkit/native/hera_wpe.cpp
  • crates/webkit/src/ffi.rs
  • apps/browser/fonts.json