/mumble-docker

The official Mumble Docker image

Primary LanguageShellBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

Mumble Docker

Mumble is a free, open source, low latency, high quality voice chat application.

Mumble WebsiteMumble Source

This is the official code of the Mumble Docker image for self-hosting the Mumble server. The image is available for download on Dockerhub.


Quick Start Guide

  1. Running the container
  2. Configuration
  3. Building the container

Running the container

Requirements

This documentation assumes that you already have Docker installed and configured on your target machine. You may find it more convenient to set up the Docker container using docker-compose. Thus, we also provide instructions for that scenario (see below).

In order for Mumble to store permanent data (most notably the database file (by default Mumble uses SQLite)), the image will use a volume which is mapped to the /data/ path inside the image. By default the image uses a user with UID 1000 and GID of also 1000 but either can be adapted when building the image yourself (see below). You will have to make sure that all file permissions are set up accordingly.

Running the container

Using docker:

$ docker run --detach \
             --name mumble-server \
             --publish 64738:64738/tcp \
             --publish 64738:64738/udp \
             --volume ./data/mumble:/data \
             --restart on-failure \
             mumblevoip/mumble-server:<tag>

For possible values of <tag> see below.

Using docker-compose:

services:
    mumble-server:
        image: mumblevoip/mumble-server:<tag>
        container_name: mumble-server
        hostname: mumble-server
        restart: on-failure
        ports:
            - 64738:64738
            - 64738:64738/udp
#       expose:
#           - 6502

For possible values of <tag> see below.

The additional port 6502 could for instance be used to expose the ICE interface. You'll obviously have to adapt the used port for whatever you configured in the server's configuration file.

Tags

For an up-to-date list of available tags, see Dockerhub. Generally, you can either use latest to always fetch the latest version or tags of the form vX.Y.Z corresponding to the respective stable releases of Mumble, e.g. v1.4.230.

Configuration

The preferred way of configuring the server instance in the Docker container is by means of environment variables. All of these variables take the form MUMBLE_CONFIG_<configName>, where <configName> is the name of the configuration to set. All config options that can be set in the regular Mumble server configuration file (historically called murmur.ini) can be set. For an overview of available options, see here.

<configName> is case-insensitive and underscores may be inserted into the respective config name, to increase readability. Thus, MUMBLE_CONFIG_dbhost, MUMBLE_CONFIG_DBHOST and MUMBLE_CONFIG_DB_HOST all refer to the same config dbHost.

The container entrypoint will use these environment variables and build a corresponding configuration file from it on-the-fly, which is then used the spun-up server.

You can specify these environment variables when starting the container using the -e command-line option as documented here:

$ docker run -e "MUMBLE_CONFIG_SERVER_PASSWORD=123"

As an alternative to environment variables, docker or podman secrets can be used to read configuration options from files which follow the MUMBLE_CONFIG_<config_name> name pattern and are located in the /run/secrets directory at runtime. The same rules to naming environment variables apply to these files as well.

Please consult the documentation of docker or podman on how to use secrets for further details.

Example: Running the container with secrets using podman

To set the server password and superuser password using podman secrets, the following series of commands can be used:

# Create the secrets
echo -n "secretserver" | podman secret create MUMBLE_CONFIG_SERVER_PASSWORD -
echo -n "supassword" | podman secret create MUMBLE_SUPERUSER_PASSWORD -

# Run the server with these secrets mounted
podman run --detach \
           --name mumble-server \
           --publish 64738:64738/tcp \
           --publish 64738:64738/udp \
           --secret MUMBLE_CONFIG_SERVER_PASSWORD \
           --secret MUMBLE_SUPERUSER_PASSWORD \
           --volume ./data/mumble:/data \
           --restart on-failure \
           mumblevoip/mumble-server:<tag>

Additional variables

The following additional variables can be set for further server configuration:

Environment Variable Description
MUMBLE_ACCEPT_UNKNOWN_SETTINGS Set to true to force the container to accept unknown settings passed as a MUMBLE_CONFIG_ variable (see note below).
MUMBLE_CUSTOM_CONFIG_FILE Specify a custom config file path - all MUMBLE_CONFIG_ variables are IGNORED
(it's best to use a path inside the volume /data/)
MUMBLE_SUPERUSER_PASSWORD Specifies the SuperUser (Admin) password for this server. If this is not given, a random password will be generated upon first startup.
MUMBLE_VERBOSE Set to true to enable verbose logging in the server

Note: In the unlikely case where a <configName> setting is unknown to the container, startup will fail with the following error.

mumble-server  | [ERROR]: Unable to find config corresponding to variable "<configName>"
mumble-server exited with code 1

The root cause of this error is the fact that this setting is incorrectly registered in the Mumble server code. You can workaround this error by setting the MUMBLE_ACCEPT_UNKNOWN_SETTINGS environment variable to true and spelling <configName> exactly as written in the Murmur.ini documentation.

Building the container

After having cloned this repository, you can just run

$ docker build .

in order to build a Mumble server from the latest commit in the upstream master branch.

If you prefer to instead build a specific version of the Mumble server, you can use the MUMBLE_VERSION argument like this:

$ docker build --build-arg MUMBLE_VERSION=v1.4.230 .

MUMBLE_VERSION can either be one of the published tags of the upstream repository or a commit hash of the respective commit to build.

Note that either way, only Mumble versions >= 1.4 can be built using this image. Mumble versions 1.3 and earlier are not compatible with the build process employed by this Docker image.

Using a different UID/GID

Additionally, it is possible to specify the UID and the GID of the mumble user that is used inside the container. These can be controlled by the MUMBLE_UID and MUMBLE_GID build variables respectively. This is intended to allow you to use the same UID and GID as your user on your host system, in order to cause minimal issues when accessing mounted volumes.

Using custom build options

It is also possible to pass custom cmake options to the build process by means of the MUMBLE_CMAKE_ARGS build variable. That way, you can customize the build to your liking. For instance, this could be used to enable the Tracy profiler (assuming you are building a version of the server that has support for it):

$ docker build --build-arg MUMBLE_CMAKE_ARGS="-Dtracy=ON"

For an overview of all available build options, check the build instructions of the main project.

Common build issues

Should you see the error

Got permission denied while trying to connect to the Docker daemon socket

you most likely invoked docker as a non-root user. In order for that to be possible, you need to add yourself to the docker group on your system. See the official docs on this topic for further information.