Change to prevent 0.0.0.0 makes containerized usage painful

[acaos]

The change in 1.1.1 to prevent the usage of 0.0.0.0 makes using MkDocs in a container painful. We have a local development environment used by our developers which spins up a documentation repository that they can live-edit, with MkDocs hosted inside a Docker container. This is now significantly more difficult.

[waylan]

We do not support using the server on anything except the local machine. We never have and never will. The only change is that we are now enforcing it. In other words, you have not been using the server in a supported way. We have never guaranteed that it would continue to work for you. If you want to use a server on anything other than the local machine, then we have always suggested that you use an appropriate third-party server.

[acaos]

These are used by developers on local machines, just within a Docker container to keep MkDocs isolated from the rest of the environment. We properly use mkdocs build when documentation is released, and you are completely correct in your assertion that it should not be used outside a local machine.

This change means we (and anyone else using mkdocs serve in a container) need to either maintain a modified version of MkDocs, a configuration file with mangled addresses, or a (moderately, but not extremely) complex script to inspect the local network and determine exactly the right address to bind to every time the container spins up.

Further, I believe this change is fragile - it does not prevent the use of (for example) 0.0.0.00 or [::0] as a wildcard bind (even though neither is the most reduced form).

If security is the primary impetus behind this change, adding a banner to the default theme when a wildcard bind is detected (that must then be removed by customizing the theme) or requiring a matching environment variable to permit such binds would probably be better solutions.

[waylan]

to keep MkDocs isolated from the rest of the environment

If that is all you are doing, a Docker image seems like overkill to me. A Python venv works great and it what I use.

[acaos]

It's actually part of a larger set of developer tooling:

Developers edit OpenAPI YAML files, which are run through source code generators as well as a Widdershins watcher which generates Markdown. The Markdown is injected into MkDocs so as developers modify API specifications they can review the resulting stubs and documentation before it is committed.

Our developers work on several different platforms and our docker-compose environment ensures everyone can easily have all the tooling at hand to work with our code base - which is not as large as many out there; I'm sure there are many developers using MkDocs' flexibility and and live editing in more complex ways than this as part of a documentation pipeline.

Compatibility with containers is important in modern environments; being flexible on this will endear you to a lot of developers who may well look for another tool if they have to struggle to get this working inside Docker when they want to try MkDocs out.

[VTLee]

I agree with this issue -- this makes a docker-compose bind of 127.0.0.1:8080:8080, which is both non-production and not (external) network accessible, fail to start.

We already use docker for several things, so our limited (1-2 person) multi-hat IT staff already give out machines with docker ready... making it a simple git clone and docker-compose up... doesn't matter what OS.

while venv is perfectly suitable for programers and IT Ops people, it's not the best for business staff that don't even understand Markdown before approaching this.

[waylan]

If you require a complex environment like that, and have the expertise to get it all working, then adding a third party server to your container should be little trouble for you.

_{Sent with GitHawk}

[mikedoug]

Why the hostility towards containerization? It's here and it governs the world of many in the this industry. Having it in a Docker along with our other 10+ services that are spun up in our docker-compose environment means that it is just one of a dozen services that are ready to go with a single, simple docker-compose up.

[inakianduaga]

If you require a complex environment like that, and have the expertise to get it all working, then adding a third party server to your container should be little trouble for you.

It's not massive trouble but it's more trouble than zero, which is the way it was until now. I'm kinda speechless that it would be so hard to understand that the feature useful for a lot of people, and the level of hostility in the responses. Using python venv is not a solution for a product that has nothing to do with python, but it's about writing docs. In our company we want any engineer to be able to contribute to the docs, and for this they should be able to 1-click start the project, which until now was easily doable with this Dockerfile

FROM python:3.7-stretch

WORKDIR /usr/src/app

# Install dependencies and fire server w/ automatic reloading
CMD [ "sh", "-c", "pip install --cache-dir=.pip -r requirements.txt; mkdocs serve -a 0.0.0.0:8000" ] 

Now I will need to create a docker-compose with some some workaround or nginx just to fake the host which makes zero sense. The only reason to put a 0.0.0.0 validation is to help devs not make mistakes, yet you're making life harder for a subset.

[VTLee]

