Lightpanda (lightpanda v0.3.1-rc.0)

Lightpanda is an installer and runner for the Lightpanda headless browser.

This package fetches binaries from the u2i fork build of Lightpanda, which carries an extra patch sending session cookies on the WebSocket upgrade request — required for cookie-authenticated WS endpoints (e.g. Phoenix LiveView). The release tag, download URL, and checksums are baked in; there are no knobs for swapping the source. If you need an unpatched upstream binary, depend on a different installer.

Configuration

Configure in your config/config.exs:

config :lightpanda,
  default: [
    args: ~w(serve --host 127.0.0.1 --port 9222)
  ]

Global options

:path - point at a locally-built binary on disk instead of the one this package downloads. Intended for developers working on the lightpanda fork itself who want to test rebuilds without republishing the package. Production users should leave this unset.

Profiles

Each profile accepts:

:args - arguments to pass to the lightpanda binary.
:cd - the working directory.
:env - environment variables as a map of string key/value pairs.

Summary

Functions

bin_path()

Returns the path to the Lightpanda binary.

detect_libc(opts \\ [])

Detects the host's libc flavor. Returns :musl if a musl dynamic linker is present in any of the probed directories (default /lib), otherwise :gnu.

ensure_installed!()

Ensures the Lightpanda binary is installed.

install()

Installs the Lightpanda binary by downloading it from the u2i fork release for the configured @release tag.

install_and_run(profile, extra_args)

Installs the binary if missing, then runs it with the given profile and extra arguments.

release()

Returns the release tag of the Lightpanda binary this package downloads.

run(profile, extra_args \\ [])

Runs the Lightpanda binary with the given profile and extra arguments.

target()

Returns the platform target string (e.g., "aarch64-macos", "x86_64-linux", "x86_64-linux-musl").

Functions

bin_path()

Returns the path to the Lightpanda binary.

By default this is _build/lightpanda-<target>. The :path config knob overrides it for developers running against a local sibling checkout of the lightpanda fork — see the module doc.

detect_libc(opts \\ [])

@spec detect_libc(keyword()) :: :gnu | :musl

Detects the host's libc flavor. Returns :musl if a musl dynamic linker is present in any of the probed directories (default /lib), otherwise :gnu.

Options

:libc_probe_dirs — list of directories to scan for an ld-musl-*.so.1 loader. Exposed for testing; production callers should pass no opts.

ensure_installed!()

Ensures the Lightpanda binary is installed.

Concurrent callers are deduplicated via an internal installer GenServer so that parallel install_and_run/2 invocations (or Lightpanda.Server startups) only download once.

install()

Installs the Lightpanda binary by downloading it from the u2i fork release for the configured @release tag.

install_and_run(profile, extra_args)

Installs the binary if missing, then runs it with the given profile and extra arguments.

Returns the exit status.

release()

Returns the release tag of the Lightpanda binary this package downloads.

run(profile, extra_args \\ [])

Runs the Lightpanda binary with the given profile and extra arguments.

target()

Returns the platform target string (e.g., "aarch64-macos", "x86_64-linux", "x86_64-linux-musl").

On Linux, the libc flavor is detected at runtime via detect_libc/1 so we pick the right release asset for glibc-based distros (Debian, Ubuntu, RHEL) vs musl-based ones (Alpine, distroless-static, Void).