Docker specific instructions

Information handy to know before starting

warning

There are differences between running Docker on Linux, Mac and Windows. Linux can share the host network using --network=host Mac and Windows need port publishing using --publish HOST_PORT:CONTAINER_PORT . This makes using the ephemeral range for UDP protocols harder. Docker Desktop versions 4.34 can allow --network=host, please look at the Docker documentation

The default --shm-size for Docker is 64MB, which is barely enough to do anything for MistServer, please do not forget to set this value!

It's recommended to set a good amount of RAM depending on your hardware. We recommend using 95% if this is a dedicated server. Otherwise we would recommend at least 50% of your RAM. In the interest of keeping this quick and simple the --shm-size=### flag has been set to use 1GB of your RAM.

Set up the following values!

• --network=host To bind MistServer to the host network, allowing others to connect
• --publish HOST_PORT:CONTAINER_PORT As alternative to --network=host, required for Mac/Window users
• /PATH/TO/CONFIG.JSON Host location where you want to store the MistServer configuration.
• /FOLDER/WITH/VIDEOFILES Host location where VoD content is available
• 1g Amount of shared memory available to the docker image

docker run --detach --mount type=bind,source=/PATH/TO/CONFIG.JSON,destination=/config.json --mount type=bind,source=/FOLDER/WITH/VIDEOFILES,destination=/video --shm-size=1G --network=host ddvtech/mistserver

For more details on which docker images are available visit our official dockerhub page Keep in mind that some of our Docker images are just the MistServer binaries, while it will make the image itself super lightweight it does not allow for adding applications or running scripts within the Docker itself. Should you need an OS we recommend grabbing one of the images with an OS included or building your own version.

info

Docker works great with MistServer, however there is one technical limitation. Docker's default network set up will significantly impact the performance of network operations. We do not recommend running intense loads on this configuration. Please use bare metal instead! If you stay within ~50% of your network capabilities you will not notice any impact however.

Choose your way to run Docker

Docker Compose

More detailed information about how the bootstrap works is available here

git clone https://github.com/DDVTECH/mistserver-bootstrap.git && cd mistserver-bootstrap && docker-compose up -d --build

• Most login information will be set to admin / admin by default using the above command.
• If you wish to add HTTPS we recommend using Caddy

If you wish to create your own compose.yml you can use the bootstrap or refer to the older examples below.

In the examples below we will be using the ddvtech/mistserver container, make your own adjustments accordingly.

Minimal Docker compose.yml using --network=host

services:
    mistserver:
        image: ddvtech/mistserver
        container_name: mistserver
        volumes:
          - /PATH/TO/CONFIG/config.json:/config.json
          - /PATH/TO/VIDEOFOLDER:/video
        shm_size: '2gb'
        network_mode: 'host'
        restart: always

Minimal Docker compose.yml using --publish

services:
    mistserver:
        image: ddvtech/mistserver
        container_name: mistserver
        volumes:
          - /PATH/TO/CONFIG/config.json:/config.json
          - /PATH/TO/VIDEOFOLDER:/video
        shm_size: '2gb'
        ports:
          - 8080:8080
          - 443:443
          - 4242:4242
          - 8889:8889/udp
          - 5554:5554
          - 4200:4200
        restart: always

warning

Make sure to edit the volumes binds to valid paths!

Docker Desktop

info

MistServer requires the --shm-size value set, which unfortunately is impossible directly from running a container using purely Docker Desktop. You will need to run a manual Docker command, but once done you can use Docker Desktop as usual from there on.

tip

You can skip most of the steps below through a docker run command instead. Make sure Docker Desktop is open and paste the following in a terminal:

docker run --shm-size=4g --network=bridge -p 18203:18203/udp -p 1935:1935 -p 4242:4242 -p 5554:5554 -p 8080:8080 -p 8889:8889/udp -d ddvtech/mistserver:latest

Grabbing the image All our images will come from ddvtech, there could obviously be more available within Dockerhub. Feel free to pick any you like, however we obviously cannot give support/guarantees on images not from us.

Getting the docker run command MistServer will require a --shm-size=SIZE flag, however shared memory cannot be set using an environment variable, it must be done through a docker run command. This means we cannot avoid running it through the terminal or power shell. However Docker Desktop will pass on all required settings except for --shm-size if you start setting it up.

