Improve documentation for Intel and AMD installations

Steam-Headless · May 8, 2024 · 47f6f7a · 47f6f7a
1 parent 28c19ed
commit 47f6f7a
Show file tree

Hide file tree

Showing 6 changed files with 230 additions and 25 deletions.
diff --git a/docs/compose-files/.env b/docs/compose-files/.env
@@ -13,6 +13,9 @@ SHM_SIZE=2G
 ## HOME_DIR:
 ##      Description:    The path to the home directory on your host. Mounts to `/home/default` inside the container.
 HOME_DIR=/opt/container-data/steam-headless/home
+## SHARED_SOCKETS_DIR:
+##      Description:    Shared sockets such as pulse audio and X11.
+SHARED_SOCKETS_DIR=/opt/container-data/steam-headless/sockets
 ## GAMES_DIR:
 ##      Description:    The path to the games directory on your host. Mounts to `/mnt/games` inside the container.
 GAMES_DIR=/mnt/games
@@ -62,7 +65,7 @@ WEB_UI_MODE=vnc
 ENABLE_VNC_AUDIO=true
 ## PORT_NOVNC_WEB:
 ##      Description:        Configure the port to use for the WebUI.
-PORT_NOVNC_WEB=58083
+PORT_NOVNC_WEB=8083
 ## NEKO_NAT1TO1:
 ##      Description:        Configure nat1to1 for the neko WebUI if it is enabled by setting 'WEB_UI_MODE' to 'neko'.
 ##                          This will need to be the IP address of the host.
@@ -98,6 +101,11 @@ SUNSHINE_PASS=admin
 ##                          evdev events for Keyboard, Mouse, etc.
 ##      Supported Modes:    ['primary']
 ENABLE_EVDEV_INPUTS=true
+## FORCE_X11_DUMMY_CONFIG:
+##      Available Options:  ['true', 'false']
+##      Description:        Forces the installation of xorg.dummy.conf. This should be used when your output device does not have a monitor connected.
+##      Supported Modes:    ['primary']
+FORCE_X11_DUMMY_CONFIG=false
 
 # Nvidia specific config (not required for non Nvidia GPUs)
 ## NVIDIA_DRIVER_CAPABILITIES:

