From 0aa2a92d3fbfe7abe9843d7cc2e51b91f74b2e43 Mon Sep 17 00:00:00 2001
From: Jonas L <jooola@users.noreply.github.com>
Date: Sun, 26 Feb 2023 19:39:10 +0100
Subject: [PATCH] docs: add pulseaudio output in containers tutorial (#2166)

---
 docker-compose.override.yml                   |  3 +
 docker/config.dev.yml                         |  4 +
 docker/pulse.client.conf                      |  8 ++
 ...p-a-pulseaudio-output-inside-containers.md | 91 +++++++++++++++++++
 4 files changed, 106 insertions(+)
 create mode 100644 docker/pulse.client.conf
 create mode 100644 docs/admin-manual/tutorials/setup-a-pulseaudio-output-inside-containers.md

diff --git a/docker-compose.override.yml b/docker-compose.override.yml
index cc9a43f0c..213147155 100644
--- a/docker-compose.override.yml
+++ b/docker-compose.override.yml
@@ -32,6 +32,9 @@ services:
     volumes:
       - ./playout:/src
       - ./docker/data/playout:/app
+      ## See https://libretime.org/docs/admin-manual/tutorials/setup-a-pulseaudio-output-inside-containers/
+      # - ./docker/pulse.socket:/tmp/pulse.socket
+      # - ./docker/pulse.client.conf:/etc/pulse/client.conf
 
   analyzer:
     build:
diff --git a/docker/config.dev.yml b/docker/config.dev.yml
index de5805369..81229ee15 100644
--- a/docker/config.dev.yml
+++ b/docker/config.dev.yml
@@ -40,3 +40,7 @@ stream:
         audio:
           format: mp3
           bitrate: 256
+
+    system:
+      - enabled: false
+        kind: pulseaudio
diff --git a/docker/pulse.client.conf b/docker/pulse.client.conf
new file mode 100644
index 000000000..b9eafe6d4
--- /dev/null
+++ b/docker/pulse.client.conf
@@ -0,0 +1,8 @@
+default-server = unix:/tmp/pulse.socket
+
+# Prevent a server running in the container
+autospawn = no
+daemon-binary = /bin/true
+
+# Prevent the use of shared memory
+enable-shm = false
diff --git a/docs/admin-manual/tutorials/setup-a-pulseaudio-output-inside-containers.md b/docs/admin-manual/tutorials/setup-a-pulseaudio-output-inside-containers.md
new file mode 100644
index 000000000..c2906eed5
--- /dev/null
+++ b/docs/admin-manual/tutorials/setup-a-pulseaudio-output-inside-containers.md
@@ -0,0 +1,91 @@
+---
+title: How to setup a PulseAudio output inside containers
+---
+
+This tutorials walks you though the steps required to setup a PulseAudio output when running LibreTime inside containers.
+
+:::info
+
+We assume you already [installed LibreTime using docker-compose](../setup/install.md#using-docker-compose).
+
+:::
+
+:::note links
+
+- https://github.com/mviereck/x11docker/wiki/Container-sound:-ALSA-or-Pulseaudio#pulseaudio-with-shared-socket
+
+:::
+
+## 1. Create a PulseAudio server socket
+
+First you need to create a PulseAudio connection socket on the host:
+
+```bash
+pactl load-module module-native-protocol-unix socket=$(pwd)/pulse.socket
+```
+
+To persist the socket after a reboot, you can save the socket configuration to a file:
+
+```bash
+mkdir -p ~/.config/pulse
+cp /etc/pulse/default.pa ~/.config/pulse/default.pa
+echo "load-module module-native-protocol-unix socket=$(pwd)/pulse.socket" | tee -a ~/.config/pulse/default.pa
+```
+
+:::info
+
+See `man default.pa` for more details on how to persist a PulseAudio configuration.
+
+:::
+
+:::warning
+
+Make sure that the PulseAudio connection socket is owned by the same user running inside the container. By default the user inside the container will be `1000:1000`, so you should be fine if your host user also has the uid `1000`.
+
+:::
+
+## 2. Configure the PulseAudio client
+
+Next, you need to configure the PulseAudio client inside the `liquidsoap` container. Save the following configuration file to `pulse.client.conf`:
+
+```ini title="pulse.client.conf"
+default-server = unix:/tmp/pulse.socket
+
+# Prevent a server running in the container
+autospawn = no
+daemon-binary = /bin/true
+
+# Prevent the use of shared memory
+enable-shm = false
+```
+
+Configure the `liquidsoap` service in your docker compose file using the following settings:
+
+```yaml title="docker-compose.yml"
+services:
+  liquidsoap:
+    volumes:
+      - ./pulse.socket:/tmp/pulse.socket # Mount the PulseAudio server socket
+      - ./pulse.client.conf:/etc/pulse/client.conf # Mount the PulseAudio client configuration
+```
+
+## 3. Configure LibreTime with the new PulseAudio output
+
+Finally, you need to configure LibreTime to output to the PulseAudio client, add the following to your configuration file:
+
+```yaml title="config.yml"
+stream:
+  outputs:
+    system:
+      - enabled: true
+        kind: pulseaudio
+```
+
+You can now start/restart LibreTime, and check the logs for any errors.
+
+```bash
+docker-compose down
+docker-compose up -d
+
+docker-compose logs -f liquidsoap
+```