@inakianduaga I just made a similar change for my employees... Apparently putting it behind a reverse proxy breaks live reloading... They were a bit disappointed.

If you (or anyone) figures out a solution to work around this, I'd love to see how to preserve it behind a reverse proxy

[inakianduaga]

@VTLee If you're on linux you can simply run the container using host networking and it should work. We are on macs so that doesn't work. I guess the easiest is to lookup the docker host ip on the host and pass it as an ENV variable to the container on the docker run command (passing host.docker.internal also doesn't work because it also breaks mkdocs built-in validation)

[squidfunk]

This change prohibits any usage of the MkDocs dev server inside of Docker and I strongly advocate against this change. Providing MkDocs inside of a Docker image with dependencies preinstalled is a very important and real use case. In fact, the Material for MkDocs Docker image has been pulled over 800k times.

Another use case I frequently encounter is when I want to preview the docs on my local machine, as well as on my mobile phone, which 0.0.0.0 makes very convenient.

Please revert to the old behavior. This will cause huge frustration among developers and a flood of incoming issues. I don't understand why this change is necessary.

[waylan]

putting it behind a reverse proxy breaks live reloading

This has never worked and results in a constant stream of requests from users. The change under discussion was intended to curtail this requests by informing the user that this is not supported.

This will cause huge frustration among developers and a flood of incoming issues. I don't understand why this change is necessary.

If a solution can be provided which allows docker containers but does not permit any other use outside of the local machine, I'm willing to listen. Personally, I have never saw any benefit to docker containers and the support requests are a contact burden and annoyance to me. I would prefer that you instead use a third party server.

The only alternate approach I have considered thus far is removing the server altogether. I certainly don't need it, as it is easy enough to use a third party solution. But I'm open to other suggestions.

[waylan]

the level of hostility in the responses

Sorry, I don't mean to be hostile, but I am extremely annoyed and frustrated that users continue to insist on using the sever in a way that we continue to state is not supported. We have continually insisted that a third party server should be used and yet it has fallen on deaf ears. Personally, I don't have time to support this and no-one else has made themselves available to do so.

[squidfunk]

Personally, I have never saw any benefit to docker containers and the support requests are a contact burden and annoyance to me. I would prefer that you instead use a third party server.

You underestimate how many people are not proficient in Python and look for a one-stop solution. There's a large community of technical writers (as my survey shows), and from my own experience with Python I can say that setting up a clean environment is far from being easy. There're several methods like virtualenv, pipenv etc., all with their caveats. Sadly, it's not as easy as npm.

Also, how should MkDocs be integrated with a third-party server for serving assets and live-reloading? If you could give some guidance, we can work towards a solution, but just taking this feature away from the users is not so nice.

Sorry, I don't mean to be hostile, but I am extremely annoyed and frustrated that users continue to insist on using the sever in a way that we continue to state is not supported.

Where's this frustration coming from? Users want to put the development server in production? How about just printing a warning when running on 0.0.0.0 "Warning, this development server is not meant for production use."?

[michaelkrupp]

Fully agree with @squidfunk. This change just broke my local (docker-based) development environment without warning. I had been using the same setup for over a year now, working flawlessly.

This change is outright hostile to docker-based setups, and not really effective anyway in what it is trying to do, as @acaos pointed out above. Simply using --dev-addr 0.0.0.00:8000 (or similar variations) instead still does work.

However, I do understand your frustration and not everyone is into Docker either. Therefor I'd like to suggest to put this change behind another parameter and printing out a big fat warning when used:

$ mkdocs serve --livereload --dev-addr 0.0.0.0:8000 --i-know-what-i-am-doing-and-innocent-kittens-may-get-killed-because-of-it
#################################################################
### The MkDocs' server is intended for development purposes   ###
### only. Therefore, '0.0.0.0' is not a supported IP address. ###
### Please use a third party production-ready server instead. ###
#################################################################
INFO    -  Building documentation...

The default behavior then could still be the current one.

[VTLee]

I'd be fine with a completely obnoxious flag over a flat-out 'crash'...

mkdocs serve --allow-non-production-and-unsupported-bind-to-all-ips

really call it what you want -- but if you require them to use a flag like this, I would hope it's fairly obvious that 1) It's unsupported, and 2) it's not for production use

