River: Difference between revisions

Latest revision as of 18:06, 19 December 2025

River is a dynamic tiling Wayland compositor. River "upstream" has developed into two different projects:-

v3.23.x v3.22.x v3.21.x

river-classic, which is an upstream fork of the original River version 0.3, now known under that new name. As of December 2025, it is the only version available on Alpine Linux: it can be downloaded as river-classic from Alpine Linux v3.23 and Edge community repositories, while it retains its legacy name as river in the v3.22 and v3.21 community repositories.
The current River project upstream, version 0.4+, which is developing under their new river-window-management-v1 protocol, also known by its rwm tag.

Updating the original river package from version 0.3 to version 0.4 would cause breakages, and therefore, distinct projects are being developed upstream.

Prerequisites

Internet connectivity, unless the packages have been pre-fetched into a local cache.
Install appropriate Graphics driver drivers for your hardware. Without graphics drivers, errors are likely to occur when starting your desktop.
A non-root user account with appropriate groups for desktop usage.
The community repository must be enabled.
Set up eudev.
Install and enable D-Bus. Without D-Bus, icons and keyboard shortcuts may be missing.
Wayland compositors need raw access to input and output devices, typically mediated by a seat manager. Either seatd or elogind work fine, but installing both leads to conflicts.
Installing wayland-base enables elogind as the seat manager and also enables the community repository and eudev.

Installation

Install river-classic and its documentation:

Under Alpine Linux v3.23 and Edge versions

v3.23.x

# apk add river-classic river-classic-doc

Under Alpine Linux v3.22 and v3.21

v3.22.x v3.21.x

# apk add river river-doc

The -doc packages are required to use the example config.

Install your choice of additional packages. The following list includes icons, fonts and a terminal emulator named foot, which is the default in river-classic's sample init file that we will use later.

# apk add adwaita-icon-theme foot font-dejavu

Further packages that are available include the following. Ensure that the Edge repository is enabled and tagged first before installing any of the following with the @testing tag, last checked in November 2025:-

rivercarro for a fork of the rivertile layout (tag as @testing);
river-luatile to write layouts in lua (tag as @testing);
river-shifttags to enable the reordering of tags (tag as @testing):
river-bedload to send info to STDOUT (tag as @testing);
those for bash/zsh/fish completion (some are in @testing, some in community repo): say, river-classic-bash-completion in Alpine Linux v3.23 or Edge community, or river-bash-completion in Alpine Linux v3.22 community repo.

To begin a search for any more packages:-

If running v3.23 or Edge, try apk search -v river-classic first, or see river-classic*.
For Alpine Linux v3.22/v3.21, or for a cruder, more generic search regardless of the Alpine Linux version, one could try apk search -v river | grep -v 'driver' , which would exclude the term 'driver'; apk search -v river; or see river* for packages that begin with that term.

Running river-classic

Before running river-classic for the first time, copy the sample init file to ~/.config:

install -Dm0755 /usr/share/doc/river/examples/init -t ~/.config/river

Set XDG_RUNTIME_DIR and then start river-classic/river with the same instruction:

river

Troubleshooting

This material is proposed for merging ...

It should be merged with Firefox. (Discuss)

The following are a few observations discovered while running river-classic; although not directly related to the compositor, they have been tacked onto the end of this wiki.

Firefox 89.0.1 complained of "glxtest: libpci missing" on launch, resolved with:

apk add pciutils-libs

Firefox 89.0.1 furthermore complained continuously: "Unable to load hand2 from the cursor theme", resolved as follows:

mkdir -p ~/.icons/default ln -s /usr/share/icons/Adwaita/cursors ~/.icons/default/cursors

