Launching NestMTX with Docker

The easiest & fastest way to deploy NestMTX is using Docker. While it is possible to build and deploy from source, most users will find that the prepared docker images are more than sufficient for their needs.

Note

This tutorial assumes that you have at least a basic understanding of how to use Docker.

Quick Start

NestMTX is designed to handle various streaming protocols and media formats, making it versatile for a range of applications. The following steps outline how to get NestMTX up and running in a Docker environment, ensuring a smooth deployment process.

The commands provided below will:

Pull the latest NestMTX image for your system's architecture.
Run the Docker container in detached mode (-d), ensuring that it restarts automatically unless stopped manually (--restart=unless-stopped).
Set up the necessary environment variables and port mappings to ensure that NestMTX can handle your media streaming needs.

Simply copy and paste the relevant command for your system architecture into your terminal, and NestMTX will be up and running in no time.

amd64arm64

bash

docker pull nestmtx/amd64:latest
docker run -d \
    --name="nestmtx" \
    --restart=unless-stopped \
    -e RTP_MAX_PORT="10100" \
    -e MEDIA_MTX_RTSP_ENABLED="true" \
    -e MEDIA_MTX_RTMP_ENABLED="true" \
    -e MEDIA_MTX_HLS_ENABLED="true" \
    -e MEDIA_MTX_WEB_RTC_ENABLED="true" \
    -e MEDIA_MTX_SRT_ENABLED="true" \
    -p "2000:2000" \
    -p "2001:2001" \
    -p "1935:1935" \
    -p "8000:8000/udp" \
    -p "8001:8001/udp" \
    -p "8189:8189/tcp" \
    -p "8189:8189/udp" \
    -p "8554:8554" \
    -p "8888:8888" \
    -p "8889:8889" \
    -p "8890:8890" \
    -p "10000-10100:10000-10100/udp" \
    nestmtx/amd64:latest

bash

docker pull nestmtx/arm64:latest
docker run -d \
    --name="nestmtx" \
    --restart=unless-stopped \
    -e RTP_MAX_PORT="10100" \
    -e MEDIA_MTX_RTSP_ENABLED="true" \
    -e MEDIA_MTX_RTMP_ENABLED="true" \
    -e MEDIA_MTX_HLS_ENABLED="true" \
    -e MEDIA_MTX_WEB_RTC_ENABLED="true" \
    -e MEDIA_MTX_SRT_ENABLED="true" \
    -p "2000:2000" \
    -p "2001:2001" \
    -p "1935:1935" \
    -p "8000:8000/udp" \
    -p "8001:8001/udp" \
    -p "8189:8189/tcp" \
    -p "8189:8189/udp" \
    -p "8554:8554" \
    -p "8888:8888" \
    -p "8889:8889" \
    -p "8890:8890" \
    -p "10000-10100:10000-10100/udp" \
    nestmtx/arm64:latest

Deployment Channels

NestMTX has been compiled for both amd64 and arm64 architecture. This is needed because the binaries for some of the supporting software such as MediaMTX, FFMpeg and GStreamer are different between the different CPU architectures. To reflect this, the images for NestMTX are:

Arch	Image	Docker Hub Link
`amd64`	`nestmtx/amd64`	https://hub.docker.com/r/nestmtx/amd64
`arm64`	`nestmtx/arm64`	https://hub.docker.com/r/nestmtx/arm64

Version Tags

In addition to the released versions, there are 2 "main" tags:

testing which receives code updates which are ready to be tested but have not yet been proven stable
latest this is always the latest released version

Example

To use the testing version of nestmtx/amd64, you would use the image nestmtx/amd64:testing. For the production ready version, you would use either the specific version tag (i.e. nestmtx/amd64:v1.0.0) or the latest tag (i.e. nestmtx/amd64:latest)

There are some situations where you way want to persist files (like the NestMTX SQLite Database) or share files from the host machine to the container (like SSL certificates). NestMTX has a built in directory ready to receive this mapping: /home/node/app/tmp.

Example

To map between the /home/user/nestmtx directory on your host machine and /home/node/app/tmp in the container, add the following before the image name in the command which you use to launch NestMTX:

bash

-v /home/user/nestmtx:/home/node/app/tmp

Folder Permissions

By default, the node user in the docker container has the ID 1000 and the group id 1000. That means that if your local folder doesn't have very permissive permissions (i.e. 777) then you will encounter errors when attempting to load NestMTX with a persistent volume. To work around this, there are 2 options:

Change the ownership of the folder

You can change the ownership of the folder to 1000:1000 using chown 1000:1000 /path/to/folder on the host machine. This will allow the dockerized application to read and write files there without any issues.

Change the ID and Group ID of the Docker Container

You can change the ID and Group ID of the docker container by passing the --user flag to the command. For example:

Example

bash

--user 100:100

If you want to use your own user's ID and Group ID, you can use:

Example

bash

--user $(id -u):$(id -g)

Networking Setup

The Networking setup for NestMTX can range between very simplistic to very complex depending on how you would things configured. Without any additional configuration, NestMTX does not expose any ports. Instead it depends on you to configure port mapping as you see fit.