diff --git a/docs/compose-files/docker-compose.amd+intel.privileged.yml b/docs/compose-files/docker-compose.amd+intel.privileged.yml
@@ -0,0 +1,76 @@
+---
+version: "3.8"
+
+services:
+  steam-headless:
+    image: josh5/steam-headless:latest
+    restart: unless-stopped
+    ## NOTE: This config uses privileged to access to host to be able to access the required devices
+    privileged: true
+    shm_size: ${SHM_SIZE}
+    ipc: host # Could also be set to 'shareable'
+    ulimits:
+      nofile:
+        soft: 1024
+        hard: 524288
+
+    # NETWORK:
+    ## NOTE:  With this configuration, if we do not use the host network, then physical device input
+    ##        is not possible and your USB connected controllers will not work in steam games.
+    network_mode: host
+    hostname: ${NAME}
+    extra_hosts:
+      - "${NAME}:127.0.0.1"
+
+    # ENVIRONMENT:
+    ## Read all config variables from the .env file
+    environment:
+      # System
+      - TZ=${TZ}
+      - USER_LOCALES=${USER_LOCALES}
+      - DISPLAY=${DISPLAY}
+      # User
+      - PUID=${PUID}
+      - PGID=${PGID}
+      - UMASK=${UMASK}
+      - USER_PASSWORD=${USER_PASSWORD}
+      # Mode
+      - MODE=${MODE}
+      # Web UI
+      - WEB_UI_MODE=${WEB_UI_MODE}
+      - ENABLE_VNC_AUDIO=${ENABLE_VNC_AUDIO}
+      - PORT_NOVNC_WEB=${PORT_NOVNC_WEB}
+      - NEKO_NAT1TO1=${NEKO_NAT1TO1}
+      # Steam
+      - ENABLE_STEAM=${ENABLE_STEAM}
+      - STEAM_ARGS=${STEAM_ARGS}
+      # Sunshine
+      - ENABLE_SUNSHINE=${ENABLE_SUNSHINE}
+      - SUNSHINE_USER=${SUNSHINE_USER}
+      - SUNSHINE_PASS=${SUNSHINE_PASS}
+      # Xorg
+      - ENABLE_EVDEV_INPUTS=${ENABLE_EVDEV_INPUTS}
+      - FORCE_X11_DUMMY_CONFIG=${FORCE_X11_DUMMY_CONFIG}
+      # Nvidia specific config
+      - NVIDIA_DRIVER_CAPABILITIES=${NVIDIA_DRIVER_CAPABILITIES}
+      - NVIDIA_VISIBLE_DEVICES=${NVIDIA_VISIBLE_DEVICES}
+      - NVIDIA_DRIVER_VERSION=${NVIDIA_DRIVER_VERSION}
+
+    # VOLUMES:
+    volumes:
+      # The location of your home directory.
+      - ${HOME_DIR}/:/home/default/:rw
+
+      # The location where all games should be installed.
+      # This path needs to be set as a library path in Steam after logging in.
+      # Otherwise, Steam will store games in the home directory above.
+      - ${GAMES_DIR}/:/mnt/games/:rw
+
+      # The Xorg socket.
+      - ${SHARED_SOCKETS_DIR}/.X11-unix/:/tmp/.X11-unix/:rw
+
+      # Pulse audio socket.
+      - ${SHARED_SOCKETS_DIR}/pulse/:/tmp/pulse/:rw
+
+      # Input devices used for mouse and joypad support inside the container.
+      - /dev/input/:/dev/input/:ro
diff --git a/docs/compose-files/docker-compose.amd+intel.yml b/docs/compose-files/docker-compose.amd+intel.yml
@@ -0,0 +1,92 @@
+---
+version: "3.8"
+
+services:
+  steam-headless:
+    image: josh5/steam-headless:latest
+    restart: unless-stopped
+    shm_size: ${SHM_SIZE}
+    ipc: host # Could also be set to 'shareable'
+    ulimits:
+      nofile:
+        soft: 1024
+        hard: 524288
+    cap_add:
+      - NET_ADMIN
+      - SYS_ADMIN
+      - SYS_NICE
+    security_opt:
+      - seccomp:unconfined
+      - apparmor:unconfined
+
+    # NETWORK:
+    ## NOTE:  With this configuration, if we do not use the host network, then physical device input
+    ##        is not possible and your USB connected controllers will not work in steam games.
+    network_mode: host
+    hostname: ${NAME}
+    extra_hosts:
+      - "${NAME}:127.0.0.1"
+
+    # ENVIRONMENT:
+    ## Read all config variables from the .env file
+    environment:
+      # System
+      - TZ=${TZ}
+      - USER_LOCALES=${USER_LOCALES}
+      - DISPLAY=${DISPLAY}
+      # User
+      - PUID=${PUID}
+      - PGID=${PGID}
+      - UMASK=${UMASK}
+      - USER_PASSWORD=${USER_PASSWORD}
+      # Mode
+      - MODE=${MODE}
+      # Web UI
+      - WEB_UI_MODE=${WEB_UI_MODE}
+      - ENABLE_VNC_AUDIO=${ENABLE_VNC_AUDIO}
+      - PORT_NOVNC_WEB=${PORT_NOVNC_WEB}
+      - NEKO_NAT1TO1=${NEKO_NAT1TO1}
+      # Steam
+      - ENABLE_STEAM=${ENABLE_STEAM}
+      - STEAM_ARGS=${STEAM_ARGS}
+      # Sunshine
+      - ENABLE_SUNSHINE=${ENABLE_SUNSHINE}
+      - SUNSHINE_USER=${SUNSHINE_USER}
+      - SUNSHINE_PASS=${SUNSHINE_PASS}
+      # Xorg
+      - ENABLE_EVDEV_INPUTS=${ENABLE_EVDEV_INPUTS}
+      - FORCE_X11_DUMMY_CONFIG=${FORCE_X11_DUMMY_CONFIG}
+      # Nvidia specific config
+      - NVIDIA_DRIVER_CAPABILITIES=${NVIDIA_DRIVER_CAPABILITIES}
+      - NVIDIA_VISIBLE_DEVICES=${NVIDIA_VISIBLE_DEVICES}
+      - NVIDIA_DRIVER_VERSION=${NVIDIA_DRIVER_VERSION}
+
+    # DEVICES:
+    devices:
+      # Use the host fuse device [REQUIRED].
+      - /dev/fuse
+      # Add the host uinput device [REQUIRED].
+      - /dev/uinput
+      # Add AMD/Intel HW accelerated video encoding/decoding devices [REQUIRED].
+      # NOTE: See documentation for determining which devices to configure here if you have multiple GPUs
+      - /dev/dri/card1
+      - /dev/dri/renderD128
+    # Ensure container access to devices 13:*
+    device_cgroup_rules:
+      - 'c 13:* rmw'
+
+    # VOLUMES:
+    volumes:
+      # The location of your home directory.
+      - ${HOME_DIR}/:/home/default/:rw
+
+      # The location where all games should be installed.
+      # This path needs to be set as a library path in Steam after logging in.
+      # Otherwise, Steam will store games in the home directory above.
+      - ${GAMES_DIR}/:/mnt/games/:rw
+
+      # The Xorg socket.
+      - ${SHARED_SOCKETS_DIR}/.X11-unix/:/tmp/.X11-unix/:rw
+
+      # Pulse audio socket.
+      - ${SHARED_SOCKETS_DIR}/pulse/:/tmp/pulse/:rw
diff --git a/...mpose-files/docker-compose.privileged.yml → ...iles/docker-compose.nvidia.privileged.yml b/...mpose-files/docker-compose.privileged.yml → ...iles/docker-compose.nvidia.privileged.yml
@@ -1,5 +1,5 @@
 ---
