docs: add new Steamdeck guide, document setup and workarounds for Pip…

…ewire audio. Fix #960

Signed-off-by: Luca Di Maio <[email protected]>

docs/README.md

@@ -39,6 +39,10 @@ graphical apps (X11/Wayland), and audio.
     - [See it in action](#see-it-in-action)
   - [Why?](#why)
     - [Aims](#aims)
+      - [Security implications](#security-implications)
+- [Quick Start](#quick-start)
+- [Assemble Distrobox](#assemble-distrobox)
+- [Configure Distrobox](#configure-distrobox)
 - [Installation](#installation)
   - [Alternative methods](#alternative-methods)
     - [Curl or Wget](#curl-or-wget)
@@ -49,6 +53,7 @@ graphical apps (X11/Wayland), and audio.
 - [Compatibility](compatibility.md)
   - [Supported container managers](compatibility.md#supported-container-managers)
   - [Host Distros](compatibility.md#host-distros)
+      - [Install on the Steamdeck](posts/steamdeck_guide.md)
   - [Containers Distros](compatibility.md#containers-distros)
 - [Usage](usage/usage.md)
   - [Outside the distrobox](usage/usage.md#outside-the-distrobox)
@@ -77,12 +82,15 @@ graphical apps (X11/Wayland), and audio.
   - [Duplicate an existing distrobox](useful_tips.md#duplicate-an-existing-distrobox)
   - [Export to the host](useful_tips.md#export-to-the-host)
   - [Execute commands on the host](useful_tips.md#execute-commands-on-the-host)
+  - [Resolve "Error cannot open display: :0"](useful_tips.md#resolve-error-cannot-open-display-0)
   - [Enable SSH X-Forwarding when SSH-ing in a distrobox](useful_tips.md#enable-ssh-x-forwarding-when-ssh-ing-in-a-distrobox)
   - [Using init system inside a distrobox](useful_tips.md#using-init-system-inside-a-distrobox)
   - [Using Docker inside a Distrobox](useful_tips.md#using-docker-inside-a-distrobox)
   - [Using Podman inside a Distrobox](useful_tips.md#using-podman-inside-a-distrobox)
   - [Using LXC inside a Distrobox](useful_tips.md#using-lxc-inside-a-distrobox)
   - [Using Waydroid inside a Distrobox](useful_tips.md#using-waydroid-inside-a-distrobox)
+    - [Manual Installation](useful_tips.md#manual-installation)
+    - [Automated Installation](useful_tips.md#automated-installation)
   - [Using host's Podman or Docker inside a Distrobox](useful_tips.md#using-hosts-podman-or-docker-inside-a-distrobox)
   - [Using distrobox as main cli](useful_tips.md#using-distrobox-as-main-cli)
   - [Using a different architecture](useful_tips.md#using-a-different-architecture)

docs/compatibility.md

@@ -65,19 +65,14 @@ Distrobox has been successfully tested on:
 | openSUSE | Leap 15.4 <br> Leap 15.3 <br> Leap 15.2 | Packages are available [here](https://software.opensuse.org/download/package?package=distrobox&project=home%3Adfaggioli%3Amicroos-desktop) (thanks [dfaggioli](https://github.com/dfaggioli)!).<br> To install on openSUSE Leap 15, Use the following repository links in the `zypper addrepo` command: [15.4](https://download.opensuse.org/repositories/home:dfaggioli:microos-desktop/15.4/home:dfaggioli:microos-desktop.repo), [15.3](https://download.opensuse.org/repositories/home:dfaggioli:microos-desktop/15.3/home:dfaggioli:microos-desktop.repo), [15.2](https://download.opensuse.org/repositories/home:dfaggioli:microos-desktop/15.2/home:dfaggioli:microos-desktop.repo). Then: <br>  `zypper refresh && zypper install distrobox`. <br> `Podman` under SUSE Leap, cannot initialize correctly the containers managed by ``distrobox`` until [this openSUSE bug](https://bugzilla.opensuse.org/show_bug.cgi?id=1199871) is fixed, or ``podman`` logging is configured properly. |
 | openSUSE | Tumbleweed <br> MicroOS | `distrobox` is available in default repos (thanks [dfaggioli](https://github.com/dfaggioli)!) <br> For Tumbleweed, do: `zypper install distrobox`. <br> For MicroOS, **distrobox is installed by default**. |
 | SUSE Linux Enterprise Server | 15&nbsp;Service&nbsp;Pack&nbsp;4 <br> 15&nbsp;Service&nbsp;Pack&nbsp;3 <br> 15&nbsp;Service&nbsp;Pack&nbsp;2 | Same procedure as the one for openSUSE (Leap, respective versions, of course). Use the following repository links in the `zypper addrepo` command: [SLE-15-SP4](https://download.opensuse.org/repositories/home:dfaggioli:microos-desktop/15.4/home:dfaggioli:microos-desktop.repo), [SLE-15-SP3](https://download.opensuse.org/repositories/home:dfaggioli:microos-desktop/15.3/home:dfaggioli:microos-desktop.repo), [SLE-15-SP4](https://download.opensuse.org/repositories/home:dfaggioli:microos-desktop/SLE_15_SP2/home:dfaggioli:microos-desktop.repo). Then: <br>  `zypper refresh && zypper install distrobox`. <br> `Podman` under SUSE Leap, cannot initialize correctly the containers managed by ``distrobox`` until [this openSUSE bug](https://bugzilla.opensuse.org/show_bug.cgi?id=1199871) is fixed, or ``podman`` logging is configured properly. |
-| SteamOS 3 | | You can use `steamos-readonly disable` and follow `Arch Linux` instructions. This will **NOT** survive updates.<br>Alternatively you can follow the [Install Podman in a static manner](posts/install_podman_static.md) guide, this will install it in your $HOME and it will survive updates.|
+| SteamOS | | You can use `steamos-readonly disable` and follow `Arch Linux` instructions. This will **NOT** survive updates.<br>Alternatively you can follow the [Install Podman in a static manner](posts/install_podman_static.md) guide, this will install it in your $HOME and it will survive updates. |
 | RedHat | 8 <br> 9  | `distrobox` is available in epel repos. (thanks [alcir](https://github.com/alcir)!) |
 | Ubuntu | 18.04 <br> 20.04 <br> 22.04 <br> 22.10 <br> 23.04 <br>| Older versions based on 20.04 or earlier may need external repos to install newer Podman and Docker releases. <br> Derivatives like Pop_OS!, Mint and Elementary OS should work the same. <br> [Now PPA available!](https://launchpad.net/~michel-slm/+archive/ubuntu/distrobox), also `distrobox` is available in default repos from `22.10` onward (thanks [michel-slm](https://github.com/michel-slm)!)  |
 | Vanilla OS | 22.10 <br> Orchid | `distrobox` should be installed in the home directory using the official script |
 | Void Linux | glibc | |
 
 ### Compatibility notes
 
-If your container is not able to connect to your host xserver, make sure to
-install `xhost` on the host machine and run `xhost +si:localuser:$USER`.
-If you wish to enable this functionality on future reboots add it to your `~/.xinitrc`
-or somewhere else tailored to your use case where it would be ran on every startup.
-
 ### Non shared mounts
 
 Note also that in some distributions, root filesystem is **not** mounted as a shared mount,

docs/posts/install_podman_static.md

@@ -3,12 +3,11 @@
 If on your distribution (eg. SteamOS) can be difficult to install something and keep it
 between updates, then you could use this script to install `podman` in your `$HOME`.
 
-Installing distrobox in HOME is quite straightforward:
-
-1. Install `distrobox` in your HOME following the `curl` instructions:
-   - [INSTALL](../README.md#curl-or-wget)
-2. Add the Path you've chosen to install to your PATH (by default it's `$HOME/.local/bin`.
+1. Add the Path you've chosen to install to your PATH (by default it's `$HOME/.local/bin`.
    - [See here how to do it](https://www.howtogeek.com/658904/how-to-add-a-directory-to-your-path-in-linux/)
+2. Ensure you have /etc/subuid and /etc/subgid, if you don't do:
+   - `sudo touch /etc/subuid /etc/subgid`
+   - `sudo usermod --add-subuid 100000-165535 --add-subgid 100000-165535 $USER`
 
 This is particularly indicated also for completely *sudoless* setups, where you don't
 have any superuser access to the system, like for example company provided computers.

docs/posts/steamdeck_guide.md

@@ -0,0 +1,54 @@
+# Install Distrobox on the Steamdecl
+
+To install Distrobox on the steamdeck, we can install both `podman` and `distrobox`
+inside the `$HOME` so that containers will survive updates.
+
+## Install Podman
+
+To install podman, [refer to the install guide](install_podman_static.md#):
+
+- Download the latest release of `podman-launcher` and place it in your home and rename it to `podman`, this example will use `~/.local/bin`
+- Setup `deck` user password using:
+  - `passwd`
+- Setup `deck` user uidmap
+   - `sudo touch /etc/subuid /etc/subgid`
+   - `sudo usermod --add-subuid 100000-165535 --add-subgid 100000-165535 deck`
+
+And `podman` is ready to use!
+
+## Install Distrobox
+
+Installing distrobox in HOME is quite straightforward:
+
+- Install `distrobox` in your HOME following the `curl` instructions:
+   - [INSTALL](../README.md#curl-or-wget)
+
+## Setup ~/.distroboxrc
+
+We need to add some tweaks to our `~/.distroboxrc` to have GUI and Audio working
+correctly in SteamOS
+
+Ensure your `~/.distroboxrc` has this content:
+
+```sh
+xhost +si:localuser:$USER
+export PIPEWIRE_RUNTIME_DIR=/dev/null
+export PATH=$PATH:$HOME/.local/bin
+```
+
+This will force the use of `pulseaudio` inside the container, right now `pipewire`
+is not working correctly inside the container, and it's a SteamOS specific issue.
+
+`xhost` is needed to ensure the graphical apps can talk to the Xwayland session.
+
+`PATH` is needed to ensure distrobox can find the `podman` binary we previously
+downloaded.
+
+# Start using it!
+
+You can now start using `distrobox` on the deck, open the terminal and go:
+
+`distrobox create && distrobox enter`
+
+Refer to the [quickstart guide](../README.md#quick-start) and to the [usage docs](../usage/usage.md)
+And don't forget the [useful tips](../useful_tips.md)!

docs/useful_tips.md

@@ -9,12 +9,15 @@
   - [Duplicate an existing distrobox](#duplicate-an-existing-distrobox)
   - [Export to the host](#export-to-the-host)
   - [Execute commands on the host](#execute-commands-on-the-host)
+  - [Resolve "Error cannot open display: :0"](#resolve-error-cannot-open-display-0)
   - [Enable SSH X-Forwarding when SSH-ing in a distrobox](#enable-ssh-x-forwarding-when-ssh-ing-in-a-distrobox)
   - [Using init system inside a distrobox](#using-init-system-inside-a-distrobox)
   - [Using Docker inside a Distrobox](#using-docker-inside-a-distrobox)
   - [Using Podman inside a Distrobox](#using-podman-inside-a-distrobox)
   - [Using LXC inside a Distrobox](#using-lxc-inside-a-distrobox)
   - [Using Waydroid inside a Distrobox](#using-waydroid-inside-a-distrobox)
+    - [Manual Installation](#manual-installation)
+    - [Automated Installation](#automated-installation)
   - [Using host's Podman or Docker inside a Distrobox](#using-hosts-podman-or-docker-inside-a-distrobox)
   - [Using distrobox as main cli](#using-distrobox-as-main-cli)
   - [Using a different architecture](#using-a-different-architecture)
@@ -198,6 +201,18 @@ Distrobox supports exporting to the host either binaries or applications.
 
 You can check this little post about [executing commands on the host.](posts/execute_commands_on_host.md)
 
+## Resolve "Error cannot open display: :0"
+
+If your container is not able to connect to your host xserver, make sure to
+install `xhost` on the host machine and run `xhost +si:localuser:$USER`.
+If you wish to enable this functionality on future reboots add the above command
+to your `~/.distroboxrc`
+
+```console
+-$ cat ~/.distroboxrc
+xhost +si:localuser:$USER`
+```
+
 ## Enable SSH X-Forwarding when SSH-ing in a distrobox
 
 SSH X-forwarding by default will not work because the container hostname is