Skip to content

alpine-pulseaudio

Legacy Image

This image still uses the old-style format for Dockerfiles/makefile recipes, that may (or may not) be compatible with the newer image sources. The container should keep working as expected, but for building new images, a significant part of the code needs to be updated.

updated stars forks watchers issues issues-pr
pulls stars aarch64 armhf armv7l x86_64

Container for Alpine Linux + S6 + PulseAudio + Bluez

This image containerizes the PulseAudio Network Sound server to setup a central sound service inside a local network, also runs the Bluez bluetooth daemon to work with bluetooth speakers or sources. Includes Pulsemixer to manage pulseaudio from CLI.

Based on Alpine Linux from the s6 image with the pulseaudio package installed in it.

Get the Image

Pull the image from Docker Hub.

docker pull woahbase/alpine-pulseaudio
Image Tags

The image is tagged respectively for the following architectures,

latest tag is retagged from x86_64, so pulling without any tag fetches you that image. For any other architectures specify the tag for that architecture. e.g. for armv8 or aarch64 host it is alpine-pulseaudio:aarch64.

non-x86_64 images used to contain the embedded qemu-user-static binary which has been redundant for a while, and is being deprecated starting with our Alpine Linux v3.22 base-image release, see qemu-user-static or the more recent binfmt instead for running multi-arch containers.

Run

Running the container starts the service.

docker run --rm -it \
  --name docker_pulseaudio \
  -p 4713:4713 \
  --net=host \
  --cap-add NET_ADMIN \
  --device /dev/snd \
  --device /dev/bus/usb \
  -v $PWD/config/pulse:/etc/pulse \
  -v /var/run/dbus:/var/run/dbus \
  -v /etc/localtime:/etc/localtime:ro \
woahbase/alpine-pulseaudio:x86_64
Multi-Arch Support

If you want to run images built for other architectures on the same host (e.g. a x86_64 machine), you will need to have the specific binary format support configured on your host machine before running the image (otherwise you get an exec format error). Here's how,

For recent images, we can use tonistiigi's binfmt image to register binary execution support for the target architecture, like the following,

docker run --rm --privileged tonistiigi/binfmt --install <architecture>

Architecture is that of the image we're trying to run, can be arm64 for aarch64, arm for both armv7l and armhf, or amd64 for x86_64. See binfmt.

Previously, multiarch, had made it easy for us by packing qemu into an image, so we could just run

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

However, that image (see qemu-user-static) seems to have fallen behind in updates, and with newer images the binfmt method is preferable.

Now images built for other architectures will also be executable. This is optional though, without the above, you can still run the image that is specifically made to support your host architecture.

Configuration

  • This image runs PulseAudio under the user root, but also has a user pulse configured to drop privileges to the passed PUID/PGID which is ideal if its used to run in non-root mode. That way you only need to specify the values at runtime and pass the -u pulse if need be. (run id in your terminal to see your own PUID/PGID values.)

  • PulseAudio config files read from /etc/pulse. If you have custom cards other than your default sound output jack, most likely you will need to edit or remount this with your own. For example, you can keep the files inside config/pulse and mount it as /etc/pulse on start.

  • Does not run own systemd or dbus daemon so cards might not get detected automatically, default configuration loads only the defauls Alsa Sink, so will need to modify configurations to detect the new hardware.

  • Default configuration listens to port 4713. Will need to have this port accessible from add devices to get sound. (Check your firewall).

  • Bluetooth configurations read from /etc/bluetooth.

  • To persist paired bluetooth configurations, preserve the contents of /var/lib/bluetooth by mounting it someplace like config/devices.

  • DBUS can cause permission issues if the host is not configured to allow Bluez or PulseAudio. Host configuration defaults for these are provided inside /config/dbus.

  • Any drivers for audio (and/or bluetooth as in Rasperry Pis) will need to be installed in the host machine.

  • Don't forget to set the environment variable PULSE_SERVER as your server host in the client machines so that they forward their sound to the server. Check out this link for more information.

  • To run only the pulseaudio server without starting bluetooth, set the environment variable DISABLEBLUETOOTH to the string true.

Stop the container with a timeout, (defaults to 2 seconds)

docker stop -t 2 docker_pulseaudio

Restart the container with

docker restart docker_pulseaudio

Removes the container, (always better to stop it first and -f only when needed most)

docker rm -f docker_pulseaudio
Shell access

Get a shell inside a already running container,

docker exec -it docker_pulseaudio /bin/bash

Optionally, login as a non-root user, (default is alpine)

docker exec -u alpine -it docker_pulseaudio /bin/bash

Or set user/group id e.g 1000/1000,

docker exec -u 1000:1000 -it docker_pulseaudio /bin/bash
Logs

To check logs of a running container in real time

docker logs -f docker_pulseaudio

Build Your Own

Feel free to clone (or fork) the repository and customize it for your own usage, build the image for yourself on your own systems, and optionally, push it to your own public (or private) repository.

Here's how...

Setting up

Before we clone the /repository, we must have Git, GNU make, and Docker (optionally, with buildx plugin for multi-platform images) setup on the machine. Also, for multi-platform annotations, we might require enabling experimental features of Docker.

Now, to get the code,

Clone the repository with,

git clone https://github.com/woahbase/alpine-pulseaudio
cd alpine-pulseaudio
Always Check Before You Make!

Did you know, we could check what any make target is going to execute before we actually run them, with

make -n <targetname> <optional args>

Build and Test

To create the image for your architecture, run the build and test target with

make build test

For building an image that targets another architecture, it is required to specify the ARCH parameter when building. e.g.

make build test ARCH=aarch64 

make build test ARCH=armhf 

make build test ARCH=armv7l 

make build test ARCH=x86_64

Make to Run

Running the image creates a container and either starts a service (for service images) or provides a shell (can be either a root-shell or usershell) to execute commands in, depending on the image. We can run the image with

make run

But if we just need a root-shell in the container without any fance pre-tasks (e.g. for debug or to test something bespoke), we can run bash in the container with --entrypoint /bin/bash. This is wrapped in the makefile as

make shell
Nothing vs All vs Run vs Shell

By default, if make is run without any arguments, it calls the target all. In our case this is usually mapped to the target run (which in turn may be mapped to shell).

There may be more such targets defined as per the usage of the image. Check the makefile for more information.

Push the Image

If the build and test steps finish without any error, and we want to use the image on other machines, it is the next step push the image we built to a container image repository (like /hub), for that, run the push target with

make push

If the built image targets another architecture then it is required to specify the ARCH parameter when pushing. e.g.

make push ARCH=aarch64 

make push ARCH=armhf 

make push ARCH=armv7l 

make push ARCH=x86_64

That's all folks! Happy containerizing!

Maintenance

Sources at Github. Images at Docker Hub.

Maintained (or sometimes a lack thereof?) by WOAHBase.

Helped you save a bit of your valuable time and effort that is best spent doing stuff you actually enjoy? If you have some pocket-change to spare, kindly consider helping out.