@@ Line 1: / Line 1: @@
+[https://github.com/riverwm/river River] is a dynamic tiling [[Wayland]] compositor. '''River''' ''"upstream"'' has developed into [https://codeberg.org/river/river/releases/tag/v0.3.12 two different projects]:-
+{{Pill|text=v3.23.x}} {{Pill||v3.22.x|green|palegreen}} {{Pill||v3.21.x|cadetblue|lightblue}}
+* '''river-classic''', which is an upstream fork of the original '''River''' version 0.3, now known under that [https://codeberg.org/river/river-classic new name].  As of December 2025, it is ''the only version available'' on Alpine Linux: it can be downloaded as {{Pkg|river-classic}} from Alpine Linux v3.23 and Edge community repositories, while it retains its legacy name as {{Pkg|river|branch=v3.22}} in the v3.22 and v3.21 community repositories.
+* The current '''River''' project upstream, version 0.4+, which is developing under their new ''river-window-management-v1 protocol'', also known by its ''rwm tag''.
+Updating the original {{ic|river}} package from version 0.3 to version 0.4 would cause breakages, and therefore, distinct projects are being developed upstream.
-{{Note|This is currently not working as written. Updates in Progress}}
+== Prerequisites ==
+{{:Include:Desktop prerequisites}}
-[https://github.com/riverwm/river River] is a dynamic tiling Wayland compositor. An introduction to River can be found in [https://isaacfreund.com/blog/river-intro/ this blog post] by the author for the 0.1.0 release.
+* Wayland compositors need raw access to input and output devices, typically mediated by a [[seat manager]]. Either [[seatd]] or [[elogind]] work fine, but installing both leads to conflicts.
+* Installing [[Alpine_setup_scripts#setup-wayland-base|wayland-base]] enables [[elogind]] as the [[Seat manager|seat manager]] and also enables the [[Repositories#Community|community repository]] and [[eudev]].
-This wiki was written starting from a fresh install using the Alpine 3.14.2 x86_64 extended .iso. The steps begin from the first reboot after running setup-alpine and performing a sys install to disk.
-Many steps below were taken from the [https://wiki.alpinelinux.org/wiki/Sway wiki entry for installing Sway].
-== First Boot ==
-Login as root, create a new user and update group membership:
-{{Cmd|adduser sodface
-addgroup sodface audio
-addgroup sodface input
-addgroup sodface video
-addgroup sodface wheel
-}}
-Install sudo and run visudo, uncommenting the desired permissions for the wheel group:
-{{Cmd|apk add sudo && visudo}}
-Logout and log back in as the new user.
-Test ssh login from a remote computer.
-Verify that you can run commands with sudo.
 == Installation ==
-Edit the repositories file and uncomment the community and testing repos. For 3.14.2, we need edge/community to get the correct software versions to support River:
+Install '''river-classic''' and its documentation:
-{{Cat|/etc/apk/repositories|
+* Under Alpine Linux v3.23 and Edge versions {{Pill||text=v3.23.x}}
-http://dl-cdn.alpinelinux.org/alpine/v3.14/main
+:{{Cmd|# apk add {{Pkg|river-classic}} {{Pkg|river-classic-doc}}}}
-#http://dl-cdn.alpinelinux.org/alpine/v3.14/community
-#http://dl-cdn.alpinelinux.org/alpine/edge/main
-http://dl-cdn.alpinelinux.org/alpine/edge/community
-http://dl-cdn.alpinelinux.org/alpine/edge/testing
-}}
-Install River and the documentation:
-{{Cmd|sudo apk add river river-doc mandoc}}
-Edit the repositories file again to toggle back to the 3.14/community repository before installing additional software:
+* Under Alpine Linux v3.22 and v3.21 {{Pill||v3.22.x|green|palegreen}} {{Pill||v3.21.x|cadetblue|lightblue}}
+:{{Cmd|# apk add {{Pkg|river|branch=v3.22}} {{Pkg|river-doc|branch=v3.22}}}}
-{{Cat|/etc/apk/repositories|
+The <code>-doc</code> packages are required to use the example config.
-http://dl-cdn.alpinelinux.org/alpine/v3.14/main
-http://dl-cdn.alpinelinux.org/alpine/v3.14/community
-#http://dl-cdn.alpinelinux.org/alpine/edge/main
-#http://dl-cdn.alpinelinux.org/alpine/edge/community
-http://dl-cdn.alpinelinux.org/alpine/edge/testing
-}}
-Install your choice of additional applications:
+Install your choice of additional packages.  The following list includes icons, fonts and a terminal emulator named '''foot''', which is the default in '''river-classic''''s sample init file that we will use later.
-This list includes icons, browser, fonts, and a terminal emulator named foot which is the default in River's sample init file that we will use later.
+{{Cmd|# apk add {{Pkg|adwaita-icon-theme}} {{Pkg|foot}} {{Pkg|font-dejavu}}}}
-{{Cmd|sudo apk add adwaita-icon-theme firefox foot ttf-dejavu}}
-== Running River ==
+Further packages that are available include the following.  Ensure that the [[Repositories#Using_testing_repository|'''Edge''' repository is enabled and tagged]] first before installing any of the following with the '''@testing''' tag, last checked in November 2025:-
+* {{Pkg|rivercarro}} for a fork of the rivertile layout (tag as '''@testing''');
+* {{Pkg|river-luatile}} to write layouts in lua (tag as '''@testing''');
+* {{Pkg|river-shifttags}} to enable the reordering of tags (tag as '''@testing'''):
+* {{Pkg|river-bedload}} to send info to STDOUT (tag as '''@testing''');
+* those for bash/zsh/fish completion (some are in '''@testing''', some in '''community''' repo):  say, {{Pkg|river-classic-bash-completion}} in Alpine Linux v3.23 or Edge community, or {{Pkg|river-bash-completion|branch=v3.22}} in Alpine Linux v3.22 community repo.
+To begin a search for any more packages:-
+* If running v3.23 or Edge, try {{ic|apk search -v river-classic}} first, or see {{Pkg|river-classic*}}.
+* For Alpine Linux v3.22/v3.21, or for a cruder, more generic search regardless of the Alpine Linux version, one could try {{ic|<nowiki>apk search -v river | grep -v 'driver'</nowiki>}} , which would exclude the term 'driver'; {{ic|apk search -v river}}; or see {{Pkg|river*|branch=3.22}} for packages that begin with that term.
-Before running River for the first time, copy the sample init file from /etc/river to ~/.config:
+== Running river-classic ==
-{{Cmd|install -Dm0755 /etc/river/init -t ~/.config/river}}
+Before running '''river-classic''' for the first time, copy the sample init file to {{Path|~/.config}}:
-Set seatd to start automatically at next boot and also manually start it for this session:
+{{Cmd|install -Dm0755 /usr/share/doc/river/examples/init -t ~/.config/river}}
-{{Cmd|sudo rc-update add seatd
+Set [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]] and then start '''river-classic'''/'''river''' with the same instruction:
-sudo rc-service seatd start}}
+{{Cmd|river}}
-{{Cmd|sudo addgroup sodface seat}}
+== Troubleshooting ==
+{{Merge|Firefox}}
+The following are a few observations discovered while running '''river-classic''';  although not directly related to the compositor, they have been tacked onto the end of this wiki.
-Logout and log back in again.
+Firefox 89.0.1 complained of ''"glxtest: libpci missing"'' on launch, resolved with:
-Start River:
+{{Cmd|apk add {{Pkg|pciutils-libs}}}}
-{{Cmd|1=XDG_RUNTIME_DIR=/tmp river}}
+Firefox 89.0.1 furthermore complained continuously:  ''"Unable to load hand2 from the cursor theme"'', resolved as follows:
-== Configuration and Usage ==
+{{Cmd|mkdir -p ~/.icons/default
+ln -s /usr/share/icons/Adwaita/cursors ~/.icons/default/cursors}}
-An example config is provided at <code>/etc/sway/config</code>. Copy it to <code>~/.config/sway/config</code> and read through it to learn the default keybindings.
+== See also ==
-For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream FAQ].
+* [https://isaacfreund.com/blog/river-intro/ An introduction to River - isaacfreund.com]
-[[Category:Desktop]]
+[[Category:Compositor]]