-version: "3.9"
+version: "3.8"
 
 services:
   steam-headless:
@@ -61,6 +61,7 @@ services:
       - SUNSHINE_PASS=${SUNSHINE_PASS}
       # Xorg
       - ENABLE_EVDEV_INPUTS=${ENABLE_EVDEV_INPUTS}
+      - FORCE_X11_DUMMY_CONFIG=${FORCE_X11_DUMMY_CONFIG}
       # Nvidia specific config
       - NVIDIA_DRIVER_CAPABILITIES=${NVIDIA_DRIVER_CAPABILITIES}
       - NVIDIA_VISIBLE_DEVICES=${NVIDIA_VISIBLE_DEVICES}
@@ -76,16 +77,11 @@ services:
       # Otherwise, Steam will store games in the home directory above.
       - ${GAMES_DIR}/:/mnt/games/:rw
 
-      # The Xorg socket. This will be shared with other containers so they can access the X server.
-      # Select only one option or leave commented out to not share the Xorg socket with any other Docker containers.
-      #   Option #1) Start a X server in the container to share with any other containers.
-      #- /opt/container-data/steam-headless/.X11-unix/:/tmp/.X11-unix/:rw
-      #   Option #2) Use an existing X server running on the host.
-      #- /tmp/.X11-unix/:/tmp/.X11-unix/:rw
+      # The Xorg socket.
+      - ${SHARED_SOCKETS_DIR}/.X11-unix/:/tmp/.X11-unix/:rw
 
-      # Pulse audio socket. This will be shared with other containers so they can access the audio sink.
-      # Leave commented out to not share the pulse socket with any other Docker containers.
-      #- /opt/container-data/steam-headless/pulse/:/tmp/pulse/:rw
+      # Pulse audio socket.
+      - ${SHARED_SOCKETS_DIR}/pulse/:/tmp/pulse/:rw
 
       # Input devices used for mouse and joypad support inside the container.
       - /dev/input/:/dev/input/:ro
diff --git a/.../compose-files/docker-compose.default.yml → docs/compose-files/docker-compose.nvidia.yml b/.../compose-files/docker-compose.default.yml → docs/compose-files/docker-compose.nvidia.yml
@@ -1,5 +1,5 @@
 ---
-version: "3.9"
+version: "3.8"
 
 services:
   steam-headless:
@@ -31,6 +31,8 @@ services:
               device_ids: ["${NVIDIA_VISIBLE_DEVICES}"]
 
     # NETWORK:
+    ## NOTE:  With this configuration, if we do not use the host network, then physical device input
+    ##        is not possible and your USB connected controllers will not work in steam games.
     network_mode: host
     hostname: ${NAME}
     extra_hosts:
@@ -64,6 +66,7 @@ services:
       - SUNSHINE_PASS=${SUNSHINE_PASS}
       # Xorg
       - ENABLE_EVDEV_INPUTS=${ENABLE_EVDEV_INPUTS}
+      - FORCE_X11_DUMMY_CONFIG=${FORCE_X11_DUMMY_CONFIG}
       # Nvidia specific config
       - NVIDIA_DRIVER_CAPABILITIES=${NVIDIA_DRIVER_CAPABILITIES}
       - NVIDIA_VISIBLE_DEVICES=${NVIDIA_VISIBLE_DEVICES}
@@ -75,9 +78,9 @@ services:
       - /dev/fuse
       # Add the host uinput device [REQUIRED].
       - /dev/uinput
-      # Add AMD/Intel HW accelerated video encoding/decoding devices [OPTIONAL].
-      #- /dev/dri
-      # Add NVIDIA HW accelerated devices [OPTIONAL - If you use the nvidia container toolkit, this is not needed].
+      # Add NVIDIA HW accelerated devices [OPTIONAL].
+      # NOTE: If you use the nvidia container toolkit, this is not needed.
+      #       Installing the nvidia container toolkit is the recommended method for running this container
       #- /dev/nvidia0
       #- /dev/nvidiactl
       #- /dev/nvidia-modeset
@@ -99,13 +102,8 @@ services:
       # Otherwise, Steam will store games in the home directory above.
       - ${GAMES_DIR}/:/mnt/games/:rw
 
