Sway
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.
Quick start Installation
The inbuilt utility for setting up Sway desktop in Alpine Linux is setup-desktop, which is available in package alpine-conf as part of standard Alpine Linux installation.
# setup-desktop sway
The above command installs wayland-base which includes elogind, polkit-elogind , eudev and the following packages dmenu, font-dejavu , foot, grim, i3status, sway, swayidle, swaylockd, util-linux-login, wl-clipboard, wmenu, xwayland and finally firefox as browser.
The above utility pulls in all the necessary dependencies and you can launch sway by issuing the command sway from tty.
$ sway
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.
Set up eudev
eudev is recommended and required for. Without it, sway cannot connect to input devices.
setup-devd udev
Install Graphics Drivers
Graphics drivers:
Setting up a seat manager
Wayland compositors need raw access to input and output devices. This is mediated by a seat manager. Using either seatd or elogind is supported. Using both may lead to conflicts.
Install seatd
See Seatd for the mandatory steps needed for sway to work with seatd.
Install elogind
See Elogind.
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:
# in ~/.config/sway/config exec touch /tmp/swaylock-sleep && inotifyd swaylock /tmp/swaylock-sleep
With this line, the screen will be promptly locked before suspend-to-RAM starts.
Install greetd (optional)
apk add greetd greetd-gtkgreet cage rc-update add greetd adduser greetd seat
In /etc/greetd/config.toml, set
[default_session] command = "cage -s -- gtkgreet"
To use a graphical greeter with seatd add rc_need=seatd to /etc/conf.d/greetd.
In /etc/greetd/environments, set
# Launch Sway with a D-Bus server available, use: dbus-run-session -- sway
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.
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 the relevant page from sway's wiki or this list at Gentoo Wiki.
Configuration
Copy default sway configuration to ~/.config:
# as normal 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 enable screensharing
For audio playback, either PipeWire or PulseAudio work fine. The 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 not additional setup. Applications in the second group (which includes Firefox and Chromium) require setting up pipewire, wireplumber and xdg portals:
apk add pipewire pipewire-pulse pipewire-tools 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:
exec /usr/libexec/pipewire-launcher
If your are using automatic D-Bus activation, you also need to set DBus variables for the portal and screensharing features to work:
exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway
Replace dmenu (depends on X server) with bemenu (Wayland native) for launching programs and selecting which screen to share in Firefox/Chromium:
set $menu bemenu-run | xargs swaymsg exec
Screen lock and suspend-to-RAM
Without elogind
Consider using powerctl.
With elogind
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
Brightness control
Controlling display backlight requires either the proper udev rules, or using some form of privilege escalation.
brightnessctl is a reliable alternative, although its default udev rules require too wide permissions (see #15409). You may need your own rules, or configure doas to allow running it as an unprivileged user.
Optionally enable brightnessctl service to restore brightness settings on reboot:
rc-update add brightnessctl
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
output <name> scale <factor>
to ~/.config/sway/config.
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.
Tweaks
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:
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:
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.
$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
}
Changing default application fonts
See Fontconfig
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
Flatpaks
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.
Failing to start under certain graphics cards/multiple wlroots stacked windows spawning upon start
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).
Sway socket not detected
See Installation for instructions on how to set this environmental variable. This issue may occur with terminal multiplexers, such as tmux