First boot through Docker Desktop To get the Docker run command we first boot it up, we then can set up the environment parameters. If you're running on Windows/Mac you will need to configure all the ports you will want to use from the outside. We have provided our defaults, but feel free to change/add ports as you like.

Copy the Docker Run command Once set up, we will need to copy the docker run command and edit this.

Edit docker run to include --shm-size Now open your terminal and paste the docker run command

We will need to add the --shm-size=SIZE setting. This is the amount of RAM available to MistServer to use, if you're only interested in testing MistServer with a few streams 1G is plenty. A good rule of thumb is to take bitrate times stream buffer + 20%. Our default stream buffer is 50 seconds.

Keep in mind you cannot go over your maximum RAM for this setting, if you want to use the maximum available the LOG of the container currently running will give you a number to copy in the first few lines.

It does not matter where you set the --shm-size=SIZE in the docker run command, we've set it before the -d ddvtech:mistserver/3.4 flag and set it to 4G to allow for some more streams.

Delete previous container and execute docker run You can now delete the currently running container, you will no longer need it and it is blocking the ports you will want to use.

Run the command and you will now have an extra container You can now start testing MistServer! .

Docker run

Docker run is the most basic method of starting a Docker container. A very minimal docker run script would be can be found here:

Docker run bare minimum sharing host network

docker run --shm-size=4G --network=host ddvtech/mistserver:latest

Docker run bare minimum publishing ports

docker run --shm-size=4g --network=bridge -p 18203:18203/udp -p 1935:1935 -p 4242:4242 -p 5554:5554 -p 8080:8080 -p 8889:8889/udp -d ddvtech/mistserver:latest

tip

We've noticed that most people tend to prefer to test a container quickly, if that is the case we recommend adding the following flags --rm -ti to both destroy the container once shut down & allow the terminal to be used by the Docker image.

Single run Docker container using host network

docker run --shm-size=4G --network=host --rm -ti ddvtech/mistserver:latest

Single run Docker container publishing default ports

docker run --shm-size=4g --network=bridge -p 18203:18203/udp -p 1935:1935 -p 4242:4242 -p 5554:5554 -p 8080:8080 -p 8889:8889/udp --rm -ti -d ddvtech/mistserver:latest

warning

Single run Docker images will NOT save settings between uses unless the configurations are stored outside Docker containers

Creating your own Docker container

This is something unnecessary for most users, however should you want to make additions, run a private version of MistServer or add to the default Docker image this is most likely the next step for you. You can simply add the Linux 64 binaries to any existing Docker and it will almost certainly work, however if you're going through the trouble of creating your own Docker container we would generally recommend compiling from the source as it does add efficiency and gives you full customization options.

We provide a dockerfile with our main repository that looks like the one below. The benefit to building MistServer with this is that all subprojects are pulled in and build separately. This means that as long as the subprojects do not change you can re-use them from your cache, which can be a big time-saver when building docker images. The default of this dockerfile is to take the source code of the project and compile that, so if you've build your own custom version of MistServer this should be compatible.

If you're planning to build a dockerfile completely from scratch the only thing you should be aware of is that there's the MistUtilHealth binary that's there specifically to do the Docker health checks. We recommend adding this to your dockerfile at the very least.

Dockerfile example

FROM alpine AS mist_build
# Pull in build requirements
RUN apk add --no-cache git patch meson ninja gcc g++ linux-headers pigz curl cjson pkgconfig

# Build dependencies librist, libsrt, libsrtp2, usrsctplib, mbedtls
RUN mkdir -p /deps/build/mbedtls /deps/build/libsrtp /deps/build/libsrt /deps/build/librist /deps/build/usrsctp /deps/mbedtls /deps/libsrtp /deps/libsrt /deps/librist /deps/usrsctp

# mbedtls
ADD --unpack=true https://github.com/Mbed-TLS/mbedtls/releases/download/mbedtls-3.6.5/mbedtls-3.6.5.tar.bz2 /deps
ADD subprojects/packagefiles/mbedtls/meson.build /deps/mbedtls-3.6.5/
ADD subprojects/packagefiles/mbedtls/include/mbedtls/mbedtls_config.h /deps/mbedtls-3.6.5/include/mbedtls/
RUN cd /deps/build/mbedtls/ && meson setup /deps/mbedtls-3.6.5 -Dstrip=true && meson install

