Running "mkdocs serve" through Docker results in "Connection reset by peer"

[marc-guenther]

Context

This is on Mac, using Docker 26.0.0, and mkdocs 1.6.0, in a completely fresh project:

$ docker --version             
Docker version 26.0.0, build 2ae903e
$ docker run --rm  squidfunk/mkdocs-material --version
mkdocs, version 1.6.0 from /usr/local/lib/python3.11/site-packages/mkdocs (Python 3.11)
$ docker run --rm -v .:/docs squidfunk/mkdocs-material new empty-project
$ cd empty-project

Bug description

When I run the "serve" command:

$ docker run --rm -v .:/docs -p 8000:8000 squidfunk/mkdocs-material serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.11 seconds
INFO    -  [12:44:48] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [12:44:48] Serving on http://127.0.0.1:8000/

a subsequent curl does not work:

$ curl http://localhost:8000
curl: (56) Recv failure: Connection reset by peer

When i run it without the serve argument:

$ docker run --rm -v .:/docs -p 8000:8000 squidfunk/mkdocs-material
WARNING -  Config value 'dev_addr': The use of the IP address '0.0.0.0' suggests a production environment or the use of a proxy to connect to the MkDocs server. However, the MkDocs' server is intended for local development purposes only. Please use a third party production-ready server instead.
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.11 seconds
INFO    -  [12:45:47] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [12:45:47] Serving on http://0.0.0.0:8000/

everything is fine.

Please note the different IP address. It fails, when it binds to 127.0.0.1, but works, when it binds to 0.0.0.0:

$ docker run --rm -v .:/docs -p 8000:8000 squidfunk/mkdocs-material serve -a 0.0.0.0:8000

behaves exactly as leaving out the "serve" argument.

Related links

• Reporting a bug
• Issue search for "docker connection"

Reproduction

I have no idea what to put here, as this is an issue running through Docker, which happens with every project.
empty.zip

Steps to reproduce

x

Browser

No response

Before submitting

• I have read and followed the bug reporting guidelines.
• I have attached links to the documentation, and possibly related issues and discussions.
• I assure that I have removed all customizations before submitting this bug report.
• I have attached a .zip file with a minimal reproduction using the built-in info plugin.

[squidfunk]

Thanks for reporting. This is not a bug – you're overriding the default CMD (which is serve), but --dev-addr is missing. MkDocs must bind to 0.0.0.0, because 127.0.0.1 will not make the server available to the host. This is a limitation of Docker, not Material for MkDocs. The easiest way is to just drop serve from your command:

$ docker run --rm -v .:/docs -p 8000:8000 squidfunk/mkdocs-material

[marc-guenther]

Ah, I see, the default command is serve --dev-addr=0.0.0.0:8000, and when I just specify serve, I override both.

But still I would consider this a bug, as serve alone never works inside Docker, you always have to specify --dev-addr. This is very non-obvious and confusing (I wasted 45min trying to figure this out why suddenly everything stopped working, and those did not include writing this bug report)

Cannot the default dev-addr be changed when running from inside docker?

[squidfunk]

If you consider this a bug, you can raise this to the maintainers of MkDocs, since this happens regardless of the theme ☺️

We can only work with the API we get from MkDocs, and there's only the CLI's --dev-addr or the possibility to set dev_addr in mkdocs.yml. A possible solution would be for MkDocs to expose configuration options via environment variables, which we could set from the Dockerfile:

MKDOCS_CONFIG_DEV_ADDR="0.0.0.0:8000"

There has been a lot of activity on MkDocs lately, so I guess it's a good time to ask and revisit mkdocs/mkdocs#2108, which is definitely related. However, I recommend to create a new issue to forego necro-posting, because this topic has been very controversial, which you'll learn if you invest the time to read it 😅

[marc-guenther]

Whoa, that was quite an unexpected ride. I had no idea that a simple topic like this could be that controversial. As I don't want to cause another maintainer burnout, I think I will simply leave it as is... 🤣

[louwers]

I opened a new issue: mkdocs/mkdocs#3724

[squidfunk]

Great! Let's see if the maintainers can consider this now, with so many users wanting it ☺️