Skip to content

electron: Overhaul *Sandbox permissions* section #578

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Mar 13, 2025
Merged

electron: Overhaul *Sandbox permissions* section #578

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8844319
electron: Overhaul section *Sandbox permissions*
salim-b Mar 12, 2025
22da78c
electron: More tweaks
salim-b Mar 12, 2025
94cf8ad
sandbox-permissions: Add explicit fragment id
salim-b Mar 12, 2025
3a5ace2
Update sandbox-permissions.rst
salim-b Mar 13, 2025
3847a68
Update electron.rst
salim-b Mar 13, 2025
f647d2c
Update docs/electron.rst
salim-b Mar 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 38 additions & 26 deletions docs/electron.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ manifest:
base: org.electronjs.Electron2.BaseApp
base-version: '23.08'

BaseApps are described in :doc:`dependencies`. Using the Electron base
BaseApps are described in :doc:`dependencies`. Using the Electron base
app is much faster and more convenient than manually building Electron
dependencies. It also has the advantage of reducing the amount of duplication
on users' machines, since it means that Electron is only saved once on disk.
Expand Down Expand Up @@ -103,14 +103,14 @@ later.
Sandbox permissions
-------------------

The standard guidelines on sandbox permissions apply to Electron
applications. However, Electron does not use Wayland by default. So for
display access, only X11 should be used as the default configuration.
This will make Electron use Xwayland in a wayland session and nothing
else is required.
The standard sandbox :ref:`sandbox-permissions:Permissions guidelines` also
apply to Electron applications. However, Electron's Wayland support is still
experimental. So for display access, only X11 should be used as the default
configuration. This will make Electron use Xwayland in a Wayland session and
nothing else is required.

The sample app also configures pulseaudio for sound and enables network
access.
The sample app also configures PulseAudio for sound and enables network
access:

.. code-block:: yaml

Expand All @@ -122,36 +122,48 @@ access.
- --share=network
- --env=ELECTRON_TRASH=gio

.. note::

Native wayland support in electron is experimental and often unstable.
It is advised to stick with the X11 and Xwayland configuration above
as the default.

To enable experimental `native Wayland` support in Electron>=20, the
To allow experimental `native Wayland` support in Electron>=20, the
``--ozone-platform-hint=auto`` flag can be passed to the program. `auto`
will choose Wayland when the session is wayland and Xwayland or X11
otherwise.
will choose Wayland when the current session is running under Wayland and
Xwayland or X11 otherwise.

The recommended option is to leave it to the user. So ``--socket=x11``
should be used in manifest and Wayland can be tested with::
It's recommended to leave actually `enabling` Wayland up to the user for now,
i.e. set ``--socket=x11`` in the manifest. Wayland can then be tested with::

flatpak run --socket=wayland org.flathub.electron-sample-app

To make native wayland the `default` for users ``--socket=fallback-x11``
Enable native Wayland support by default
````````````````````````````````````````

.. note::

Native Wayland support in Electron is still experimental and often unstable.
It is advised to stick with the X11/Xwayland configuration above as the
default.

To make native Wayland the `default` for users, ``--socket=fallback-x11``
and ``--socket=wayland`` must be used in the manifest.

For Electron versions between 17 and 27, client-side window decorations in native wayland can be enabled by
passing ``--enable-features=WaylandWindowDecorations``.
For Electron versions between 17 and 27, client-side window decorations under
native Wayland can be enabled by passing
``--enable-features=WaylandWindowDecorations`` to the program. For newer
versions of Electron , this isn't necessary anymore.

Electron uses ``libnotify`` on Linux to provide desktop notifications.
libnotify `since 0.8.0 <https://gitlab.gnome.org/GNOME/libnotify/-/merge_requests/27>`_
`Since version 0.8.0 <https://gitlab.gnome.org/GNOME/libnotify/-/merge_requests/27>`_ libnotify
automatically uses the `notification portal <https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Notification.html>`_
when inside a sandboxed environment and ``--talk-name=org.freedesktop.Notifications``
is not required.
is not required anymore. ``org.electronjs.Electron2.BaseApp`` includes
``libnotify>=0.8.0`` since ``branch/23.08``.

To ensure proper mouse cursor scaling on HiDPI displays under Wayland, the
``XCURSOR_PATH`` environment variable must be set to the host's corresponding
directories:

``org.electronjs.Electron2.BaseApp`` since ``branch/23.08`` comes with
``libnotify>=0.8.0``
.. code-block:: yaml

finish-args:
- --env=XCURSOR_PATH=/run/host/user-share/icons:/run/host/share/icons

.. _use-correct-desktop-filename:

Expand Down