Mkdocs-material: Provide an official docker container with a production server

[mrmanc]

__I checked that...__

• [x] ... the documentation does not mention anything about my idea
• [x] ... to my best knowledge, my idea wouldn't break something for other users
• [x] ... 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]

As mentioned in https://github.com/squidfunk/mkdocs-material/issues/1691#issuecomment-662558128, I have quite some concerns regarding size and usability. If you can draft a solid proposal that covers all use cases (to be enumerated), we can work towards a solution together, but I'm afraid I currently don't have time to work on the Docker runtime. The runtime works, albeit with a warning, but as it's not used in production it doesn't matter that much.

[squidfunk]

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.

That is exactly the case waylan wants to omit, and I'm seconding him on this opinion. What I don't agree on is to make it impossible to expose MkDocs on 0.0.0.0, so Dockerizing fails entirely, but I'm okay with the warning. I think providing a Docker production runtime is out of scope for this project, as this project produces static HTML which can be hosted in one million different ways.

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).

I think that's too many moving parts. For the part of Material for MkDocs, I want to keep it as simple as possible. The new docs include deployment instructions to GitHub Pages and GitLab, and we can add more (S3, ...), but I don't see much value in providing a packaged web server solution, as that's too opinionated. Maybe you could implement this as part of a downstream project like Material for MkDocs is a downstream project of MkDocs?

[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.

[mrmanc]

Sorry… I started a reply to this and got distracted.

That is exactly the case waylan wants to omit, and I'm seconding him on this decision.

Running the development server in production? Absolutely—I’d aim to make it easier not to do this.

I think providing a Docker production runtime is out of scope for this project, as this project produces static HTML which can be hosted in one million different ways.

That is fair enough. I’m happy that this lives as a separate repo. It could start by building using the image you’ve built, then adding Nginx.

I don't see much value in providing a packaged web server solution, as that's too opinionated

Yep, always a tricky trade-off!

Maybe you could implement this as part of a downstream project like Material for MkDocs is a downstream project of MkDocs?

Sure, I think starting that way makes sense. Eventually, I’d like to provide a solution for those who use mkdocs without Material as well.

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

Sounds sensible. I’ve got some other changes on the backburner for when I get some dev time, so this might come after that, but I’ll get in touch if and when.

Thanks for your input—totally rational and helps me find a direction for this. 😃

[squidfunk]

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