RaspberryValley MkDocks Docker Image

We write a lot at the Raspberry Valley makerspace. To share our tools without the hassle of installation, we reverted recently to Docker deployments, both for techies and authors.

This is our Docker Image for running MkDocs. It is based on Alpine, a minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size. We were inspired by elamperti and his MKDocks image.

Our Dockerfile and instructions are is available at GitHub. Read detailed release notes in our ChangeLog document.

NOTE: As of release 1.2 we have changed to Python 3 in the backend, and to support of Jupyter notebooks via mknotebooks. This results in a much larger image size. If you don't need Jupyter, you'll still be safe with release 1.1

About

Raspberry Valley is a maker community in Karlskrona, Sweden. We work with Raspberry Pis, Arduinos and other interesting hardware.

This repository is here to support our community of makers. A lot of our achievements are based and inspired by the community at large. We wish to pay back and share our experiences and lessons learned.

You can find our pages here: Raspberry Valley. You can also check Docker Hub for images of interest.

Introduction

This documentation describes the creation and usage of the MkDocs image. On top we provide a few PowerShell scripts to simplify day-to-day authoring of content.

If you don't want to roll your own, but start using the image, jump to the section Pulling the image from Dockerhub below. We do recommend to be careful about third party images and to validate the image before installing.

To learn more about setting up your project in MkDocs and working with the tool, see the MkDocs Getting Started manual.

Please note: We always assume that you run all commands from the directory where your MkDocs site is, or will be. You can easily confirm you are in the right directory if you see the Yaml file.

Once you have setup your MkDocs/Docker environment, as described here, you might want to take the next step and automate your site deployment. If it's Azure you are targeting, you're in luck; we have a solution and guide for Deployment of MkDocs to Azure

Building the image

First, let us prepare our image.

Navigate to an empty folder and pull this Git repository
Open your shell (both the Dos prompt and PowerShell will work) and run the following

docker build -t raspberryvalley/mkdocs .

You should end up with output similar to this:

NOTE: please don't forget the dot at the end of the command

Push image

We can push our image to Docker Hub. We assume here you have an account and can log in.

First, let's 'tag' the image. Basically give it a 'label' which identifies a version of the system, target platform etc.

docker tag raspberryvalley/mkdocs raspberryvalley/mkdocs:1.3.2

Let us now push the docker image to Docker Hub (you need to login first)

docker login
docker push raspberryvalley/mkdocs:1.3.2

You should see something similar to this:

And, on your Docker repository, you can see the image for re-use. Don't forget to edit the title and the description. The example above obviously points to our hub, substitute '''raspberryvalley''' to a hub of your choice.

Pull MkDocs image from Docker hub

Now we have sorted out everything, we have our brand new image on Docker Hub. If you want to skip all the above, you can simply use our image to get started. Time to Pull the image.

docker pull raspberryvalley/mkdocs:1.3.2

After a bit of downloading, you will be ready to create your own sites.

Starting a new MkDocs project

You might need to start a new project using the MkDocs inbuilt features. It really is trivial and not always needed. But just in case, this is how you start one in the current directory.

docker run -it --rm -v $(pwd):/mysite raspberryvalley/mkdocs:1.3.2 new .

Serving an MkDocs project

The current project directory will be served and can be tested in your browser

docker run -it --rm -v $(pwd):/mysite -p 8000:8000 raspberryvalley/mkdocs:1.3.2 serve -a 0.0.0.0:8000

Building an MkDocs project

To generate a static site using the docker image, run

docker run -it --rm -v $(pwd):/mysite raspberryvalley/mkdocs:1.3.2 build

Notes:

We assume you are in a directory where a valid MkDocs site is
$(pwd) expands the current directory. There are issues in Windows doing this. In such a case, expand to the full path in the command-line. It can be of interest, that if you use this expansion inside a PowerShell script, it will work.

docker run -it --rm -v c:\somedirectory\somesite:/mysite raspberryvalley/mkdocs:1.3.2 build

docker run -it --rm -v /c/somedirectory/somesite:/mysite raspberryvalley/mkdocs:1.3.2 build

It's a good idea to remove the container immediately after it was used. Use the switch --rm to achieve this

Powershell Scripts

It is tedious to always write the full docker commands on the command line. Now I do not recommend to use the below scripts immediately (there's no better learning than getting the manual effort into your bloodstream), but once you are convinced you know how things work, it's time to start working with our PowerShell Scripts.

Just copy the scripts from our ps-scripts directory somewhere onto your path, or simply copy-paste the scripts from below.

Creating a new website

To create a new website in mkdocs, simply use the script below. The name in the scripts directory is mkdocsnew.ps1. Note this scripts creates a new site in the current directory of your powershell console by utilizing our mkdocs image. The mkdocs parameter 'sitename' is ignored.

# Script to create a new mkdocs repository using our Docker image

Write-Host
"Create new mkdocs site
=======================
This script creates a new mkdocs site using the raspberryvalley/mkdocs image (version 1.3.2)
in the current directory.

Docker Hub : https://hub.docker.com/r/raspberryvalley/mkdocs/
Github     : https://github.com/raspberryvalley/docker-mkdocs/
"

# docker run -it -v $(pwd):/mysite mkdocs new .
$command = "docker run -it --rm -v $(pwd):/mysite raspberryvalley/mkdocs:1.3.2 new ."
Write-Output $command
iex $command

Once you run the script on a directory, you can see something similar to the below:

Serve existing mkdocs site

To serve an existing site you your local machine, yuu can use the powershell script mkdocsserve.ps1. Navigate to the directory where your site is (in powershell), then simply run the script (grab it from our repository or use the code below). If the script is on your path, you're in business.

# Script to serve an existing mkdocs site using our Docker image

Write-Host
"Serve mkdocs site (from current directory)
===========================================
This script serves an mkdocs site using the raspberryvalley/mkdocs image (version 1.3.2)
in the current directory.

Docker Hub : https://hub.docker.com/r/raspberryvalley/mkdocs/
Github     : https://github.com/raspberryvalley/docker-mkdocs/
"

# docker run -it --rm -v $(pwd):/mysite -p 8000:8000 mkdocs serve -a 0.0.0.0:8000

$command = "docker run -it --rm -v $(pwd):/mysite -p 8000:8000 raspberryvalley/mkdocs:1.3.2 serve -a 0.0.0.0:8000"
Write-Output $command
iex $command

Your output in the console can be similar to the below

Build existing mkdocs site

Time to build an existing mkdocs site. You can use our script mkdocsbuild.ps1 or simply copy the script below. Navigate to the directory with your mkdocs source and invoke the script.

# Script to build an existing mkdocs site using our Docker image

Write-Host
"Build mkdocs site (from current directory)
===========================================
This script builds an mkdocs site using the raspberryvalley/mkdocs image (version 1.3.2)
in the current directory.

Docker Hub : https://hub.docker.com/r/raspberryvalley/mkdocs/
Github     : https://github.com/raspberryvalley/docker-mkdocs/
"

$command = "docker run -it --rm -v $(pwd):/mysite raspberryvalley/mkdocs:1.3.2 build"
Write-Output $command
iex $command

The output is as follows.

Run all actions from one script

If you prefer, you can use our script docker-mkdocs.ps1. This combines all the 3 above mentioned scripts as one, and can be used as follows.

docker-mkdocs.ps1 [new|serve|build]

Same thing, one script file with options.

We have also attached a podman file, if you prefer to use podman on your system. Usage is the same:

podman-mkdocs.ps1 [new|serve|build]

Known Issues

This section is a list of fixes for known issues. We searched for a solution, so you don't have to.

Error Starting userland Proxy

Recently we are getting this error on some configurations:

 Error response from daemon: driver failed programming external connectivity on endpoint tender_cocks (5678ab713xy7a2d97eb3b746352b8az2312341bcda8be3d58ea6959uytb): Error starting userland proxy: mkdir /port/tcp:0.0.0.0:8000:tcp:128.11.0.1:8000: input/output error.

It turns out that you probably have 'Fast Startup Mode' on your Windows 10 which can conflict with Docker. All you have to do is restart Docker. A good explanation of the issue can be found here