I also would combined this with @michaelkrupp 's suggested output when used

[waylan]

@squidfunk you make some good arguments, however...

You underestimate how many people... look for a one-stop solution.

This is part of the problem. We don't offer a one-stop solution. We never have. We offer a local development solution only. Anything outside of that has never been part of MkDocs. The fact that some users have hacked it to be a a risk they took.

... from my own experience with Python I can say that setting up a clean environment is far from being easy.

And a Docker Container is easy? Seems to me like venv is worlds easier to work out that docker. So long as we are talking about docker, this argument will never hold for me.

There're several methods like virtualenv, pipenv etc., all with their caveats.

And only venv is included in the standard lib. Why would you consider anything else? But I digress.

Also, how should MkDocs be integrated with a third-party server for serving assets and live-reloading?

I haven't researched the options myself, but the live-reload server is based on a standard (which is not unique to nor originates with our server). If npm is so easy, I'm sure there are multiple node servers which would work quite well for this. And they would be better supported. As you are well aware, the python based server we use is currently not being maintained. If we change servers (due to lack of maintenance) we likely would loose the live-reload feature as I'm not aware of any other Python solutions and I don't have the resources to maintain one myself. If that were to happen, I suspect everyone involved in this conversation would move to a third party server anyway. Think of this as a push in that direction.

Users want to put the development server in production?

Yes, that is a very common request. We could issue a warning, but given how those users react when they are informed we don't support production use, they would just ignore the warning. Therefore, I was trying to force the issue.

Truth be told, I expected there to be some backlash, but not from those using docker containers. Admittedly, as I don't use docker, it hadn't occurred to me that that would be an issue.

That said, I don't see why we should support them. Our server is not to be used outside the local machine. From one perspective a docker container is not the local machine.

[acaos]

@VTLee

@inakianduaga I just made a similar change for my employees... Apparently putting it behind a reverse proxy breaks live reloading... They were a bit disappointed.

If you (or anyone) figures out a solution to work around this, I'd love to see how to preserve it behind a reverse proxy

You can do this with nginx with a block similar to this:

    location / {
        add_header Access-Control-Allow-Origin $http_origin;
        add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";

        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Port $server_port;

        set $backend "http://127.0.0.1:8080";
        proxy_pass $backend;
        proxy_http_version 1.1;
        proxy_redirect off;
    }

That or just use mkdocs serve -a 0.0.0.00:8080.

[waylan]

I've given this some more thought and I see a few possible solutions, in order of (increasing) severity, although not necessarily order of preference:

• Someone else steps up and volunteers to maintain the server code. Their first commit can be changing the error to a warning. But I expect them to honor their word and stay with the project.
• The current behavior remains.
• The server is completely dropped and users are responsible to go find their own solution. Perhaps we could offer a few recommendations in the docs.
• I walk away from MkDocs.

To be fair, I'm not completely satisfied with any of those myself. But I don't have any other ideas.

[waylan]

You can do this with nginx with a block similar to this:

@acaos you are perpetuating the problem. We do not support using proxy server with the included server. Every time someone comments with a "working solution" that is just one more date point which reinforces the need to forcefully disable it.

[mikedoug]

@waylan you don't understand that people want to run this in a Docker on their local development system SO THAT they don't have to worry about even having Python installed. With Docker, I can trivially run a local development version on a Windows box using Docker Desktop -- without having to know anything about that Python Jazz. There are probably another twenty "why this is good to allow us to run your awesome tool in Docker" that we can come up with...

Leave your new behavior as default and add a --force-insecure-bind-all command line parameter that allows those of us who know what we're doing to do continue to use it within a Docker on our local development systems. It's a really simple solution that allows you to have the default behavior and you even get to call the feature "insecure" so that nobody can be surprised by it.

[waylan]

@waylan you don't understand that people want to run this in a Docker on their local development system SO THAT they don't have to worry about even having Python installed.

If you have such an aversion to Python, then why are you using a Python based tool? There are certainly more than enough competing products to chose from developed in any number of languages.

In looking at the various options out there, I came across a number of products where the docs basically said: just download and launch this docker container and you get a one-stop solution. All I saw was a mysterious black box. When I found MkDocs, I understood how it worked. I found a product I was willing to use. It seems some of you want the black box. I can't identify with that mindset.

