Add troubleshooting guide for mosquitto Docker container startup failures

[knowack1]

How would you describe the topic that you would love to see in the documentation?

Add documentation about potential Mosquitto Docker container startup failures and their resolution. Specifically, when the container fails to start due to websockets listener errors on port 9001 users need guidance on diagnosing and set file descriptor limit in Docker configuration.

On which page or to which section does this belong?

This belongs in the "Quick Start Guide" section (docs/general/03_quick_start_guide.rst), specifically in the Mosquitto Docker container setup section where Docker run commands are documented.

Can you reference a related GitHub repository or source code?

The documentation file that needs updating is:

docs/general/03_quick_start_guide.rst

Additional context

This issue was observed on Fedora 42 with Docker version 28.3.3:

docker run --name mqtt-server --network infranet_network -p 1883:1883 -p 9001:9001 ghcr.io/everest/everest-dev-environment/mosquitto:docker-images-v0.1.0
Config loaded from /mosquitto/config/mosquitto.conf.
Opening ipv4 listen socket on port 1883.
Opening ipv6 listen socket on port 1883.2
Opening websockets listen socket on port 9001.
Error: Unable to create websockets listener on port 9001.

Detailed log with websockets_log_level 31:

docker run --name mqtt-server --network infranet_network -p 1883:1883 -p 9001:9001 ghcr.io/everest/everest-dev-environment/mosquitto:docker-images-v0.1.0
1758397856: mosquitto version 2.0.10 starting
1758397856: mosquitto version 2.0.10 starting
1758397856: Config loaded from /mosquitto/config/mosquitto.conf.
1758397856: Config loaded from /mosquitto/config/mosquitto.conf.
1758397856: Opening ipv4 listen socket on port 1883.
1758397856: Opening ipv4 listen socket on port 1883.
1758397856: Opening ipv6 listen socket on port 1883.
1758397856: Opening ipv6 listen socket on port 1883.
1758397856: Opening websockets listen socket on port 9001.
1758397856: Opening websockets listen socket on port 9001.
1758397856: libuv support not compiled in
1758397856: libuv support not compiled in
1758397856: OOM allocating 1073741816 fds
1758397856: OOM allocating 1073741816 fds
1758397856: ZERO RANDOM FD
1758397856: ZERO RANDOM FD
1758397856: Error: Unable to create websockets listener on port 9001.
1758397856: Error: Unable to create websockets listener on port 9001.

The solution involves configuring Docker's nofile limits as documented in this guide: https://ichbinblau.github.io/2019/09/06/Setup-nofile-for-Docker.

[knowack1]

This issue was observed on Fedora 42 with Docker version 28.3.3.
Adding a note about a possible root cause can save time for users facing the same issue.

[andistorm]

@knowack1 is this error caused by default configuration on Fedora 42 with Docker version 28.3.3 or is it a setting that could be set somewhere accidently?

[knowack1]

@knowack1 is this error caused by default configuration on Fedora 42 with Docker version 28.3.3 or is it a setting that could be set somewhere accidently?

I haven't changed the Docker configuration on my Fedora. The only change that I have made so far is the one that I did to resolve this problem:

karolnowacki@fedora$ cat /etc/docker/daemon.json 
 {
        "default-ulimits": {
                "nofile": {
                        "Name": "nofile",
                        "Hard": 20000,
                        "Soft": 20000
                }
        }
}

[knowack1]

I recently installed Fedora 42 Workstation from scratch and I'm having the same issue:

knowack1@fedora:~/Projects/everest-workspace$ docker run --rm --name mqtt-server  -p 1883:1883 -p 9001:9001 ghcr.io/everest/everest-dev-environment/mosquitto:docker-images-v0.1.0
1760766285: mosquitto version 2.0.10 starting
1760766285: Config loaded from /mosquitto/config/mosquitto.conf.
1760766285: Opening ipv4 listen socket on port 1883.
1760766285: Opening ipv6 listen socket on port 1883.
1760766285: Opening websockets listen socket on port 9001.
1760766285: Error: Unable to create websockets listener on port 9001.