General enhancement: Clarify in the docs how you can explicitly specify the config file location

[emiedmee]

Describe the feature

I've been having some issues deploying MediaMTX to OpenShift and loading a custom config file. In particular I'm unable to mount a volume containing my custom config file to the default path where MediaMTX expects the config file to be.
I've been looking around the docs and issues, but couldn't find anything about changing the config file path.

Problem

On Docker this is not a problem, because you can mount a single file, so you can mount a custom config file from your local file system to /mediamtx.yml and everything works.

On OpenShift, you can't mount a volume to / so you are not able to mount /mediamtx.yml and therefor not able to load a custom config file. When you can tell MediaMTX the config file is in a different folder, where you can mount a volume, everything works fine!

It turns out that you can actually change the config file path, by providing an extra argument that contains the config file path to MediaMTX. This is not documented as far as I could find, but I happened to stumble upon this in issue #3799.

Solution

Add a section, probably at Other features > Configuration, explaining you can change the path for the config file by providing it as an argument when starting the program.

When starting MediaMTX by starting the executable:

./mediamtx /path/to/config/file.yml

When using docker:

docker run --rm -it --network=host bluenviron/mediamtx:latest /path/to/config/file.yml

When using docker-compose:

services:
  mediamtx:
    image: bluenviron/mediamtx:latest
    command: ["/config/mediamtx.yml"]  # Explicitly specify the config file location
    volumes:
      - /local/path/to/config/file.yml:/config/mediamtx.yml
    networks:
      - host

When using Kubernetes/OpenShift:

kind: Deployment
apiVersion: apps/v1
metadata:
  name: mediamtx
spec:
  template:
    spec:
      containers:
        - name: mediamtx
          image: bluenviron/mediamtx:latest
          args: ["/config/mediamtx.yml"]  # Explicitly specify the config file location
          volumeMounts:
            - name: mediamtx-config
              mountPath: /config
      volumes:
        - name: mediamtx-config
          persistentVolumeClaim:
            claimName: mediamtx-config-pvc

[Arcitec]

What you are describing is not right. At all.

The current documentation is right:

https://github.com/bluenviron/mediamtx?tab=readme-ov-file#configuration

docker run --rm -it --network=host -v $PWD/mediamtx.yml:/mediamtx.yml bluenviron/mediamtx

The docker image stores the config at /mediamtx.yml and to override it you need to map an EXTERNAL file (outside container) to THAT path inside the container. That's all you have to do. This is the standard workflow for all Docker containers, not just MediaMTX, btw.

Did you miss that section of the documentation?

---

As for the standalone (non-Docker) app binary, that .tar.gz file contains the binary AND the mediamtx.yml file, and the binary automatically looks for the config in the same directory as the binary. So yet again, there's no need to tell people how to override the path.

---

And you may say "But what if they want to run multiple MediaMTX servers with different configs?". Then they haven't understood MediaMTX at all: MediaMTX needs only ONE instance to handle EVERYTHING. It's a media ROUTER. You can configure external authentication servers to handle complex user authentication, different stream URLs, protocols, etc.

See: https://github.com/bluenviron/mediamtx?tab=readme-ov-file#authentication (especially the HTTP authentication method), where your external server can reply stuff like "Yes user bob can publish to RTSP but only on stream paths starting with /bob/" or "Yes any user can watch without login, but only from RTMP" etc.

For even higher performance authentication, read the section about JWT which generates auth tokens and a list of what permissions that user has (with all valid paths (regex is allowed), etc) instead of verifying every request.

You can also completely turn off any protocols you never want, via the mediamtx.yml config.

[emiedmee]

Hello, I think I overspecified a bit which caused some misunderstanding. So let me try to clear things up.

The problem is only with Kubernetes/OpenShift, but I provided code snippets for all other supported ways of running MediaMTX to be complete.

I know you just need to place/overwrite the config file in the same directory as the binary. I also know that for Docker you just need to mount an external file to /mediamtx.yml. That's also how I do it when running it locally with Docker.

In Kubernetes/OpenShift it's not possible to mount the config file to /mediamtx.yml.

You can't just mount a single file, like you would in Docker. You need to mount a volume, which contains one or more files. So if you create a volume with a file mediamtx.yml and mount that volume at /my/path, you will have /my/path/mediamtx.yml.

The second thing, that is the real problem, is that you can't mount a volume to /. If you want to mount the config file so it is available at /mediamtx.yml, you would need to create a volume with a file mediamtx.yml and mount that volume at /, but you just can't do that in Kubernetes/OpenShift.

So that is why I created this issue, because I didn't see anywhere in the documentation how you could explicitly specify the config location and I think it should be added in there.
In hindsight the Docker and docker-compose examples are not needed and maybe confusing, but I added them to be complete. The CLI example was just to show "how it's done". But the Kubernetes/OpenShift examples was the only one that is applicable here.

[Arcitec]

Ahhh right, yeah mounting individual files is a bit weird even for Docker/Podman. Normally you'd mount directory volumes.

I didn't know that Kubernetes demands directory volumes. Interesting.

I agree that there needs to be some mention of how to override the config location when mounting a directory volume on Kubernetes. Good catch. :)

[adeturner]

I used helm - I created my own from scratch but used this as a guide.

https://git.home.oriley.net/apps/helm-charts/-/tree/main/mediamtx/templates

Checkout the configmap and deployment yaml