Leave your new behavior as default and add a --force-insecure-bind-all command line parameter that allows those of us who know what we're doing to do continue to use it within a Docker on our local development systems. It's a really simple solution that allows you to have the default behavior and you even get to call the feature "insecure" so that nobody can be surprised by it.

The issue is not that it is "insecure." A more appropriate name for the flag might be --enable-proxy-connections which I have repeatedly stated that we have never supported. Either we support a feature or we don't. The fact that a flag exists to enable a behavior suggests that we support it. And no one is going to accept the 'you can only use that feature if you know what you are doing' response. In other words, adding a flag makes it worse not better as we can no longer claim we don't support that use case.

As I think about it, it occurs to me that anyone who is using a docker container has been using a proxy. Therefore this has always been unsupported. The fact that it worked as all was a coincidence. Even if we removed the forced error, the entire thing could break at any time for any number of reasons. It would be a disservice to our users to suggest otherwise.

[squidfunk]

If you have such an aversion to Python, then why are you using a Python based tool? There are certainly more than enough competing products to chose from developed in any number of languages.

You fell into the common trap thinking that people choose solutions because of their underlying technologies. This might be true for developers, who question every layer of the stack, but MkDocs solves problems of non-technical people, i.e. technical writers, who mostly don't care about the underlying technology. Personally, I'm not a fan of Python. I dislike the syntax and the whole environment. However, I built one of the most popular third party themes for a Python-based static site generator, because I believe in its values – not in its technology.

In looking at the various options out there, I came across a number of products where the docs basically said: just download and launch this docker container and you get a one-stop solution. All I saw was a mysterious black box. When I found MkDocs, I understood how it worked. I found a product I was willing to use. It seems some of you want the black box. I can't identify with that mindset.

It's fine to speak of your own expectations evaluating a new technology, but a project with 10k stars should also consider the expectations of users. To you, Docker is a black box. To me, it is Python. I'm actually more familiar with Docker than Python. Still, I love MkDocs.

[mikedoug]

As I think about it, it occurs to me that anyone who is using a docker container has been using a proxy.

This is inaccurate. In fact, in our use, in a Docker, on our local development systems, is doing nothing more than simple port forwarding. There's no HTTP proxy server in the middle. This is the standard way for using Docker locally for development and many other things.

This change isn't preventing proxies at all either -- proxies can explicitly route to loopback... In fact, you're expressly pushing people towards a proxy solution as a work around.

I would like to plead with you to just add -some-command-line-option to disable this new default behavior. It will end a lot of pain for people today and for a long time to come.

[michaelkrupp]

@waylan Please reconsider your decision. As stated above, I do understand that you are not familiar with Docker and do not want to use it personally. That is fair, and I have been on the same track couple of years ago.

Fact is though, that docker has become the de-facto standard for many of us. For someone like me it has become indispensable by now, as I do not develop in just one or two language on a daily basis, but somewhere in the ballpark of 25. Maintaining 25 tool-chains on 4 devices is just not practical. With docker I can abstract all of this and just not care about how the internals work. Everything is just a simple docker pull away.

Python is my favorite language (and has ever been since 2.3) by a huge margin - I absolutely love it. But its ecosystem currently is just a huge mess and a major pain in the a** to work with. Docker solves this problem for the most part.

The change you made will just spawn work-arounds, of which two have already been posted here.
Another one would be to simply monkey-patch that config validator method via a mkdocs-plugin. All of those are arguably worse than a clean --iknowhatiamdoing command line switch.

People who want to run it in production will do so, no matter how hard you try to stop them. Please do not throw us Docker users under the bus and force us to use ugly hacks just because you get annoyed with people running unsupported configurations.

We all love MkDocs, and we want to keep using it in our Docker environments 💗

[cirego]

I will add my voice to the requests to please enable 0.0.0.0 as a bind address once again. I work in a polyglot environment and use Docker to provide a consistent developer environment for all team members, regardless of technical background. If my team members are required to become Python developers in order to use mkdocs, they will reject mkdocs.

[acaos]

