diff --git a/README.md b/README.md index 1b4f8bfa..c3af8d12 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ # GOW - Games on Whales [![Discord](https://img.shields.io/discord/856434175455133727.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://discord.gg/kRGUDHNHt2) -Stream games (and GUI) over Docker with HW acceleration and low latency +Stream games (and GUI) running on Docker with HW acceleration and low latency! -![Screenshot of GOW running](screen/GOW-running.jpg) +Read more on our [documentation](docs/README.md) + +![Screenshot of GOW running](docs/img/GOW-running.jpg) ## Quickstart @@ -13,134 +15,8 @@ docker-compose pull docker-compose up ``` -Connect over Moonlight by manually adding the IP address of the PC running the Docker container. To validate the PIN you can use the Sunshine web interface (at `https://:47990/` username: sunshine, password is auto generated on startup check the docker logs.) or directly calling: `curl :47989/pin/`. - -From Moonlight open the `Desktop` app, from there you should be able to see your X11 apps running! - - -## RetroArch first time configuration - -> Using the keyboard you can move using the arrows and get back to the previous menu by pressing backspace - -From the **Main Menu** > **Online Updater** select: -- Update Core Info Files -- Update assets - -Press `F` to toggle fullscreen. +Wait, are you seriously running code from the internet? +It's dangerous out there! Make sure to checkout the [documentation](docs/README.md) first! -## GPU HW acceleration - -> **TESTING**: the following is still under development - -### Nvidia GPUs with `nouveau` drivers - -Make sure that the host doesn't use proprietary drivers but it's using the open source `nouveau` drivers. -``` -sudo lshw -class video | grep driver= - configuration: driver=nouveau latency=0 -``` - -Double check that the GPU card is correctly listed under `/dev/dri/`: -``` -ls -la /dev/dri/ -total 0 -drwxr-xr-x 3 root root 100 Jun 20 09:47 . -drwxr-xr-x 17 root root 3100 Jun 20 10:33 .. -drwxr-xr-x 2 root root 80 Jun 20 09:47 by-path -crw-rw---- 1 root video 226, 0 Jun 20 09:47 card0 -crw-rw---- 1 root render 226, 128 Jun 20 09:47 renderD128 -``` - -### Nvidia GPUs with proprietary drivers - -You can see if your host is using the proprietary driver using `lshw`: -```console -$ lshw -class video | grep -i driver - configuration: driver=nvidia latency=0 -``` - -In order to make use of your GPU inside docker containers, you'll need to set up the [NVIDIA Container Toolkit](https://github.com/NVIDIA/nvidia-docker). - -Once that's done, you can run the container, you should add the following ENV variables to the docker-compose file - -```yaml -environment: - NVIDIA_VISIBLE_DEVICES: GPU-[uuid] # Replace [uuid] (see the instructions) - NVIDIA_DRIVER_CAPABILITIES: utility,graphics,video,display -``` - -To get the correct UUID for your GPU, use the `nvidia-container-cli` command: -```console -$ sudo nvidia-container-cli --load-kmods info -NVRM version: [version] -CUDA version: 11.3 - -Device Index: 0 -Device Minor: 0 -Model: NVIDIA GeForce [model] -Brand: GeForce -GPU UUID: GPU-[uuid] -Bus Location: 00000000:0a:00.0 -Architecture: 7.5 -``` -##### Xorg drivers - -Although the NVIDIA Container Toolkit automatically provides most of the drivers needed to use the GPU inside a container, Xorg is _not_ officially supported. This means that the runtime will not automatically map in the specific drivers needed by Xorg. - -There are two libraries needed by Xorg: `nvidia_drv.so` and `libglxserver_nvidia.so.[version]`. It is preferred to map these into the container as a bind volume from the host, because this guarantees that the version will exactly match between the container and the host. Locate the two modules and add a section like this to the `xorg` service in your `docker-compose.yml`: -```yaml -volumes: - - /path/to/nvidia_drv.so:/nvidia/xorg/nvidia_drv.so:ro - - /path/to/libglxserver_nvidia.so.[version]:/nvidia/xorg/libglxserver_nvidia.so:ro -``` - -Be sure to replace `[version]` with the correct version number from the `nvidia-container-cli` command above. - -Some common locations for `nvidia_drv.so` include: - * `/usr/lib64/xorg/modules/drivers/` (Unraid) - * `/usr/lib/x86_64-linux-gnu/nvidia/xorg/` (Ubuntu 20.04) - -Some common locations for `libglxserver_nvidia.so.[version]` include: - * `/usr/lib64/xorg/modules/extensions/` (Unraid) - * `/usr/lib/x86_64-linux-gnu/nvidia/xorg/` (Ubuntu 20.04) - -If you don't want to do this, or if you can't find the driver on your host for some reason, the container will attempt to install the correct version for you automatically. However, there is no guarantee that it will be able to find a version that exactly matches the driver version on your host. - -If for some reason you want to skip the entire process and just assume the driver is already installed, you can do that too: -```yaml -environment: - SKIP_NVIDIA_DRIVER_CHECK: 1 -``` - -## Troubleshooting - -You can access Retroarch logs at `~/retroarch/retroarch.log` - -### Error: Could not create Sunshine Mouse: No such file or directory - -Make sure that `/dev/uinput/` is present in the host and that it does have the correct permissions: - -```console -ls -la /dev/uinput -crw-rw---- 1 $USER input 10, 223 Jun 9 08:57 /dev/uinput # Check that $USER is not root but your current user -``` - -Try following this: https://github.com/chrippa/ds4drv/issues/93#issuecomment-265300511 -(On Debian I had to modify `/etc/modules-load.d/modules.conf`, adding `/etc/modules-load.d/uinput.conf` didn't trigger anything to me) - -Non permanent fix: -```console -sudo chmod 0660 /dev/uinput -``` - -## Docker build - -You can either build the docker image or use the pre-built one available at [DockerHub](https://hub.docker.com/u/gameonwhales). - -To build it locally run: - -```console -docker-compose build -``` diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..6ef449bc --- /dev/null +++ b/docs/README.md @@ -0,0 +1,33 @@ +# Documentation + +If something is missing here feel free to reach us on [Discord](https://discord.gg/kRGUDHNHt2) or open up a [discussion](https://github.com/games-on-whales/gow/discussions/new) here on Github. + +## What is Games on Whales? + + - [Overview](overview.md) + - [Components overview](components-overview.md) + - [Roadmap](roadmap.md) + +## Running GOW + + - GNU/Linux + - I have a headless server (CLI only) + - [Debian/Ubuntu](debian-instructions.md) + - [Unraid](https://github.com/games-on-whales/unraid-plugin) + - [I already have a Desktop environment](desktop-instructions.md) + - [Windows](https://github.com/games-on-whales/gow/issues/13) + - OSX + +## HW Acceleration + + - [Nvidia GPU](nvidia.md) + - [iGPU](https://github.com/games-on-whales/gow/issues/21) + +## Troubleshooting + + - [Common errors](troubleshooting.md) + +## Contributing + + - [How can I help?](contributing.md) + - [Building manually](docker-build.md) \ No newline at end of file diff --git a/docs/components-overview.md b/docs/components-overview.md new file mode 100644 index 00000000..69105070 --- /dev/null +++ b/docs/components-overview.md @@ -0,0 +1,57 @@ +# Components Overview + +Make sure to read first the [overview](overview.md) section to get a grasp on what's the idea behind GOW. + +

