Mumble Docker

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

Mumble Website • Mumble 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 and the GHCR.

---

Quick Start Guide

1. Running the container
2. Configuration
3. Building the container
4. More docs and usage examples in the Wiki

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 10000 and GID of also 10000 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"

You can specify these environment varibles in docker-compose using the environment attribute as documented here:

services:
    mumble-server:
        environment:
            MUMBLE_CONFIG_USERS: 100
            MUMBLE_CONFIG_SENDVERSION: false
            MUMBLE_CONFIG_WELCOMETEXT: 'Hello World'

            # For MUMBLE_CONFIG_ string values with special
            # characters (e.g. comma), wrap the value in quotes
            MUMBLE_CONFIG_USERNAME: '"^[-_a-z0-9]{3,15}$"'

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.

• Docker (Swarm) Secrets
• Podman Secrets
  • podman run with secrets
  • podman secret subcommand

Automatic TLS Certificate Management

Any Mumble docker image has a variant that contains the -acme suffix (e.g. latest-acme). These docker images contain the ACME client lego which may be used to automatically issue, renew and reload trusted TLS certificates from Let's Encrypt and other ACME enabled CAs. In order to make use of this feature you have to mount a persistent volume to /etc/acme and set some environment variables:

• ACME_ACCOUNT_MAIL: Will be used to register an account with the given ACME service.
• ACME_SERVER: The API URL of the ACME service. Defaults to Let's Encrypt. You may set this for example to https://acme-staging-v02.api.letsencrypt.org/directory in order to use the staging environment.
• ACME_DOMAIN: The domain of your Mumble server. The certificate will be ordered for this domain.
• ACME_HTTP: Set this to any value to use the HTTP-01 challenge. You have to expose your Mumble server directly to the internet via port 80 (not 443!).
• ACME_DNS: Set this to the name of a DNS provider supported by lego. You have to provide credentials for the DNS API as mentioned in the lego docs.
• ACME_DNS_RESOLVERS: You may set this to a semicolon separated list of DNS servers to use for validation. Set this to your DNS providers servers if you experience slow validations.

If you have special requirements you can set the ACME_LEGO_ARGS variable to make use of all features of lego. The contents of this variable will be appended to lego run. If you do so, you may omit all other ACME_* variables, but have to set the same values in your ACME_LEGO_CMD manually. Please do not include the run or renew subcommands, as these will be appended by the certificate management script.

Differences between the regular image and the -acme image

The images containing the ACME client come with some additional restrictions compared to the regular image:

• Mumble is not PID 1, because a process manager is added to run multiple processes in a single docker image. You cannot send signals to Mumble via docker kill.
• You can only set a different UID/GID via specifying the PUID/PGID variables. It is not possible to start the image as a different user via the docker run --user flag. Note that privileges will be dropped prior to launching Mumble, so the server will never run as root.

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_CHOWN_DATA	Set to false to skip taking ownership of /data and its contents.
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 --target mumble .

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 --target mumble --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.

If you want to build a version of the docker image that supports automating certificate management via ACME, you have to specify another build target:

$ docker build --target mumble-acme .

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

You can use Docker-standard PUID and PGID environment variables to set the UID and GID you wish mumble-server to run as and who will own the files in /data. The default is UID:GID 10000:10000. Unless the environment variable MUMBLE_CHOWN_DATA is set to false the container will take ownership of /data and any of its contents at container launch.

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.