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.

Add a normal user

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

Install Graphics Drivers

Graphics drivers:

• Intel Video
• Radeon Video
• Nvidia Video

Install seatd

Install seatd, a minimal seat management daemon. This grants the required permissions to the user running sway:

apk add seatd

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

rc-service seatd start
adduser $USER seat

Install elogind (optional)

elogind is used to enable suspend-to-RAM:

apk add elogind
rc-update add elogind
rc-service elogind start

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, if someone is filming the screen. 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 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.

Set up eudev

eudev is recommended and required for the greeter. Or else it will not be able to find any input device (libinput failure).

setup-devd udev

Install greetd (optional)

greetd is used to set XDG_RUNTIME_DIR and properly configure seat:

apk add greetd greetd-gtkgreet cage greetd-openrc
rc-update add greetd
adduser greetd seat

In /etc/greetd/config.toml, set

[default_session]

command = "cage -s -- gtkgreet"

In /etc/greetd/environments, set

# Launch Sway with a D-Bus server available, use:
dbus-run-session -- sway

We need to run sway with dbus-run-session, this is needed for PipeWire and screensharing in Firefox and Chromium.

Install doas (optional)

Doas is used to grant permissions for suspend-to-RAM and brightness control with brightnessctl:

apk add doas brightnessctl
# optionally, allow $USER root access with password
adduser $USER wheel

In /etc/doas.conf, set

permit :wheel
permit nopass $USER as root cmd /bin/loginctl
permit nopass $USER as root cmd /usr/bin/brightnessctl

After setting the above, suspend-to-RAM can be triggered by running

/bin/loginctl suspend

(use full path to executable) and brightness can be adjusted by running

/usr/bin/brightnessctl set 100

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.
   bemenu               \ # 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 for example 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.

Launch PipeWire and enable screensharing

For a reasonable desktop experience with support for audio and screensharing, install 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, add the following to sway config:

exec /usr/libexec/pipewire-launcher

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

Mouse cursor theme

Set a mouse cursor, using GNOME Adwaita theme:

seat "*" xcursor_theme Adwaita 16

Screen lock and suspend-to-RAM

Set screen lock and suspend-to-RAM:

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

loginctl suspend command will trigger the screenlock, as mentioned above.

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

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

Brightness control

Use brightnessctl. Configure permission in doas config. 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"

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

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.

Start with NumLock enabled

Add this to your sway config file: input type:keyboard xkb_numlock enabled

Change cursor theme and size

Add to your sway config:

seat seat0 xcursor_theme my_cursor_theme my_cursor_size

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 uses client-side cursors. It is possible that applications do not evaluate the values of $XCURSOR_SIZE and $XCURSOR_THEME.

Custom keyboard layout

Since wayland does not support setxkbmap, you will also need to add similar content to your /usr/share/X11/xkb/rules/evdev.xml, after </modelList> and after <layoutList>:

<layout>
      <configItem>
        <name>[the name of your layout, same as the name of the file in /usr/share/X11/xkb/symbols]</name>
        <shortDescription>[usually just two letters]</shortDescription>
        <description>[description of your layout]</description>
        <countryList>
          <iso3166Id>US</iso3166Id>
          <iso3166Id>NO</iso3166Id>
        </countryList>
        <languageList>
          <iso639Id>eng</iso639Id>
        </languageList>
      </configItem>
    </layout>
<!--[other layouts]-->

Then, to enable for all keyboards, navigate to the input section of ~/.config/sway/config and modify it to

input type:keyboard {
  xkb_layout "my_layout" 
}

If you have enabled xkb_numlock, include this setting inside those braces as well.

Default font

This is not related to Sway, but still nice to have: change system wide default font selection. In /etc/fonts/conf.d/52-my-default-fonts.conf, set

<?xml version='1.0'?>
<!DOCTYPE fontconfig SYSTEM 'urn:fontconfig:fonts.dtd'>
<fontconfig>
  <!-- Default fonts -->
  <alias binding="same">
    <family>sans-serif</family>
    <prefer>
      <family>DejaVu Sans</family>
    </prefer>
  </alias>
  <alias binding="same">
    <family>serif</family>
    <prefer>
      <family>DejaVu Serif</family>
    </prefer>
  </alias>
  <alias binding="same">
    <family>monospace</family>
    <prefer>
      <family>DejaVu Sans Mono</family>
    </prefer>
  </alias>
</fontconfig>

You can obtain a list of installed fonts with fc-list.

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).

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.

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

See Also

• Archwiki
• Gentoo Wiki
• PostmarketOS Wiki