Sway

Sway is a tiling Wayland compositor. It's a drop-in replacement for the i3 window manager.

Installation

eudev:

# apk add eudev
# setup-devd udev

Graphics drivers:

• Intel Video
• Radeon Video
• Nvidia Video

Add user to the input and video groups:

# adduser $USER input
# adduser $USER video

Install some TTF fonts:

# apk add ttf-dejavu

seatd daemon:

# apk add seatd
# rc-update add seatd
# rc-service seatd start
# adduser $USER seat

elogind, optional for suspending with a key (otherwise you can run echo mem > /sys/power/state as a root), or lid close support

Note: Even though elogind may be installed and the service running, you may still need to configure some values. Otherwise you may for example be able to suspend with a key, but encounter a freeze upon waking. It is always vital to verify it is set up correctly with loginctl list-sessions

Install sway:

# apk add sway sway-doc
# apk add                \ # Install optional dependencies:
    xwayland             \ # recommended for compatibility reasons
    foot                 \ # default terminal emulator. Modify $term in config for a different one.
    bemenu               \ # wayland menu
    swaylock swaylockd   \ # lockscreen tool
    swaybg               \ # wallpaper daemon
    swayidle               # idle management (DPMS) daemon

Configure XDG_RUNTIME_DIR. If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the XDG_RUNTIME_DIR code with

export XDG_SEAT=seat0
export XDG_SESSION_CLASS=user

For inter-program communication and functionality such as screensharing, install and enable dbus and PipeWire, see PipeWire and set SWAYSOCK environmental variable to /tmp/$(id -u)-runtime-dir/sway-ipc.1000.$(pgrep -x sway).sock in your login shell's init script. Note that it has to be set after the line responsible for launching Sway.

Re-login or reboot to allow above modifications to take effect.

Launch Sway with dbus support:

dbus-run-session -- sway #prepend with exec in your login shell init script

Configuration

An example config is provided at /etc/sway/config. Copy it to ~/.config/sway/config and 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.

Firefox screensharing

For some programs, additional configuration is needed to launch them natively under Wayland and to support special features such as screen sharing.

To launch Firefox natively under Wayland and to enable support for screensharing, you need:

• Install and configure PipeWire
• Install xdg-desktop-portal and xdg-desktop-portal-wlr package
• Install wofi for screen selection
• Launch support programs on sway startup:

exec /usr/libexec/pipewire-launcher #pipewire must be launched first
exec /usr/libexec/xdg-desktop-portal-wlr

• Export the following variables:

export MOZ_ENABLE_WAYLAND="1"
export XDG_CURRENT_DESKTOP=sway
export XDG_SESSION_TYPE=wayland
export QT_QPA_PLATFORM="wayland-egl"

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

If you are using bemenu or dmenu and want flatpaks to be included in their search, you need to add the executables for the flatpaks to your $PATH for these launchers to find. To do so in Alpine Linux, open /etc/profile and add a new line to the list of append_path to include the flatpaks. For example, but with your username instead of USERNAME:

append_path "/usr/local/sbin"
append_path "/usr/local/bin"
append_path "/usr/sbin"
append_path "/usr/bin"
append_path "/sbin"
append_path "/bin"
append_path "/home/USERNAME/.local/share/flatpak/exports/bin"

Scaling for high resolution screens

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

Via sway

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.

Via GTK/Qt

# 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 test 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

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.

Start as a service

Although this is not necessary, you may write an init script like the following:

{{/etc/init.d/sway|
#!/sbin/openrc-run

description="Sway Compositor"

command="/usr/bin/sway"
command_args=""

pidfile="/run/sway.pid"

start_stop_daemon_args="--background --pidfile ${pidfile}"

depend() {
  need localmount
  after elogind
  use seatd dbus
}

Then as a root run chmod +x /etc/init.d/seat and rc-update add sway default. Make sure you have elogind installed or specify another service, like your display/login manager after which the sway service will run.

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 * {
  xkb_layout "my_layout" 
}

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

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

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