Tip: Avoid Host Networking

NestMTX allocates a LOT of ports for use internally. While it tries to be graceful about conflicts, other applications may not be as flexible. For best results (and for better overall security) it is highly recommended NOT to use --network=host.

To configure port mapping, add the following before the image name in the command which you use to launch NestMTX:

bash

-p {port on host}:{port from container}

Tip

Some ports are UDP only. The format for mapping those ports is

bash

-p {port on host}:{port from container}/udp

Web Server(s)

NestMTX serves it's HTTP(s) API on ports 2000 (http) and 2001 (https).

Tip

You do not need to expose ports for both HTTP and HTTPS. Only expose what you need

HTTPS

NestMTX serves HTTPS requests with a self-signed certificate which is automatically generated if missing or expired when the container boots. However you are not limited to using the self-signed certificate generated by NestMTX. If you would like to bring your own, you can set the path to the certificate by configuring the HTTPS_CERT_PATH and HTTPS_KEY_PATH environmental variables.

Tip

If you use a relative file path (i.e. one which doesn't start with /) NestMTX assumes that your file path is relative to /home/app/nestmtx/tmp so nestmtx.crt will be assumed to be /home/app/nestmtx/tmp/nestmtx.crt

The easiest way to configure your own SSL certifcates is to map a volume between your host machine and the NestMTX /home/node/app/tmp directory, place your certificate and certificate key files in the folder on your host machine, and configure the HTTPS_CERT_PATH and HTTPS_KEY_PATH appropriately.

Database

NestMTX is configured by default to use an SQLite database which is generated and stored in /home/node/app/tmp/db.sqlite3, however you are able to use your own custom database server including:

MySQL / MariaDB
PostgreSQL¹
Microsoft SQL

¹ While the driver technically supports Amazon Redshift, it is not recommended to use it.

Configuring a Custom Database

To configure a custom database, you will need to configure the following environmental variables:

Environmental Variable	Options	Description
`DB_CONNECTION`	`sqlite`, `mysql`, `pg`, `mssql`	The type of database which NestMTX will use
`DB_HOST`		The IP address or hostname of the database server NestMTX will use
`DB_PORT`		The port which the database server is listening for connections on
`DB_USER`		The user NestMTX will use to authenticate connections to the database server
`DB_PASSWORD`		The password NestMTX will use to authenticate connections to the database server
`DB_NAME`		The name of the database NestMTX will connect to on the database server
`DB_SECURE`	`true`, `false`	If NestMTX needs to attempt a secure connection to the database server

Tip

In most cases in a home lab, you will not need to configure DB_SECURE, but if you're using a Cloud-managed database server from providers like AWS or DigitalOcean you will most likely need to set this to true.

MQTT

NestMTX supports many programmatic methods of control including an MQTT API. Without any additional configuration, NestMTX launches its own built-in MQTT server using Aedes, but it can be configured to use an external MQTT server as well.

NestMTX Topics

NestMTX nests all topics under the topic defined by the MQTT_BASE_TOPIC environmental variable. By default, it is set to nestmtx, but you can change it to anything that you would like! For more information on how topics are used, please see the MQTT API documentation.

NestMTX MQTT

To use the NestMTX MQTT Server, you will need to forward requests from the host machine to the port configured under the environmental variable MQTT_PORT. This port is set to 1883 by default.

Example

bash

-p 1883:1883

External MQTT Server

You can use an external MQTT Server with NestMTX by setting the following environmental variables:

Environmental Variable	Options	Description
`MQTT_PROTOCOL`	`wss`,`ws`,`mqtt`,`mqtts`,`tcp`,`ssl`,`wx`,`wxs`,`ali`,`alis`	The protocol used to connect to the MQTT Server
`MQTT_HOST`		The IP address or hostname of the MQTT Server
`MQTT_PORT`		The port the MQTT server is listening for connections on
`MQTT_USER`		The username used to authenticate connections with the MQTT server
`MQTT_PASS`		The password used to authenticate connections with the MQTT server

Streaming Protocols

By default, NestMTX does not enable any streaming protocols. This is mainly done for performance reasons, but has the additional benefit of helping prevent port conflicts.

Updating the ports shown in the UI

You can use the following environmental variables to change the port shown in the UI. This is especially useful when you have mapped a different host port to the protocol's port.

Environmental Variable	Default
`NESTMTX_RTSP_TCP_PORT`	`8554`
`NESTMTX_RTSP_UDP_RTP_PORT`	`8000`
`NESTMTX_RTSP_UDP_RTCP_PORT`	`8001`
`NESTMTX_RTMP_PORT`	`1935`
`NESTMTX_HLS_PORT`	`8888`
`NESTMTX_WEB_RTC_PORT`	`8889`
`NESTMTX_SRT_PORT`	`8890`

RTSP Output Streaming

To enable an output stream from NestMTX for the RTSP Protocol, you should set the environmental variables:

Environmental Variable	Value
`MEDIA_MTX_RTSP_ENABLED`	`true`