I've created a MkDocs + BrowserSync Docker configuration which can be used for automated reloading. Hopefully this will provide an alternative or template to those who are having issues with mkdocs serve in a Docker, and also a backup in case the serve functionality breaks or is entirely removed.

It can be found at: https://github.com/acaos/mkdocs-browsersync

I still believe it would be ideal to revert this change.

[squidfunk]

I am leaning very heavily toward the last option. I'm willing to make one final release which restores the behavior and step away. This issue has made it clear that MkDocs is causing me too much stress. The change under discussion was an attempt to reduce that stress but has instead increased it. I don't have any good reason to stay here. I can perhaps use the time to focus on a few other ideas I have't had time to explore.

It would be really sad if you'd walk away from MkDocs, but I myself know this kind of fatigue. It can really bring you down and I've been there in the past. Maybe it's best if you take some time off and try to recenter yourself. Explore some new ideas. Though, hopefully, you'll come back! You, Douglas and Tom have built quite a legacy 😊

[facelessuser]

I would also suggest maybe we should put up some help wanted sticky issues requesting help in maintenance. Maybe outline a couple areas we'd like to see additional help.

[geoknee]

I stumbled across this issue today (coming from squidfunk/mkdocs-material#5855). Several years on, I wonder if the maintainers of mkdocs now feel it is worth changing the behaviour? Thanks

[pawamoy]

Is it mandatory for you to serve in strict mode? Can't you check your docs without setting the IP address to 0.0.0.0 first, and if they raise no warning you know you can serve them without strict mode?

[cmaster11]

For those who are coming here after all these years, I've got a snippet that works fine for me (using the mkdocs-material image, but it will work for any other as well):

docker run --rm -it --entrypoint /bin/sh -p 8000:8000 -v $(pwd):/docs squidfunk/mkdocs-material:latest -ec 'exec mkdocs serve "--dev-addr=$(ip route get 1 | awk '"'{print \$NF;exit}'"'):8000"'

I use it inside a yarn script, like:

"scripts": {
  "docs:watch": "docker run --rm -it --entrypoint /bin/sh -p 8000:8000 -v $(pwd):/docs squidfunk/mkdocs-material:latest -ec 'exec mkdocs serve \"--dev-addr=$(ip route get 1 | awk '\"'{print \\$NF;exit}'\"'):8000\"'"
}

It is not the prettiest, but with that:

1. The IP is automatically inferred from the Docker container (e.g. 172.17.0.6)
2. I can connect using http://127.0.0.1:8000
3. No warning, strict mode works!
4. Works on non-linux machines (e.g. if you're on Windows or MacOS you cannot use the --network host flag, where you could then easily listen on 127.0.0.1 as a hack)

[squidfunk]

It would really be amazing if we could revisit this topic and remove the warning message, or add a --yes-i-know-what-im-doing-please-leave-me-alone flag that suppresses the error message. Not being able to use strict mode is a bummer.

[squidfunk]

@oprypin could we maybe get entirely rid of this warning? Moving it into the serve command will give us no option to remove it expect for filtering it out. This warning does not prevent people from using the development server as a production server, or at least as an internal application server behind a reverse proxy (Using the dev server on 127.0.0.1 does not print a warning). Thus, from my experience talking users, it's more or less a "⚠️ hot contents inside" on a coffee cup.

Until this is released, here's a 2-line workaround I found to silence the warning and let strict mode pass:

from mkdocs.config.config_options import IpAddress
IpAddress.post_validation = lambda *args, **kwargs: None

[maxadamo]

I kind of disagree/agree with both sides.
Of course, in this day and age, Docker is the way to go for such a small application (a full fledged VM would not make much sense to me), but I can understand the objection that a Dev server is a Dev server.

I couldn't get gunicorn running in front of mkdocs-material, and I created an image, based on mkdocs-material, NGINX, gunicorn and Flask.
Flask is used to provide a hook (to reload the application on the fly and re-run mkdocs build), and to provide a health-check URL.
But, even Flask provides a Dev server only, hence I had to use gunicorn.
There you go: https://github.com/GEANT/docker-devops-wiki

[louwers]

We are also using Docker for easily spinning up a dev environment with MkDocs.

Unfortunately, this broke after we turned on strict mode. 😞