-      # The Xorg socket. This will be shared with other containers so they can access the X server.
-      # Select only one option or leave commented out to not share the Xorg socket with any other Docker containers.
-      #   Option #1) Start a X server in the container to share with any other containers.
-      #- /opt/container-data/steam-headless/.X11-unix/:/tmp/.X11-unix/:rw
-      #   Option #2) Use an existing X server running on the host.
-      #- /tmp/.X11-unix/:/tmp/.X11-unix/:rw
+      # The Xorg socket.
+      - ${SHARED_SOCKETS_DIR}/.X11-unix/:/tmp/.X11-unix/:rw
 
-      # Pulse audio socket. This will be shared with other containers so they can access the audio sink.
-      # Leave commented out to not share the pulse socket with any other Docker containers.
-      #- /opt/container-data/steam-headless/pulse/:/tmp/pulse/:rw
+      # Pulse audio socket.
+      - ${SHARED_SOCKETS_DIR}/pulse/:/tmp/pulse/:rw
diff --git a/docs/docker-compose.md b/docs/docker-compose.md
@@ -38,8 +38,40 @@ sudo chown -R $(id -u):$(id -g) /mnt/games
 
 Create a Steam Headless `/opt/container-services/steam-headless/docker-compose.yml` file.
 
-Populate this file with the contents of the default [Docker Compose File](./compose-files/docker-compose.default.yml).
+Populate this file with the contents of the default Docker Compose File
 
+### AMD/Intel:
+- [AMD and Intel GPUs](./compose-files/docker-compose.amd+intel.yml).
+- [Privileged AMD and Intel GPUs Docker Compose Template](./compose-files/docker-compose.amd+intel.privileged.yml) (grants full access to host devices).
+
+#### Multipl AMD or Intel GPUs
+
+If you have multiple AMD or Intel GPUs and you wish to isolate them, then follow these steps to determine the card to passthrough in the docker compose file. This requires that you do not use the privileged compose template.
+1) List the PCI devices and get their IDs `lspci | grep -E 'VGA|3D'`
+```
+00:02.0 VGA compatible controller: Intel Corporation TigerLake-LP GT2 [Iris Xe Graphics] (rev 01)
+06:00.0 VGA compatible controller: Advanced Micro Devices, Inc. [AMD/ATI] Cezanne [Radeon Vega Series / Radeon Vega Mobile Series] (rev c6)
+```
+In this example, the Intel GPU has an ID of `00:02.0` and the AMD GPU has an ID of `06:00.0`.
+
+2) Discover which `/dev/dri/card*` and `/dev/dri/renderD12*` references the `00:02.0` Intel GPU (or whatever your output was). To do this, run the commands `ls -la /sys/class/drm/card*` and `ls -l /sys/class/drm/renderD*`.
+```
+lrwxrwxrwx. 1 root root 0 May  8 15:44 /sys/class/drm/card1 -> ../../devices/pci0000:00/0000:00:02.0/drm/card1
+lrwxrwxrwx. 1 root root 0 May  8 15:44 /sys/class/drm/card1-DP-1 -> ../../devices/pci0000:00/0000:00:02.0/drm/card1/card1-DP-1
+lrwxrwxrwx. 1 root root 0 May  8 15:44 /sys/class/drm/card1-DP-2 -> ../../devices/pci0000:00/0000:00:02.0/drm/card1/card1-DP-2
+lrwxrwxrwx. 1 root root 0 May  8 15:44 /sys/class/drm/card1-DP-3 -> ../../devices/pci0000:00/0000:00:02.0/drm/card1/card1-DP-3
+lrwxrwxrwx. 1 root root 0 May  8 15:44 /sys/class/drm/card1-DP-4 -> ../../devices/pci0000:00/0000:00:02.0/drm/card1/card1-DP-4
+```
+```
+lrwxrwxrwx. 1 root root 0 May  8 15:44 /sys/class/drm/renderD128 -> ../../devices/pci0000:00/0000:00:02.0/drm/renderD128
+lrwxrwxrwx. 1 root root 0 May  8 15:44 /sys/class/drm/renderD129 -> ../../devices/pci0000:00/0000:06:00.0/drm/renderD129
+```
+
+From this example output we can see that the Intel GPU is `/dev/dri/card1` and `/dev/dri/renderD128`.
+
+### NVIDIA:
+- [NVIDIA GPUs Docker Compose Template](./compose-files/docker-compose.nvidia.yml).
+- [Privileged NVIDIA GPUs Docker Compose Template](./compose-files/docker-compose.nvidia.yml) (grants full access to host devices).
 
 ## CONFIGURE ENV:
 
@@ -58,3 +90,6 @@ sudo docker-compose up -d --force-recreate
 After container executes successfully, navigate to your docker host URL in your browser on port 8083 and click connect.
 `http://<host-ip>:8083/`
 ![img.png](./images/web_connect.png)
+
+## Troubleshooting
+[Troubleshooting Docs](./troubleshooting.md)