Provide an official docker container with a production server

I checked that…

• … the documentation does not mention anything about my idea
• … to my best knowledge, my idea wouldn’t break something for other users
• … there are no open or closed issues that are related to my idea

Description

So far, the Material Docker container gives people portable access to mkdocs and all of the things it can do. It is my understanding that people rely on running the mkdocs development server via Docker to host their built website, rather than hosting the built static site under a simple webserver.

Googling ‘mkdocs docker’, I find a bunch of containers doing a lot of similar stuff. For example

• https://github.com/squidfunk/mkdocs-material/blob/master/Dockerfile
• https://github.com/pozgo/docker-mkdocs/blob/master/Dockerfile
• https://github.com/DG0lden/mkdocs-docker/blob/master/Dockerfile
• https://github.com/teamdeeson/mkdocs/blob/master/Dockerfile

My proposal is that there could be an official base mkdocs Dockerfile, based on python:3.8.1-alpine3.11 much as yours is. That could provide the mkdocs runtime.

Another Dockerfile with a multi stage build could first build the site using the above image, and then serve using something like Nginx as a second stage with a smaller set of dependencies. That would provide an easy option to publish the site to a container platform (such as many enterprises now use), using Docker to package their built site into a container, which doesn’t need to have Python or mkdocs or any of the plugins on the built image installed.

A sample docker-compose file could allow users to run docker-compose up to start a preview of their site (by mounting the appropriate files and running the base image with the command set to serve using the mkdocs runtime).

A Dockerfile which extends from the base image could install the mkdocs-material dependency and could belong to this project, still allowing people to run a preview of a Material site with no Python knowledge. This image should be no larger than the one you provide already since it does the same thing: install mkdocs and material dependencies over alpine.

I’m open to raising this suggestion in the mkdocs repo, but I thought it would be good to discuss with you, as mentioned here.

I also worry that I might not have explained that well, so if it doesn’t make sense please say so 😃 We use a very similar approach with how we host our mkdocs site on Kubernetes, so I’m fairly confident it is possible.

Use Cases

• less duplication of images designed to provide an mkdocs runtime
• an easy way for users to package their site into an efficient production runtime suitable for any Docker hosting platform
• it would be easier for users not to use the development server in production, reducing the headaches for the mkdocs maintainers
• users would not have to remember a complicated command to kick off a local preview

Screenshots / Mockups

[squidfunk]

So, essentially, I think this should be solved as a downstream project. Material for MkDocs is just a template for MkDocs. It provides its own Docker container for convenience, aimed at easing the writing and building of documentation. Hosting is a completely different topic.

If you start working on this, we can review whether it makes sense to advertise a solution in the docs.

[squidfunk]

Okay, cool! Just comment on this issue if you make any progress 😊