Mkdocs-material: MkDocs 1.1.1 breaks development server in Docker image

[sssarali]

Description

When I try to run my Dockerfile to serve the mkdocs site locally, I get an error about the dev-addr

Expected behavior

I expect the mkdocs site to successfully load locally at http://0.0.0.0:8000/

Actual behavior

mkdocs gives this error:

INFO    -  Building documentation... 
ERROR   -  Config value: 'dev_addr'. Error: 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. 

Aborted with 1 Configuration Errors!

Steps to reproduce the bug

docker run --it -p 8000:8000 image-id

Package versions

• Python: python 3.6
• MkDocs: latest version on github (I clone the mkdocs-material in my Dockerfile)

Project configuration

# Project information
site_name: Site Name
site_description: Site Description
site_author: Author
site_url: ""

# Repository
repo_name: test/test
repo_url: https://github.com/test/test
edit_uri: ""

# Copyright
copyright: "Copyright"

# Configuration
theme:
  name: null
  custom_dir: material

  # 404 page
  static_templates:
    - 404.html

  # Don't include MkDocs' JavaScript
  include_search_page: false
  search_index_only: true

  # Default values, taken from mkdocs_theme.yml
  language: en
  features:
    - tabs
    - instant
  palette:
    primary: blue
    accent: blue
  font:
    text: Roboto
    code: Roboto Mono
  icon:
    logo: logo
  favicon: assets/images/favicon.png

# Customization
extra:
  social:
    - icon: logo
      link: https://www.test.com/

# Extensions
markdown_extensions:
  - markdown.extensions.admonition
  - markdown.extensions.attr_list
  - markdown.extensions.codehilite:
      guess_lang: false
  - markdown.extensions.def_list
  - markdown.extensions.footnotes
  - markdown.extensions.meta
  - markdown.extensions.toc:
      permalink: true
  - pymdownx.arithmatex
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
        # - pymdownx.highlight:
      #     linenums_style: pymdownx-inline
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.magiclink:
      repo_url_shorthand: true
      user: squidfunk
      repo: mkdocs-material
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.snippets:
      check_paths: true
  - pymdownx.superfences
  - pymdownx.tabbed
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

#yamllint disable rule:line-length
nav:
     - Introduction:
          - test: test.md

System information

• OS: Mac
• Browser: Google Chrome

[squidfunk]

That's an upstream issue. It seems that MkDocs 1.1.1 forbids the dev server to run on 0.0.0.0, see https://github.com/mkdocs/mkdocs/issues/2108

Let's hope they revert this behavior. Otherwise it'll render any usage of the Docker image useless.

[squidfunk]

Or wait, let's leave this issue open until it is resolved.

[sssarali]

Is there any workaround for now to get mkdocs on a development server using the Docker image?

[squidfunk]

Yes, pin the dependency to 1.1:

mkdocs==1.1

[squidfunk]

I just pushed 02f058bc after reading https://github.com/mkdocs/mkdocs/issues/2108#issuecomment-627562040, which points out that ::0 should work as well, and my testing shows that it does. Let's hope this doesn't get patched either.

[squidfunk]

MkDocs 1.1.2 was just released which reverts the behavior and should issue a warning. I'm therefore closing this issue.

[busches]

I'm still seeing this issue running the following: docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material:5.3.3

WARNING -  Config value: 'dev_addr'. Warning: 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. 

Is there something else I need to change in my mkdocs.yml?

[squidfunk]

It’s only a warning. It was the deliberate decision of the MkDocs maintainers to leave it like that. Nothing we can do about, unfortunately.

[busches]

We're running in strict mode, meaning it's an error. May want to call out
that it's no longer possible to use the flag in the latest version.

On Fri, Jun 26, 2020, 9:42 AM Martin Donath [e-mail]
wrote:

It’s only a warning. It was the deliberate decision of the MkDocs
maintainers to leave it like that. Nothing we can do about, unfortunately.

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/squidfunk/mkdocs-material/issues/1691#issuecomment-650216076,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/AAGRMZDA4M7HRAVBDEZIC4TRYSXU3ANCNFSM4M73XLZQ
.

[mrmanc]

@squidfunk Just want to say thanks so much for your advocacy on the mkdocs issue thread. It was nice to see a rational and compassionate approach. Looking forward to finding a solution as we also run in strict mode.

[squidfunk]

@mrmanc thanks, that was a wild ride indeed. I'm quite satisfied with the outcome, though it's not perfect yet, but let's hope that waylan will come back at some point and reconsider.

[mrmanc]

We're also going to talk about whether we can do anything to help on mkdocs. I took a look at the issues and the community seem to be responding, but I don't know if that’s new. I was wondering if publishing an mkdocs Docker container with a built in production server would help reduce the pain that Docker users are causing the mkdocs maintainers. We deploy to kubernetes with an in house image which extends an in house Python image, but I was wondering if your Material image could be split so that it extends an mkdocs one. Apologies if you'd rather not discuss that in this issue 🙂

[squidfunk]

I'd be interested to see how you'd solve this problem because currently, the mkdocs executable is the entrypoint of the official Docker image. All mkdocs commands should still work, that's a must. Furthermore, a requirement would be that the image size is not blown up by a few dozen megs. I'm definitely curious in discussing possibilities, but let's do that in a new issue!

[SalmonKing72]

I'd be interested to see how you'd solve this problem because currently, the mkdocs executable is the entrypoint of the official Docker image. All mkdocs commands should still work, that's a must. Furthermore, a requirement would be that the image size is not blown up by a few dozen megs. I'm definitely curious in discussing possibilities, but let's do that in a new issue!

I am still experiencing this problem. Has a new issue been opened in regards to getting it addressed?

[squidfunk]

What problem? MkDocs 1.1.2 will only print a warning, everything else should work as expected.

[SalmonKing72]

What problem? MkDocs 1.1.2 will only print a warning, everything else should work as expected.

MkDocs is failing to start up in docker with the following in the logs. Using the 5.5.14 image.

WARNING - Config value: 'dev_addr'. Warning: 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.
Aborted with 1 Configuration Warnings in 'strict' mode!

even though my mkdocs.yml is configured as follows

...
strict: true
dev_addr: 127.0.0.1:8000
...

[squidfunk]

Yes, strict will not work anymore since the change was introduced. Unfortunately, there's nothing we can do about it, since Material for MkDocs is only a theme and this is something that would need to be changed in MkDocs. The only thing you can do is vouch in the linked issue for returning back to the original behavior.

EDIT: the fact that dev_addr is not respected, is because the Docker image will not work without setting the address to 0.0.0.0, as the service would not be visible outside Docker. This is done by Material's official Docker image:

https://github.com/squidfunk/mkdocs-material/blob/a3c0e46d123e78d9da0c3986e26b5ff188f8fd9d/Dockerfile#L63