diff --git a/docs/README.md b/docs/README.md index 00fd28c8b9..b5b0745e8f 100644 --- a/docs/README.md +++ b/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) diff --git a/docs/compatibility.md b/docs/compatibility.md index 3299aa9255..79c62e7ef4 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -65,7 +65,7 @@ Distrobox has been successfully tested on: | openSUSE | Leap 15.4
Leap 15.3
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)!).
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:
`zypper refresh && zypper install distrobox`.
`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
MicroOS | `distrobox` is available in default repos (thanks [dfaggioli](https://github.com/dfaggioli)!)
For Tumbleweed, do: `zypper install distrobox`.
For MicroOS, **distrobox is installed by default**. | | SUSE Linux Enterprise Server | 15 Service Pack 4
15 Service Pack 3
15 Service Pack 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:
`zypper refresh && zypper install distrobox`.
`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.
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.
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
9 | `distrobox` is available in epel repos. (thanks [alcir](https://github.com/alcir)!) | | Ubuntu | 18.04
20.04
22.04
22.10
23.04
| Older versions based on 20.04 or earlier may need external repos to install newer Podman and Docker releases.
Derivatives like Pop_OS!, Mint and Elementary OS should work the same.
[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
Orchid | `distrobox` should be installed in the home directory using the official script | @@ -73,11 +73,6 @@ Distrobox has been successfully tested on: ### 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, diff --git a/docs/posts/install_podman_static.md b/docs/posts/install_podman_static.md index 9f5e964cd9..cf83e4a77a 100644 --- a/docs/posts/install_podman_static.md +++ b/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. diff --git a/docs/posts/steamdeck_guide.md b/docs/posts/steamdeck_guide.md new file mode 100644 index 0000000000..464cd4039c --- /dev/null +++ b/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)! diff --git a/docs/useful_tips.md b/docs/useful_tips.md index 287255954d..a54fb4844c 100644 --- a/docs/useful_tips.md +++ b/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