Sway: Difference between revisions

From Alpine Linux
m (fix wording)
m (added note about testing repository)
 
(62 intermediate revisions by 4 users not shown)
Line 1: Line 1:
Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.
[https://swaywm.org Sway] is a tiling [[Wayland]] compositor and a drop-in replacement for the [[i3wm |i3 window manager]]. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.


== Add a normal user ==
{{:Include:Setup-desktop}}
Install appropriate [[#Install Graphics Drivers|video]] drivers for your hardware before you can [[#Starting sway|launch sway]]. Without  graphics drivers [[#Video Driver Issues|errors]] may occur.


Use <code>setup-user</code> to add a non-system normal user for running Sway.
== Manual Installation ==


== Set up eudev ==
The below installation step allows you to pick and choose various componenents for your Sway Desktop.


[[eudev]] is recommended and required for. Without it, sway cannot connect to input devices.
=== Add a normal user ===


setup-devd udev
Use <code>setup-user</code> to add a non-system normal user for running Sway.
{{cmd|# setup-user}}


== Install Graphics Drivers ==
=== Set up eudev ===
{{:Include:Setup Device Manager}}


Graphics drivers:
=== Install Graphics Drivers ===


* [[Intel Video]]
Install [[graphics driver]] for your video hardware. Without proper driver, Sway will fail to start.
* [[Radeon Video]]
* [[Nvidia Video]]


== Install seatd ==
=== Setup up a seat manager ===


Install seatd, a minimal seat management daemon. This grants the required permissions to the user running sway:
Wayland compositors need raw access to input and output devices. This is mediated by a [[seat manager]].  


apk add seatd
Configure either [[seatd]] or [[elogind]] as both are supported. However using both may lead to conflicts.


# add seatd to boot run-level, because it must be running before greetd
=== Install fonts ===
# else greetd will fail to start
rc-update add seatd boot


rc-service seatd start
Install DejaVu fonts, which has good Unicode coverage:
  adduser $USER seat
{{cmd|# apk add font-dejavu}} 
   
=== Install Sway ===


== Install elogind (optional) ==
{{cmd|# apk add sway \
 
    xwayland            \ # if you need xserver
<code>swayidle</code> has integration with <code>elogind</code> and can handle <code>before-sleep</code> events.
    foot                \ # default terminal emulator. Modify $term in config for a different one.
 
    wmenu                \ # default wayland native menu for choosing program and screensharing monitor
apk add elogind
    swaylock swaylockd  \ # lockscreen tool
rc-update add elogind
    swaybg              \ # display wallpaper
rc-service elogind start
    grim                \ # screenshot tool
 
    wl-clipboard        \ # clipboard management
If using <code>swayidle before-sleep</code>, there will be a race condition, so that when you resume the computer from suspend, the screen shows the contents of the unlocked screen for a second before showing the actual lock screen.  This can be a privacy concern, if someone is filming the screen.
    i3status            \ # simple status bar
To solve this issue, do the following:
    swayidle               # idle management (DPMS) daemon
}}


Create this file <code>/etc/elogind/system-sleep/10-swaylock.sh</code>, then add the following script to this file:
For complimentary software alternatives, see [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway sway wiki] or [https://wiki.gentoo.org/wiki/List_of_software_for_Wayland Gentoo Wiki.]


#!/bin/sh
== Starting sway ==
if [ "${1}" == "pre" ]; then
  touch /tmp/swaylock-sleep
  sleep 1
fi


Then set it to executable.
=== Manually launch sway ===


Later, once sway is installed, add the following line to sway config:
You can launch <Code>sway</Code> by issuing the command sway from TTY. {{Cmd|$ sway}}


# in ~/.config/sway/config
=== Automatically launch sway on TTY login ===
  exec sh -c "touch /tmp/swaylock-sleep; inotifyd swaylock /tmp/swaylock-sleep"


With this line, the screen will be promptly locked before suspend-to-RAM starts.
{{Note|[[D-Bus]] is required for PipeWire and screensharing in Firefox and Chromium. Running with <code>dbus-run-session</code> is a convenience wrapper that will explicitly export the path of the session bus.}}


== Install greetd (optional) ==
Adding the following lines to your {{Path|~/.profile}} will launch Sway automatically with [[D-Bus]] only in tty1 {{Cat| ~/.profile|<nowiki>export XDG_VTNR=$(basename "$(tty)" | sed 's/tty//')
if [ -z "$WAYLAND_DISPLAY" ] && [ "$XDG_VTNR" -eq 1 ]; then
    exec dbus-run-session sway
fi</nowiki>}}


{{Box YELLOW|Note:|This content is tangential, and should be moved into the 'greetd' page}}
=== Use Wrapper script to launch sway ===


apk add greetd greetd-gtkgreet cage greetd-openrc
Instead of using {{Path|~.profile}} for environment variables, a wrapper script <Code>sway-run</Code> can be used to launch <Code>sway</Code> from both TTY and [[greetd]], a lightweight [[Display manager|display manager]]. Here is a [https://man.sr.ht/~kennylevinsen/greetd/#how-to-set-xdg_session_typewayland sample] wrapper script: {{Cat|/usr/local/bin/sway-run|<nowiki>#!/bin/sh
rc-update add greetd
# Session
adduser greetd seat
export XDG_SESSION_TYPE=wayland
export XDG_SESSION_DESKTOP=sway
export XDG_CURRENT_DESKTOP=sway


In <code>/etc/greetd/config.toml</code>, set
# Wayland stuff
export MOZ_ENABLE_WAYLAND=1
export QT_QPA_PLATFORM=wayland
export SDL_VIDEODRIVER=wayland
export _JAVA_AWT_WM_NONREPARENTING=1


<pre>
# If using seatd instead of elogind uncomment the below line
[default_session]
# export LIBSEAT_BACKEND=seatd


command = "cage -s -- gtkgreet"
# Launch Sway with a D-Bus server available, use:
</pre>


In <code>/etc/greetd/environments</code>, set
<pre>
# Launch Sway with a D-Bus server available, use:
dbus-run-session -- sway
dbus-run-session -- sway
</pre>
</nowiki>}}


D-Bus is required for PipeWire and screensharing in Firefox and Chromium. Running with <code>dbus-run-session</code> is a convenience wrapper that will explicitly export the path of the session bus.
Make the file executable: {{Codeline|<Code># chmod +x /usr/local/bin/sway-run</Code>}}
 
== Install fonts ==
 
Install DejaVu fonts, which has good Unicode coverage:
 
apk add font-dejavu
 
== Install Sway ==
 
apk add sway \
    xwayland            \ # if you need xserver
    foot                \ # default terminal emulator. Modify $term in config for a different one.
    wmenu                \ # default wayland native menu for choosing program and screensharing monitor
    swaylock swaylockd  \ # lockscreen tool
    grim                \ # screenshot tool
    wl-clipboard        \ # clipboard management
    i3status            \ # simple status bar
    swayidle              # idle management (DPMS) daemon
 
For complimentary software alternatives, see [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the relevant page from sway's wiki] or [https://wiki.gentoo.org/wiki/List_of_software_for_Wayland this list at Gentoo Wiki.]


== Configuration ==
== Configuration ==


Copy default sway configuration to <code>~/.config</code>:
===Sway config file ===
 
Copy default sway configuration file to {{Path|~/.config/sway/config}} so that it can be customized per user:{{cmd|$ mkdir -p ~/.config/sway
# as normal user
$ cp /etc/sway/config ~/.config/sway/}}
mkdir -p ~/.config/sway
cp /etc/sway/config ~/.config/sway/


Read through it to learn the default keybindings.
Read through it to learn the default keybindings.
Line 117: Line 97:
For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream wiki].
For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream wiki].


== PipeWire and enable screensharing ==
=== PipeWire and Screensharing ===


For audio playback, either PipeWire or PulseAudio work fine.
For audio playback, install [[PipeWire#Installation|PipeWire]]. The sway compositor has no involvement in audio playback.


For screen sharing, applications are split into two categories:
For screen sharing, applications are split into two categories:


- Those which use the native wayland protocol, </code>wlr-screencopy</code>
* Those which use the native wayland protocol, </code>wlr-screencopy</code>
- Those which use the API from Flatpak's <code>xdg-desktop-portal</code> (this portal is also used by native non-Flatpak applications).
* Those which use the API from Flatpak's <code>xdg-desktop-portal</code> (this portal is also used by native non-Flatpak applications).


Applications in the first group require not additional setup. Applications in the second group (which includes Firefox and Chromium) require setting up pipewire, wireplumber and xdg portals:
Applications in the first group require no additional setup. Applications in the second group (which includes Firefox and Chromium) require setting up xdg portals in addition to [[PipeWire#Installation|PipeWire]].


apk add pipewire pipewire-pulse pipewire-tools
{{Cmd|# apk add xdg-desktop-portal xdg-desktop-portal-wlr}}
apk add wireplumber
  apk add xdg-desktop-portal xdg-desktop-portal-wlr


Launch PipeWire with Sway. Use your service manager of choice, or add the following to sway config:
Launch PipeWire with Sway by adding the following to sway [[#Sway config file|config]] file:  


<pre>
  exec /usr/libexec/pipewire-launcher
  exec /usr/libexec/pipewire-launcher
</pre>


If your are using automatic D-Bus activation, you also need to set DBus variables for the portal and screensharing features to work:
If you are using <code>dbus-run-session</code> wrapper to launch sway, you also need to set D-Bus variables for the portal and screensharing features to work by adding the following to sway [[#Sway config file|config]] file:


  exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway
  exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway


{{Box YELLOW|Unclear:|The following paragraph is unclear and needs further work}}
=== Screen lock and suspend-to-RAM ===


Replace dmenu (depends on X server) with bemenu (Wayland native) for launching programs and selecting which screen to share in Firefox/Chromium:
{{Tip| For a seat manager and de/wm agnostic tool consider {{Pkg|powerctl}} utility available in the [[Repositories#Testing|testing]] repository to manage suspend and hibernation.}}


set $menu bemenu-run | xargs swaymsg exec
Putting the system to sleep with elogind requires elevated privileges or additional configuration.


== Mouse cursor theme ==
For details on configuring <code>doas</code> with <code>elogind</code>, see [[Elogind#Doas]]


Set a mouse cursor, using GNOME Adwaita theme:
To put the system to sleep after 600 seconds, use:


  seat "*" xcursor_theme Adwaita 16
  exec swayidle -w timeout 600 'doas /bin/loginctl suspend'


== Screen lock and suspend-to-RAM ==
loginctl suspend command will trigger the screenlock, as mentioned in the section [[#Install elogind (optional)|Install elogind (optional)]] above.


=== Without elogind ===
Do not lock the screen if program is running in full screen:


Consider using {{Pkg|powerctl}}.
for_window [app_id="^.*"] inhibit_idle fullscreen


=== With elogind ===
=== Elogind and swayidle ===


Putting the system to sleep with elogind requires elevated privileges or additional configuration.
<code>swayidle</code> has integration with <code>elogind</code> and can handle <code>before-sleep</code> events.


For details on configuring <code>doas</code> with <code>elogind</code>, see [[Elogind#Doas]]
If using <code>swayidle before-sleep</code>, there will be a race condition, so that when you resume the computer from suspend, the screen shows the contents of the unlocked screen for a second before showing the actual lock screen.  This can be a privacy concern.


To put the system to sleep after 600 seconds, use:
To solve this issue, do the following:


exec swayidle -w timeout 600 'doas /bin/loginctl suspend'
Create this file <code>/etc/elogind/system-sleep/10-swaylock.sh</code>, then add the following script to this file:


loginctl suspend command will trigger the screenlock, as mentioned in the section [[#Install elogind (optional)|Install elogind (optional)]] above.
#!/bin/sh
if [ "${1}" == "pre" ]; then
  touch /tmp/swaylock-sleep
  sleep 1
fi


Do not lock the screen if program is running in full screen:
Then set it to executable.


for_window [app_id="^.*"] inhibit_idle fullscreen
Later, once sway is installed, add the following line to sway [[#Sway config file|config]] file:


== Brightness control ==
exec touch /tmp/swaylock-sleep && inotifyd swaylock /tmp/swaylock-sleep


Controlling display backlight requires either the proper udev rules, or using some form of privilege escalation.
With this line, the screen will be promptly locked before suspend-to-RAM starts.


{{Pkg|brightnessctl}} is a reliable alternative, although its default udev rules require too wide permissions (see {{Issue|15409}}). You may need your own rules, or configure doas to allow running it as an unprivileged user.
=== Brightness control ===


Optionally enable brightnessctl service to restore brightness settings on reboot:
Refer [[Backlight]] for information on brightness control utilities including the popular [[Backlight#Brightnessctl|brightnessctl]] utility.


rc-update add brightnessctl
=== Output scaling for high resolution displays ===
 
== Output scaling for high resolution displays ==


Without further configuration, program interfaces might be too small to use on high resolution displays.
Without further configuration, program interfaces might be too small to use on high resolution displays.
Line 195: Line 177:
However, fractional scaling is discouraged due to both the performance impact and the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT based scaling is recommended.  See below.
However, fractional scaling is discouraged due to both the performance impact and the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT based scaling is recommended.  See below.


To enable Sway scaling, the user can first preview different scaling factors with <code>wdisplays</code> package.  Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2.  To make changes permanent, add
To enable Sway scaling, the user can first preview different scaling factors with <code>wdisplays</code> package.  Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2.  To make changes permanent, add below to sway [[#Sway config file|config]] file.


<pre>
<pre>
output <name> scale <factor>
output <name> scale <factor>
</pre>
</pre>
to ~/.config/sway/config.


To use toolkit scaling, use
To use toolkit scaling, use
Line 214: Line 194:
}}
}}


== Make clipboard content persistent ==
=== Screenshots ===
 
A simple tool that works well under Wayland is Grimshot. Example keybindings:
<pre>
bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
</pre>
 
See [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the sway wiki's article] for a list of screenshot tools.
 
=== Make clipboard content persistent ===
 
By default the clipboard content does not persist after terminating the program: you copy some text from Firefox and then exit Firefox, the copied text is also lost.
By default the clipboard content does not persist after terminating the program: you copy some text from Firefox and then exit Firefox, the copied text is also lost.


Install clipman from testing repo and add the following to sway config:
Install {{Pkg|clipman}} from testing repo and add the following to sway [[#Sway config file|config]] file:


<pre>
<pre>
Line 224: Line 217:
</pre>
</pre>


== Firefox picture-in-picture mode/floating windows ==
=== Firefox picture-in-picture mode/floating windows ===
 
Add this to your sway config file (modify the numeric values to suit your needs and your display):
Add this to your sway config file (modify the numeric values to suit your needs and your display):
<pre>
<pre>
Line 230: Line 224:
</pre>
</pre>


== Screenshots ==
=== Start with NumLock enabled ===
A simple tool that works well under Wayland is Grimshot. Example keybindings:
 
<pre>
Add this to your sway config file:
bindsym Print exec grimshot copy area
 
bindsym Shift+Print exec grimshot copy screen
input type:keyboard xkb_numlock enabled
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
 
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
=== Change mouse cursor theme and size ===
</pre>
 
Add to your sway [[#Sway config file|config]] file:
 
seat seat0 xcursor_theme my_cursor_theme my_cursor_size


See [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the sway wiki's article] for a list of screenshot tools.
For example, set a mouse cursor, using GNOME Adwaita theme:


== Start with NumLock enabled ==
seat seat0 xcursor_theme Adwaita 16
Add this to your sway config file:
<code>input type:keyboard xkb_numlock enabled</code>


== Change cursor theme and size ==
Add to your sway config:
<pre>
seat seat0 xcursor_theme my_cursor_theme my_cursor_size
</pre>
You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your config does not result in change, try logging out and in.
You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your config does not result in change, try logging out and in.
{{Note|Wayland uses client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}


{{Note|Wayland allows for client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}


== Custom keyboard layout ==
=== Custom keyboard layout ===


To use custom keyboard layout, just use
To use custom keyboard layout, just use
Line 263: Line 253:
</pre>
</pre>


== Changing default application fonts ==
== Troubleshooting ==
 
If you encounter any issues, try running <code>sway -Vc /etc/sway/config</code>. It will run sway with the default config file and set the output to be more verbose. It is generally a good idea to track your config files with git (when and if at all you use a remote repository for them, keep it private for security reasons).


See [[Fontconfig]]
To capture the sway error log in a file for troubleshooting, replace <code>sway</code> in your startup file by
<code>sway -d 2> ~/sway_error.log</code>.


== Troubleshooting ==
Alternately, you can also issue the below command from TTY.
{{cmd|$ sway -d 2> ~/sway_error.log}}
 
=== Video Driver Issues ===
 
After installing sway, while launching it for the first time, lack of proper [[#Install Graphics Drivers|video drivers]] causes various error messages such as:
* "unable to create backend"
* "Failed to create renderer"


If you encounter any issues, try running <code>sway -Vc /etc/sway/config</code>. It will run sway with the default config file and set the output to be more verbose. It is generally a good idea to track your config files with git (when and if at all you use a remote repository for them, keep it private for security reasons).  
Do install necessary drivers for your [[#Install Graphics Drivers|graphics card]] for sway to work.  


=== Flatpaks ===
=== Flatpaks ===
{{main|Flatpak}}
{{main|Flatpak}}
Due to their sandboxing, flatpaks require the use of a portal frontend (xdg-desktop-portal) and backends (such as xdg-desktop-portal-wlr, xdg-desktop-portal-gtk, xdg-desktop-portal-gnome) that implement the methods. When in doubt, install multiple backends. For more information on backends, see [https://github.com/flatpak/xdg-desktop-portal/#using-portals flatpak's page on the subject]. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional backends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.
Due to their sandboxing, flatpaks require the use of a portal frontend (xdg-desktop-portal) and backends (such as xdg-desktop-portal-wlr, xdg-desktop-portal-gtk, xdg-desktop-portal-gnome) that implement the methods. When in doubt, install multiple backends. For more information on backends, see [https://github.com/flatpak/xdg-desktop-portal/#using-portals flatpak's page on the subject]. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional backends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.


After installing different backends, you might need to add the relevant backends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway config file may include:
After installing different backends, you might need to add the relevant backends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway [[#Sway config file|config]] file may include:
<pre>
<pre>
exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-gtk
Line 285: Line 286:


=== Firefox (Flatpak) and/or GTK apps ===
=== Firefox (Flatpak) and/or GTK apps ===
==== Disappearing cursor ====
==== Disappearing cursor ====
You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively you can install a theme     for all users (search [https://pkgs.alpinelinux.org/ Alpine Linux Packages] for ''*-icon-theme'') using <code>apk add</code>.
 
You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively you can install a theme for all users (search [https://pkgs.alpinelinux.org/ Alpine Linux Packages] for ''*-icon-theme'') using <code>apk add</code>.


==== Missing file picker/cannot download ====
==== Missing file picker/cannot download ====
Line 292: Line 295:
Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.
Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.


=== Failing to start under certain graphics cards/multiple wlroots stacked windows spawning upon start ===
=== Nvidia Issues ===
 
{{Main|NVIDIA}}
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to <code>drm,libinput</code> or <code>x11</code> (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install libinput first''').
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to <code>drm,libinput</code> or <code>x11</code> (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install libinput first''').


=== Sway socket not detected ===
== See also ==
 
See [[Sway#Installation|Installation]] for instructions on how to set this environmental variable. This issue may occur with terminal multiplexers, such as [[tmux]]
 


== See Also ==
* [https://github.com/swaywm/sway/wiki/ Sway Wiki]
* [https://wiki.archlinux.org/title/Sway Archwiki]
* [https://wiki.archlinux.org/title/Sway Archwiki]
* [https://wiki.gentoo.org/wiki/Sway Gentoo Wiki]
* [https://wiki.gentoo.org/wiki/Sway Gentoo Wiki]
* [https://wiki.postmarketos.org/wiki/Sway PostmarketOS Wiki]
* [https://wiki.postmarketos.org/wiki/Sway PostmarketOS Wiki]


[[Category:Compositor]]
[[Category:Desktop]]
[[Category:Desktop]]
[[Category:Window Managers]]
[[Category:Window Managers]]
[[Category:Wayland]]
[[Category:Wayland]]

Latest revision as of 12:38, 29 January 2025

Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.

Note: Before installing any desktop,

Setup-desktop script automatically enables the community repository.

Installation using setup-desktop

The Alpine Linux script for setting up a desktop quickly is setup-desktop.

# setup-desktop

On running the above command, you will be prompted to select a desktop environment.

Which desktop environment? ('gnome', 'plasma', 'xfce', 'mate', 'sway', 'lxqt' or 'none') [none]

Once you have chosen a desktop environment, this script installs the chosen desktop along with necessary packages, firefox browser and adds the necessary services to run on startup. You can reboot when complete and the system will boot into a graphical login screen with the desktop environment. Depending on the desktop chosen, the script also activates the necessary services like dbus, elogind, login manager etc..

To view all the packages that are installed by the script for the chosen desktop you can issue the below command:

# cat /usr/sbin/setup-desktop

Install appropriate video drivers for your hardware before you can launch sway. Without graphics drivers errors may occur.

Manual Installation

The below installation step allows you to pick and choose various componenents for your Sway Desktop.

Add a normal user

Use setup-user to add a non-system normal user for running Sway.

# setup-user

Set up eudev

Setting up eudev on a desktop system is recommended in Alpine Linux. Without a fully functional device manager users will not be able to connect to input devices. The alpine-conf package provides setup-devd script to easily install and setup device managers.

Setup eudev.

# setup-devd udev

For more details and other options see eudev.

Install Graphics Drivers

Install graphics driver for your video hardware. Without proper driver, Sway will fail to start.

Setup up a seat manager

Wayland compositors need raw access to input and output devices. This is mediated by a seat manager.

Configure either seatd or elogind as both are supported. However using both may lead to conflicts.

Install fonts

Install DejaVu fonts, which has good Unicode coverage:

# apk add font-dejavu

Install Sway

# apk add sway \ xwayland \ # if you need xserver foot \ # default terminal emulator. Modify $term in config for a different one. wmenu \ # default wayland native menu for choosing program and screensharing monitor swaylock swaylockd \ # lockscreen tool swaybg \ # display wallpaper grim \ # screenshot tool wl-clipboard \ # clipboard management i3status \ # simple status bar swayidle # idle management (DPMS) daemon

For complimentary software alternatives, see sway wiki or Gentoo Wiki.

Starting sway

Manually launch sway

You can launch sway by issuing the command sway from TTY.

$ sway

Automatically launch sway on TTY login

Note: D-Bus is required for PipeWire and screensharing in Firefox and Chromium. Running with dbus-run-session is a convenience wrapper that will explicitly export the path of the session bus.

Adding the following lines to your ~/.profile will launch Sway automatically with D-Bus only in tty1

Contents of ~/.profile

export XDG_VTNR=$(basename "$(tty)" | sed 's/tty//') if [ -z "$WAYLAND_DISPLAY" ] && [ "$XDG_VTNR" -eq 1 ]; then exec dbus-run-session sway fi

Use Wrapper script to launch sway

Instead of using ~.profile for environment variables, a wrapper script sway-run can be used to launch sway from both TTY and greetd, a lightweight display manager. Here is a sample wrapper script:

Contents of /usr/local/bin/sway-run

#!/bin/sh # Session export XDG_SESSION_TYPE=wayland export XDG_SESSION_DESKTOP=sway export XDG_CURRENT_DESKTOP=sway # Wayland stuff export MOZ_ENABLE_WAYLAND=1 export QT_QPA_PLATFORM=wayland export SDL_VIDEODRIVER=wayland export _JAVA_AWT_WM_NONREPARENTING=1 # If using seatd instead of elogind uncomment the below line # export LIBSEAT_BACKEND=seatd # Launch Sway with a D-Bus server available, use: dbus-run-session -- sway

Make the file executable: # chmod +x /usr/local/bin/sway-run

Configuration

Sway config file

Copy default sway configuration file to ~/.config/sway/config so that it can be customized per user:

$ mkdir -p ~/.config/sway $ cp /etc/sway/config ~/.config/sway/

Read through it to learn the default keybindings. Sway configuration is mostly backwards-compatible with that of i3 and if you are looking for a solution for a specific issue, you may also try checking if it hasn't been provided for i3WM.

For additional information, start at man 5 sway and read the upstream wiki.

PipeWire and Screensharing

For audio playback, install PipeWire. The sway compositor has no involvement in audio playback.

For screen sharing, applications are split into two categories:

  • Those which use the native wayland protocol, wlr-screencopy
  • Those which use the API from Flatpak's xdg-desktop-portal (this portal is also used by native non-Flatpak applications).

Applications in the first group require no additional setup. Applications in the second group (which includes Firefox and Chromium) require setting up xdg portals in addition to PipeWire.

# apk add xdg-desktop-portal xdg-desktop-portal-wlr

Launch PipeWire with Sway by adding the following to sway config file: 

 exec /usr/libexec/pipewire-launcher

If you are using dbus-run-session wrapper to launch sway, you also need to set D-Bus variables for the portal and screensharing features to work by adding the following to sway config file: 

exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway

Screen lock and suspend-to-RAM

Tip: For a seat manager and de/wm agnostic tool consider powerctl utility available in the testing repository to manage suspend and hibernation.

Putting the system to sleep with elogind requires elevated privileges or additional configuration.

For details on configuring doas with elogind, see Elogind#Doas

To put the system to sleep after 600 seconds, use: 

exec swayidle -w timeout 600 'doas /bin/loginctl suspend'

loginctl suspend command will trigger the screenlock, as mentioned in the section Install elogind (optional) above.

Do not lock the screen if program is running in full screen: 

for_window [app_id="^.*"] inhibit_idle fullscreen

Elogind and swayidle

swayidle has integration with elogind and can handle before-sleep events.

If using swayidle before-sleep, there will be a race condition, so that when you resume the computer from suspend, the screen shows the contents of the unlocked screen for a second before showing the actual lock screen. This can be a privacy concern.

To solve this issue, do the following:

Create this file /etc/elogind/system-sleep/10-swaylock.sh, then add the following script to this file: 

#!/bin/sh
if [ "${1}" == "pre" ]; then
  touch /tmp/swaylock-sleep
  sleep 1
fi

Then set it to executable.

Later, once sway is installed, add the following line to sway config file: 

exec touch /tmp/swaylock-sleep && inotifyd swaylock /tmp/swaylock-sleep

With this line, the screen will be promptly locked before suspend-to-RAM starts.

Brightness control

Refer Backlight for information on brightness control utilities including the popular brightnessctl utility.

Output scaling for high resolution displays

Without further configuration, program interfaces might be too small to use on high resolution displays.

Sway supports the per-display configuration of

  • fractional (e.g., 1.5x), and
  • integer scaling (e.g., 2x)

However, fractional scaling is discouraged due to both the performance impact and the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT based scaling is recommended. See below.

To enable Sway scaling, the user can first preview different scaling factors with wdisplays package. Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2. To make changes permanent, add below to sway config file. 

output <name> scale <factor>

To use toolkit scaling, use

# for GTK-based programs such as firefox and emacs: export GDK_DPI_SCALE=2 # for QT-based programs export QT_WAYLAND_FORCE_DPI="physical" # or if still too small, use a custom DPI export QT_WAYLAND_FORCE_DPI=192 # 2x scaling export QT_QPA_PLATFORM="wayland-egl"

Screenshots

A simple tool that works well under Wayland is Grimshot. Example keybindings: 

bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png

See the sway wiki's article for a list of screenshot tools.

Make clipboard content persistent

By default the clipboard content does not persist after terminating the program: you copy some text from Firefox and then exit Firefox, the copied text is also lost.

Install clipman from testing repo and add the following to sway config file: 

exec wl-paste --type text/plain --watch clipman store --histpath="~/.local/state/clipman-primary.json"
bindsym $mod+h exec clipman pick --tool wofi --histpath="~/.local/state/clipman-primary.json"

Firefox picture-in-picture mode/floating windows

Add this to your sway config file (modify the numeric values to suit your needs and your display): 

for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none

Start with NumLock enabled

Add this to your sway config file: 

input type:keyboard xkb_numlock enabled

Change mouse cursor theme and size

Add to your sway config file: 

seat seat0 xcursor_theme my_cursor_theme my_cursor_size

For example, set a mouse cursor, using GNOME Adwaita theme: 

seat seat0 xcursor_theme Adwaita 16

You can inspect their values with echo $XCURSOR_SIZE and echo $XCURSOR_THEME. If reloading your config does not result in change, try logging out and in.

Note: Wayland allows for client-side cursors. It is possible that applications do not evaluate the values of $XCURSOR_SIZE and $XCURSOR_THEME.

Custom keyboard layout

To use custom keyboard layout, just use 

input type:keyboard {
  xkb_file /path/to/my/custom/layout
}

Troubleshooting

If you encounter any issues, try running sway -Vc /etc/sway/config. It will run sway with the default config file and set the output to be more verbose. It is generally a good idea to track your config files with git (when and if at all you use a remote repository for them, keep it private for security reasons).

To capture the sway error log in a file for troubleshooting, replace sway in your startup file by sway -d 2> ~/sway_error.log.

Alternately, you can also issue the below command from TTY.

$ sway -d 2> ~/sway_error.log

Video Driver Issues

After installing sway, while launching it for the first time, lack of proper video drivers causes various error messages such as:

  • "unable to create backend"
  • "Failed to create renderer"

Do install necessary drivers for your graphics card for sway to work.

Flatpaks

Main article: Flatpak

Due to their sandboxing, flatpaks require the use of a portal frontend (xdg-desktop-portal) and backends (such as xdg-desktop-portal-wlr, xdg-desktop-portal-gtk, xdg-desktop-portal-gnome) that implement the methods. When in doubt, install multiple backends. For more information on backends, see flatpak's page on the subject. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional backends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.

After installing different backends, you might need to add the relevant backends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway config file may include: 

exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
exec /usr/libexec/xdg-desktop-portal-gnome

This is only needed if they are not started automatically via other means.

Firefox (Flatpak) and/or GTK apps

Disappearing cursor

You may need to get an icon pack and possibly a theme from Pling store and set GTK_THEME environmental variable. Alternatively you can install a theme for all users (search Alpine Linux Packages for *-icon-theme) using apk add.

Missing file picker/cannot download

Go to about:config and set widget.use-xdg-desktop-portal.file-picker to 0.

Nvidia Issues

Main article: NVIDIA

As of Dec 31 2022, Nvidia still doesn't fully support Wayland. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to drm,libinput or x11 (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards (make sure to install libinput first).

See also

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=Sway&oldid=28867"