From 042347222fb87cb25face6ab966d2b0802084527 Mon Sep 17 00:00:00 2001 From: Peter Cai Date: Sun, 31 Mar 2024 10:36:18 -0400 Subject: [PATCH] Add a README for Dobu --- README.md | 131 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4bb45b6 --- /dev/null +++ b/README.md @@ -0,0 +1,131 @@ +Dobu +--- + +This is a collection of scripts and corresponding container images to run desktop Linux applications +(mainly games) in isolated environments using unprivileged (rootless) Podman. + +Unlike Distrobox, Dobu uses exclusively pre-defined `Containerfile`s (`Dockerfile`s) and does not support +ad-hoc containers. All applications are defined using `Containerfile`s under the `apps/` directory. +Also unlike Distrobox, Dobu does not share everything accessible through the host graphics environment with +application containers. By default, Dobu only allows access to the following: + +- Wayland / Xorg proxied through [sommelier](https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/main/vm_tools/sommelier/) + - This gives containers effectively a separate Wayland subcompositor with its own Xwayland server, + mitigating risks associated with sharing a desktop session +- DRI render nodes (for GL acceleration) +- PulseAudio server + - This should ideally be proxied too like Wayland / Xorg, but currently no ideal implementation is known +- A user-defined, isolated, per-container `$HOME` directory +- Direct `/dev/input` access can be optionally granted + +Requirements +--- + +- A __Wayland__ compositor: this is required for `sommelier` +- Unprivileged user namespaces support + - This is to support Podman and some applications which require further namespacing inside the containers + - Unprivileged user namespaces will be blocked by default inside application containers unless otherwise + specified. +- Rootless Podman +- A PulseAudio-compatible audio server + +Setup +--- + +Scripts here expect to be run straight from the repository. Before running any application, you will need to +build the `sommelier` image first, as it is run from its own isolated container too. + +```shell +$ ./build-image.sh deps/sommelier +``` + +Then, take a look at `config-default.sh`, where some configurable options are located. This includes the base +path to `$HOME` directories for containers, and whether to allow direct `/dev/input` to some containers, etc. +If there is an option you would like to override, create a `config.sh` and include the override options there. + +You should now be ready to run an application. Take a look at `apps/`, choose an application to run, and build +its image (using `prismlauncher` as an example): + +```shell +$ ./build-image.sh apps/prismlauncher +$ ./dobu-run.sh apps/prismlauncher +``` + +Instead of manually executing `./dobu-run.sh` every time, you could also generate a desktop shortcut: + +```shell +$ ./create-shortcut.sh apps/prismlauncher +``` + +Note that this shortcut is created on a best-effort basis. Not all features are supported, but you should at +least be able to launch an application through the shortcut. + +Adding an Application +--- + +Adding an application should in general be straightforward if you are familiar with `Containerfile`s / `Dockerfile`s. +You can use existing applications under `apps/` as a template. + +In general, all applications should use a base image available under `deps/`. Currently, this means either +`deps/base-archlinux`, tagged `dobu/deps-base-archlinux` when built, or `deps/base-ubuntu-jammy`, tagged +`dobu/deps-base-ubuntu-jammy` when built. + +A `Containerfile` for a Dobu application looks in general like the following: + +```Dockerfile +FROM dobu/deps-base-:latest + +RUN + +# This is IMPORTANT because Dobu assumes "user" to be the default unprivileged username inside +# the container. This username will be mapped to the host user ID when a container is started. +USER user + +# This is used by create-shortcut.sh to generate desktop entries outside of the container +LABEL net.typeblog.dobu.desktop_file_path="/path/to/desktop/file/in/container" +# If your application requires the use of unprivileged user namespaces even inside the +# container, set the following +# LABEL net.typeblog.dobu.unsafe_i_know_what_i_am_doing_allow_namespaces="true" + +ENTRYPOINT [ "/path/to/main/app/binary" ] +``` + +Then, run `./build-image.sh apps/your-app` to create an image. + +There is an additional `control` file that you could add in your app directory. Currently, there +are only a few supported options: + +```bash +# If your application image is based on an Arch Linux package, setting this would tell Dobu +# to set an argument UPSTREAM_VERSION to the version of the indicated Arch Linux package when +# building the application image. If you refer to this version somewhere in your Containerfile +# (it could be as simple as `ARG UPSTREAM_VERSION` near the start of your Containerfile), this +# would invalidate Podman's build cache whenever this version changes. This allows these images +# to be updated with a simple rebuild instead of having to manually bump some version code +# every time something updates. +# Note that you SHALL NOT depend on the exact value of this UPSTREAM_VERSION variable. It should +# ONLY be used as a cache invalidation mechanism. +INVALIDATE_CACHE_UPSTREAM_ARCHLINUX="some/package" +# Same thing, but for GitHub upstreams +INVALIDATE_CACHE_UPSTREAM_GITHUB="some/package" +# or Ubuntu +INVALIDATE_CACHE_UPSTREAM_UBUNTU="some/package" +``` + +Limitations +--- + +- Dobu is currently created with x86\_64 and only x86\_64 in mind. +- Applications inside containers share the same UID as the host user. This is to make + file sharing easier (otherwise you have to either `sudo` or `podman unshare` all the time), + and to share things like the Sommelier socket and PulseAudio without making them + world-writable or `setfacl` hacks. +- PulseAudio socket is not isolated but shared directly. This could ideally be solved by + a proxy of PulseAudio similar to Sommelier for Wayland / Xorg. +- DBus is not shared at all into application containers. This means that input methods such + as Fcitx would not work through their traditional DBus interfaces, and status indicators + through `libappindicator` are broken (e.g. Steam). + - I do not have a plan to support DBus inside containers. In my opinion, many of these + limitations should be solved by Wayland protocols and be proxied through Sommelier. + Once compositors, input methods, and Sommelier all support the `text_input` suite of + protocols, they should work inside these containers.