+ +

+ +GOW is a composition of Docker containers that enable users to stream graphical applications to Moonlight clients. + +We wrapped each individual software with the necessary dependencies into a single Docker image and we use [`docker-compose`](https://docs.docker.com/compose/) in order to manage the composition. + +## Sunshine + +[Sunshine](https://github.com/loki-47-6F-64/sunshine) is the heart of this system: it's the streaming host and it's in charge of: + - Encoding the graphical environment (`Xorg`) and audio (`PulseAudio`) into a video that will be streamed to [Moonlight](https://moonlight-stream.org/) clients + - This process can be HW accelerated using [`VAAPI`](https://en.wikipedia.org/wiki/Video_Acceleration_API) on compatible HW + - Translating remote inputs into local input devices (aka: keyboards, mouse, joypad) + - This is achieved by using the [`uinput`](https://www.kernel.org/doc/html/v4.12/input/uinput.html) kernel module + +### uinput + +Uinput makes possible to emulate virtual devices. It's required by Sunshine and it's the one and only real requirement that we need in the host machine kernel. + +Most Linux distributions already ships it and you'll find it already there if you use Ubuntu or Debian for example. + +If it's not there already, since it's part of the Linux kernel, it might be difficult to compile it from scratch. We try to add support for platforms who don't have it, for example, [we are working on a plugin for Unraid](https://github.com/games-on-whales/unraid-plugin). + +If you have issues with inputs (mouse, joypad) while streaming using GOW, it's very likely that something is wrong with `uinput` + + +## Xorg + PulseAudio + +This two components are in charge respectively of *Display* and *Audio*. + +- If your OS comes with a [desktop environment](https://en.wikipedia.org/wiki/Desktop_environment) already, you can use that instead of running it over Docker. +- If you are running a [headless](https://en.wikipedia.org/wiki/Headless_computer) system you'll need to run them in order to run graphical applications, you can use our Docker images for that. + +While PulseAudio runs just fine without a real sound device, Xorg can (and should) be HW accelerated using a GPU. That's the main reason why we choose Xorg over [`Xvfb`](https://en.wikipedia.org/wiki/Xvfb), while it's more complicated to run the full Xorg server the benefits of having HW acceleration are too big to be dismissed. + +## GUIs + +Graphical applications can run easily on top of Xorg and PulseAudio, that's how most desktop environment works! + +

+ +

+ +Sharing [sockets](https://en.wikipedia.org/wiki/Unix_domain_socket) between containers is the mechanism that enables us to have proper isolation. Instead of having a big single Docker image which installs and runs all these softwares together we can decouple them and share only a communication channel. + +This means that it's very simple to make a Docker container of any given GUI application and that same container will work both on **GOW** or on a normal *Desktop Environment*, enabling users to have a high degree of freedom on how to use them. + +## GPU + +A GPU is not required to run any of this, but it's highly recommended. + +Sharing a GPU across Docker containers is possible and it's generally done by sharing the [DRM devices (`/dev/dri/cardX`)](https://en.wikipedia.org/wiki/Direct_Rendering_Manager). As always there are exceptions and we have specific instructions for [Nvidia cards](nvidia.md). \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..09f6d4e3 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,11 @@ +# How can I help? + +:tada: First off, thanks for taking the time to contribute! :tada: + +There are many ways to contribute to this project! + +Just by running it and reporting issues (or even letting us know everything works out of the box) you are helping us! + +You don't have to code or understand all the little details of how everything work, helping us mantaining and expanding the documentation is another great way to help. Asking questions in the public [discussion board](https://github.com/games-on-whales/gow/discussions) is another great way to share knowledge for others. + +Feel free to join our [discord server](https://discord.gg/kRGUDHNHt2) if you have any question, if you need any help, or you would like to join us on our journey! \ No newline at end of file diff --git a/docs/debian-instructions.md b/docs/debian-instructions.md new file mode 100644 index 00000000..5c360ec3 --- /dev/null +++ b/docs/debian-instructions.md @@ -0,0 +1,21 @@ +# Debian/Ubuntu instructions + +Make sure to checkout the [Overview](overview.md) first. + +## Quickstart + +```console +git clone https://github.com/games-on-whales/gow.git +cd gow +docker-compose pull +docker-compose up +``` + +Connect over Moonlight by manually adding the IP address of the PC running the Docker container. To validate the PIN you can use the Sunshine web interface (at `https://:47990/` username: sunshine, password is auto generated on startup check the docker logs.) or directly calling: `curl :47989/pin/`. + +From Moonlight open the `Desktop` app, from there you should be able to see your X11 apps running! + +## Next steps + + - Checkout how to [configure RetroArch](retroarch-first-start.md) + - Head [back to the Documentation](README.md) to configure and use your GPU (if you have one) diff --git a/docs/desktop-instructions.md b/docs/desktop-instructions.md new file mode 100644 index 00000000..8445b9dd --- /dev/null +++ b/docs/desktop-instructions.md @@ -0,0 +1,3 @@ +# Desktop instructions + +There's not much content in here, uh? \ No newline at end of file diff --git a/docs/docker-build.md b/docs/docker-build.md new file mode 100644 index 00000000..a1a4364f --- /dev/null +++ b/docs/docker-build.md @@ -0,0 +1,9 @@ +# Docker build + +You can either build the docker image or use the pre-built one available at [DockerHub](https://hub.docker.com/u/gameonwhales). + +To build it locally run: + +```console +docker-compose build +``` \ No newline at end of file diff --git a/screen/GOW-running.jpg b/docs/img/GOW-running.jpg similarity index 100% rename from screen/GOW-running.jpg rename to docs/img/GOW-running.jpg diff --git a/docs/img/gow-diagram.svg b/docs/img/gow-diagram.svg new file mode 100644 index 00000000..270c4d53 --- /dev/null +++ b/docs/img/gow-diagram.svg @@ -0,0 +1,3 @@ + + +
GOW
GOW
Xorg
Xorg
PulseAudio
PulseAudio
Sunshine
Sunshine
RetroArch
RetroArch
Firefox
Firefox
Docker
Docker
Kernel
Kernel
uinput
uinput
DMR
DMR
Hardware
Hardware
GPU
GPU
OS
OS
Moonlight
MoonlightViewer does not support full SVG 1.1 \ No newline at end of file diff --git a/docs/img/gow-logo.png b/docs/img/gow-logo.png new file mode 100644 index 00000000..827cd26b Binary files /dev/null and b/docs/img/gow-logo.png differ diff --git a/docs/img/gui-overview.svg b/docs/img/gui-overview.svg new file mode 100644 index 00000000..06282b09 --- /dev/null +++ b/docs/img/gui-overview.svg @@ -0,0 +1,3 @@ + + +
X11 socket
X11 socket
Xorg
Xorg
Audio socket
Audio socket
PulseAudio
PulseAudio
Remote inputs
Remote inputs
Sunshine
Sunshine
Firefox
FirefoxViewer does not support full SVG 1.1 \ No newline at end of file diff --git a/docs/nvidia.md b/docs/nvidia.md new file mode 100644 index 00000000..4e400874 --- /dev/null +++ b/docs/nvidia.md @@ -0,0 +1,84 @@ +# GPU HW acceleration + +> **TESTING**: the following is still under development + +## Nvidia GPUs with `nouveau` drivers + +Make sure that the host doesn't use proprietary drivers but it's using the open source `nouveau` drivers. +``` +sudo lshw -class video | grep driver= + configuration: driver=nouveau latency=0 +``` + +Double check that the GPU card is correctly listed under `/dev/dri/`: +``` +ls -la /dev/dri/ +total 0 +drwxr-xr-x 3 root root 100 Jun 20 09:47 . +drwxr-xr-x 17 root root 3100 Jun 20 10:33 .. +drwxr-xr-x 2 root root 80 Jun 20 09:47 by-path +crw-rw---- 1 root video 226, 0 Jun 20 09:47 card0 +crw-rw---- 1 root render 226, 128 Jun 20 09:47 renderD128 +``` + +## Nvidia GPUs with proprietary drivers + +You can see if your host is using the proprietary driver using `lshw`: +```console +$ lshw -class video | grep -i driver + configuration: driver=nvidia latency=0 +``` + +In order to make use of your GPU inside docker containers, you'll need to set up the [NVIDIA Container Toolkit](https://github.com/NVIDIA/nvidia-docker). + +Once that's done, you can run the container, you should add the following ENV variables to the docker-compose file + +```yaml +environment: + NVIDIA_VISIBLE_DEVICES: GPU-[uuid] # Replace [uuid] (see the instructions) + NVIDIA_DRIVER_CAPABILITIES: utility,graphics,video,display +``` + +To get the correct UUID for your GPU, use the `nvidia-container-cli` command: +```console +$ sudo nvidia-container-cli --load-kmods info +NVRM version: [version] +CUDA version: 11.3 + +Device Index: 0 +Device Minor: 0 +Model: NVIDIA GeForce [model] +Brand: GeForce +GPU UUID: GPU-[uuid] +Bus Location: 00000000:0a:00.0 +Architecture: 7.5 +``` + +### Xorg drivers + +Although the NVIDIA Container Toolkit automatically provides most of the drivers needed to use the GPU inside a container, Xorg is _not_ officially supported. This means that the runtime will not automatically map in the specific drivers needed by Xorg. + +There are two libraries needed by Xorg: `nvidia_drv.so` and `libglxserver_nvidia.so.[version]`. It is preferred to map these into the container as a bind volume from the host, because this guarantees that the version will exactly match between the container and the host. Locate the two modules and add a section like this to the `xorg` service in your `docker-compose.yml`: +```yaml +volumes: + - /path/to/nvidia_drv.so:/nvidia/xorg/nvidia_drv.so:ro + - /path/to/libglxserver_nvidia.so.[version]:/nvidia/xorg/libglxserver_nvidia.so:ro +``` + +Be sure to replace `[version]` with the correct version number from the `nvidia-container-cli` command above. + +Some common locations for `nvidia_drv.so` include: + * `/usr/lib64/xorg/modules/drivers/` (Unraid) + * `/usr/lib/x86_64-linux-gnu/nvidia/xorg/` (Ubuntu 20.04) + +Some common locations for `libglxserver_nvidia.so.[version]` include: + * `/usr/lib64/xorg/modules/extensions/` (Unraid) + * `/usr/lib/x86_64-linux-gnu/nvidia/xorg/` (Ubuntu 20.04) + +If you don't want to do this, or if you can't find the driver on your host for some reason, the container will attempt to install the correct version for you automatically. However, there is no guarantee that it will be able to find a version that exactly matches the driver version on your host. + +If for some reason you want to skip the entire process and just assume the driver is already installed, you can do that too: +```yaml +environment: + SKIP_NVIDIA_DRIVER_CHECK: 1 +``` \ No newline at end of file diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 00000000..8ca4ef7e --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,32 @@ +# Overview + + + +**Games on Whales (GOW)** let's you stream games (and GUI) running on Docker with HW acceleration and low latency. + +The basic idea is that a [server](https://en.wikipedia.org/wiki/Server_(computing)) can stream games to clients the same way you will play a video on Youtube. There are lots of supported clients already like: your phone, your laptop, or even a Nintendo Switch! + +A server is not necessary a [gigantic beast of a machine](https://upload.wikimedia.org/wikipedia/commons/6/69/Wikimedia_Foundation_Servers-8055_35.jpg), it can be: a laptop, a normal desktop machine, or even something smaller and compact like a Raspberry PI ([in theory](https://github.com/games-on-whales/gow/issues/20)). Generally, you should be able to pick any OS that supports [Docker](https://en.wikipedia.org/wiki/Docker_(software) and start using GOW! + +## How does it work? + +We bring together a few different components in order to achieve that: + + - [Moonlight](https://moonlight-stream.org/): an open source implementation of NVIDIA's GameStream protocol. You can stream your collection of PC games from your GameStream-compatible PC to any supported device and play them remotely. + + - [Sunshine](https://github.com/loki-47-6F-64/sunshine): an opensource Gamestream host for Moonlight. This gives us the ability stream from a Linux box since it's not tied to the proprietary Nvidia GameStream (Windows only and not opensource). + + - [Docker](https://en.wikipedia.org/wiki/Docker_(software)): the platform that we use in order to deliver software packages (called containers) that you can easily run without having to manually install and configure everything. + + - [Xorg](https://en.wikipedia.org/wiki/X.Org_Server): The window system that we use in order to manage and display graphical applications ([GUI](https://en.wikipedia.org/wiki/Graphical_user_interface)) + + - [PulseAudio](https://en.wikipedia.org/wiki/PulseAudio): The software that will manage audio for our GUIs + + - [RetroArch](https://en.wikipedia.org/wiki/RetroArch): An open source, crossplatform frontend for emulators, game engines and much more! + +

+ +

+ + Head over to the [components overview](components-overview.md) if you are interested in how these bunch of softwares are tied together by GOW + diff --git a/docs/retroarch-first-start.md b/docs/retroarch-first-start.md new file mode 100644 index 00000000..cc11c494 --- /dev/null +++ b/docs/retroarch-first-start.md @@ -0,0 +1,9 @@ +# RetroArch first time configuration + +> Using the keyboard you can move using the arrows and get back to the previous menu by pressing backspace + +From the **Main Menu** > **Online Updater** select: +- Update Core Info Files +- Update assets + +Press `F` to toggle fullscreen. \ No newline at end of file diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 00000000..6e5ff1d9 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,13 @@ +# Roadmap + +We are in a proof of concept phase right now, so far we have achieved the followings: + - we know *it's possible* to run HW accelerated games on Docker + - we have working environments in `Debian` and `Unraid` with and without a GPU + + +We would like to achieve the followings: + - make a general set of Docker containers that can run any GUI app (as long as it can run on Docker). + - make a *launcher app* that will let users start/stop other GUI containers *easily*. + - This will be possible by passing the Docker socket. + - support as much platforms as we can. + - make a great documentation so that anybody can understand and learn from this project. \ No newline at end of file diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..7c728930 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,20 @@ +# Troubleshooting + +You can access Retroarch logs at `~/retroarch/retroarch.log` + +### Error: Could not create Sunshine Mouse: No such file or directory + +Make sure that `/dev/uinput/` is present in the host and that it does have the correct permissions: + +```console +ls -la /dev/uinput +crw-rw---- 1 $USER input 10, 223 Jun 9 08:57 /dev/uinput # Check that $USER is not root but your current user +``` + +Try following this: https://github.com/chrippa/ds4drv/issues/93#issuecomment-265300511 +(On Debian I had to modify `/etc/modules-load.d/modules.conf`, adding `/etc/modules-load.d/uinput.conf` didn't trigger anything to me) + +Non permanent fix: +```console +sudo chmod 0660 /dev/uinput +``` \ No newline at end of file