# srtp
ADD https://github.com/cisco/libsrtp.git#v2.6.0 /deps/libsrtp
RUN cd /deps/build/libsrtp/ && meson setup /deps/libsrtp -Dstrip=true  && meson install

# srt
ADD https://github.com/Haivision/srt.git#v1.5.4 /deps/libsrt
ADD subprojects/packagefiles/libsrt/meson.build /deps/libsrt/
ADD subprojects/packagefiles/libsrt/srt/meson.build /deps/libsrt/srt/
RUN cd /deps/build/libsrt/ && meson setup /deps/libsrt -Dstrip=true  && meson install

# librist
ADD https://code.videolan.org/rist/librist.git#v0.2.11 /deps/librist
RUN cd /deps/build/librist/ && meson setup /deps/librist -Dstrip=true  && meson install

# usrsctp
ADD https://github.com/sctplab/usrsctp.git#0.9.5.0 /deps/usrsctp
RUN cd /deps/build/usrsctp/ && meson setup /deps/usrsctp -Dstrip=true  && meson install

# Build MistServer from local source
ADD . /src/
ARG MIST_OPTS
ARG DEBUG=3
ARG VERSION=Unknown
ARG TARGETPLATFORM
ARG RELEASE=Docker_${TARGETPLATFORM}
RUN mkdir /build/ && cd /build && meson setup /src -DDOCKERRUN=true -DNOUPDATE=true -DDEBUG=${DEBUG} -DVERSION=${VERSION} -DRELEASE=${RELEASE} -Dstrip=true ${MIST_OPTS} && ninja install

# Upload debug symbols if requested
ARG OUTPUT_DBG
RUN if [ -n "${OUTPUT_DBG+x}" ]; then tar cf - /build /src /deps | pigz -6 | curl --upload-file - "${OUTPUT_DBG}" ; fi

# Prepare final image from stripped (installed) copy of build
FROM alpine
RUN apk add --no-cache libstdc++ cjson
COPY --from=mist_build /usr/local/ /usr/local/
EXPOSE 4242 8080 1935 5554 8889/udp 18203/udp
ENTRYPOINT ["MistController"]
HEALTHCHECK CMD ["MistUtilHealth"]

tip

The above dockerfile does not expose default HTTP or HTTPS ports (80 and 443) you will want to add these if you want to use them instead.

Using the MistServer dockerfile

While the dockerfile will work as is, you will probably want to at least set the VERSION argument so that the reported version is correct:

• VERSION : Unknown by default, this can be set by passing a build-arg for the version, for example: --build-arg VERSION=3.9.2

Other build arguments that are useful to know about are:

• MIST_OPTS="OPTION OPTION OPTION": This can be used to pass compile flags to MistServer as stated here. Note that certain compile flags such as -DNORIST or -DNOSRT would still have those subprojects be pulled in and compiled unless you remove those lines from the dockerfile as well.
• OUTPUT_DBG=TARGET.tar.gz : Setting this value will allow you to make a backup of the binaries with debug flags for easier debugging. This requires an URL endpoint that it can do PUT towards.
• RELEASE : Defaults to Docker_${TARGETPLATFORM} this is what will be used as version for this docker container.
• --platform: By default the Docker container you'll be creating will be for the matching platform you're running this on. You can however build for AMD64 or ARM64 specifically by setting the --platform option.
  • --platform linux/amd64 for AMD64 builds
  • --platform linux/arm64 for ARM64 builds

Recommended minimum for building 3.9.2

docker build . -f Dockerfile.mistserver --build-arg VERSION=3.9.2 -t ddvtech/mistserver:3.9.2

Example with multiple options set

docker build . -f Dockerfile.mistserver --platform linux/amd64 --build-arg VERSION=3.9.2 --build-arg MIST_OPTS="-DNORIST=true -DDEBUG=4" -t ddvtech/mistserver:3.9.2

If you're building your own Dockers there's a good chance you know what you want configured. However keep in mind that you still need to give your Docker enough shared memory to work with.

tip

Do not forget to add --shm-size=SIZE and either --network=host or --publish HOST_PORT:CONTAINER_PORT to your docker run command. We recommend at least 1gb for minimal testing.