pozgo/docker-mkdocs

MkDocs in a Docker. (Alpine)

MkDocs in a docker.

Felling like supporting me in my projects use donate button. Thank You!

Docker Image with MkDocs. It's using tiny image provided by Alpine.
MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

Purpose of this image was to simplify the process of deploying MkDocs. This image is based on Alpine Linux to minimize the size of the image.

ARM based image

Example build:

docker buildx build --platform linux/arm64 --file Dockerfile-arm64v8 -t polinux/mkdocs:arm64v8-1.2.2 .

Docker compose example

version: '3'

services:
  mkdocs:
    container_name: mkdocs
    image: polinux/mkdocs:1.2.2
    restart: always
    ports:
      - "8000:8000"
    environment:
      LIVE_RELOAD_SUPPORT: 'true'
      ADD_MODULES: 'fontawesome-markdown mkdocs-git-revision-date-localized-plugin mkdocs-material'
      FAST_MODE: 'true'
      DOCS_DIRECTORY: '/mkdocs'
      GIT_REPO: '[email protected]:username/docs.git'
      UPDATE_INTERVAL: 15
      AUTO_UPDATE: 'true'
    volumes:
      - $HOME/.ssh/id_rsa:/root/.ssh/id_rsa

Environmental Variables

Variable	Notes	Default
LIVE_RELOAD_SUPPORT	Support for live reload feature.	false
ADD_MODULES	List of module to install.	false
FAST_MODE	Enable fast mode. Rebuilds only changed/added files	false
DOCS_DIRECTORY	Directory in which documentation is mounted inside of container	/mkdocs
GIT_REPO	Repository address. Will require ssh key for ssh connection. Example: -v ${HOME}/.ssh/id_rsa:/root/.ssh/id_rsa	false
GIT_BRANCH	Self explanatory	master
AUTO_UPDATE	Auto update for git repository support	false
UPDATE_INTERVAL	Update interval in minutes - used only when AUTO_UPDATE set to true	every 15 minutes
DEV_ADDR	Custom IP address and port to serve documentation locall	0.0.0.0:8000

Usage

docker run \
    -ti \
    --name mkdocs \
    polinux/mkdocs

Custom config with git repository as source of documentation

docker run \
    -ti \
    --name mkdocs \
    -p 80:9000 \
    -e "ADD_MODULES=mkdocs-bootstrap mkdocs-gitbook mkdocs-bootstrap4" \
    -e "LIVE_RELOAD_SUPPORT=true" \
    -e "FAST_MODE=true" \
    -e "DOCS_DIRECTORY=/my_docs" \
    -e "GIT_REPO=https://my_repos/custom-docs.git" \
    -e "GIT_BRANCH=develop" \
    -e "AUTO_UPDATE=true" \
    -e "UPDATE_INTERVAL=1" \
    -e "DEV_ADDR=0.0.0.0:9000" \
    -v ${HOME}/.ssh/id_rsa:/root/.ssh/id_rsa \
    polinux/mkdocs

See docker-compose.yaml for all compose options examples

Update git repo based deployment

Assuming you are using git repository as source of documentation there are two options available for updating the content of the docs.

Manual

Assuming that container name is mkdocs

docker exec -ti mkdocs bootstrap update
Pulled branch: master
Commit: a4000c525f6db977777bf758987c4df0b44f59b4
Commit Message: Updated nodejs
Date: 2020-03-24 18:52:43
Author: Przemek Ozgo

AUTO_UPDATE

there are two environmental variables that can be used for AUTO UPDATE. See table above ^^

Build

docker build -t polinux/mkdocs .

Docker troubleshooting

Use docker command to see if all required containers are up and running:

docker ps

Check logs of mkdocs server container:

docker logs mkdocs

Sometimes you might just want to review how things are deployed inside a running container, you can do this by executing a bash shell through docker's exec command:

docker exec -ti mkdocs /bin/bash

History of an image and size of layers:

docker history --no-trunc=true polinux/mkdocs | tr -s ' ' | tail -n+2 | awk -F " ago " '{print $2}'

Author

Przemyslaw Ozgo

docker-mkdocs's Issues

Live upload problem when using diferent port

As on mkdocs/mkdocs#1175 (comment) we must use the same port on --ports or live upload stops working.
So if possible add environment like 'default_dev_addr' so we can change the default command on mkdocs/common.py 'os.system(f'mkdocs serve -a 0.0.0.0:8000 {_live_reload()} {_fast_mode()}')'.
For now i'm going to edit the file, thanks.

Question: Modifying mkdocs CLI flags

I am having an issue where the container is quitting without an error before serving the site. I am wanting to enable the --verbose flag for mkdocs, but I can't figure out a way to do that with the current entrypoint / cmd. Is this possible currently, or is this a feature request?

Support latest version of mkdocs?

Is it possible to update the image to the latest version of mkdocs: 1.1?

Thanks a lot.

Adding Cairo support

When e.g. using the mkdocs-material theme, there is image processing recommended, e.g. for their "social" plugin. Details see at https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing and https://squidfunk.github.io/mkdocs-material/plugins/social

This requires 3 more packages to be installed by apk in the docker image:

• cairo
• freetype-dev
• jpeg-dev

Could they be added please?

Auto-Update feature dysfunctionality after updating to 1.5.2

After upgrading from version 1.4.2 to 1.5.2, I encountered an issue when attempting to execute the following command:

docker exec -ti mkdocs bootstrap update

This resulted in the following error:

Traceback (most recent call last): File "/usr/bin/bootstrap", line 5, in <module> from app.cli import cli ModuleNotFoundError: No module named 'app'

Consequently, this error has disrupted the functionality of the auto-update feature. I have tested it with version 1.4.2, and it was working perfectly.

Missing automatic latest tag when releasing new image

Handling git safe directory in some way

Thanks a lot for making version 1.5.2 available, really much appreciated.

Now, I run into a new issue due to the latest git version contained in that docker image, which, of course, is a good thing. The problem is that git introduced the concept of safe directories, i.e. no git command can be executed unless the working directory is declared safe in the global git settings.

Now, in mkdocs there are some nice plugins that use the git logs of the current project to extract the date and author of each page. But they now fail due to the missing configuration on the host, i.e. the docker container. The plugins can't fix this themselves, it needs to be resolved before actually installing such plugins.

As a workaround I cloned this project and tested it by adding the following line into the dockerfile:

git config --global --add safe.directory /mkdocs

right after the apk add --update ... command. That solves the issue, but of course only because my working directory is /mkdocs. I'm aware, this won't work for other working directories. So, that command should ideally be executed as part of the command that executes when the container gets built when we know the working directory of that container.

Is that even possible?

Move to GH Actions

Migrate to python3

error: command 'gcc' failed with exit status 1

ERROR: Command errored out with exit status 1:
     command: /usr/bin/python3.8 -u -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'/tmp/pip-install-t725coun/regex/setup.py'"'"'; __file__='"'"'/tmp/pip-install-t725coun/regex/setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' install --record /tmp/pip-record-rxnjwqs1/install-record.txt --single-version-externally-managed --compile --install-headers /usr/include/python3.8/regex
         cwd: /tmp/pip-install-t725coun/regex/
    Complete output (17 lines):
    running install
    running build
    running build_py
    creating build
    creating build/lib.linux-x86_64-3.8
    creating build/lib.linux-x86_64-3.8/regex
    copying regex_3/__init__.py -> build/lib.linux-x86_64-3.8/regex
    copying regex_3/regex.py -> build/lib.linux-x86_64-3.8/regex
    copying regex_3/_regex_core.py -> build/lib.linux-x86_64-3.8/regex
    copying regex_3/test_regex.py -> build/lib.linux-x86_64-3.8/regex
    running build_ext
    building 'regex._regex' extension
    creating build/temp.linux-x86_64-3.8
    creating build/temp.linux-x86_64-3.8/regex_3
    gcc -Wno-unused-result -Wsign-compare -DNDEBUG -g -fwrapv -O3 -Wall -Os -fomit-frame-pointer -g -Os -fomit-frame-pointer -g -Os -fomit-frame-pointer -g -DTHREAD_STACK_SIZE=0x100000 -fPIC -I/usr/include/python3.8 -c regex_3/_regex.c -o build/temp.linux-x86_64-3.8/regex_3/_regex.o
    unable to execute 'gcc': No such file or directory
    error: command 'gcc' failed with exit status 1
    ----------------------------------------
ERROR: Command errored out with exit status 1: /usr/bin/python3.8 -u -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'/tmp/pip-install-t725coun/regex/setup.py'"'"'; __file__='"'"'/tmp/pip-install-t725coun/regex/setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' install --record /tmp/pip-record-rxnjwqs1/install-record.txt --single-version-externally-managed --compile --install-headers /usr/include/python3.8/regex Check the logs for full command output.

No need for bloated command.py module

Move CI/CD into Jenkins.

CI/CD Should be migrated to Jenkins.

Installing modules doesn't do anything

Add support for installing additional themes

Rename INSTALL_THEMES to ADD_MODULES

This variable is used to install python modules compatible with mkdocs so renaming it to more logical name makes sense

Side Task - Add Discord badge

MkDocs fails to start due to conflict between material for MkDocs and the MkDocs version included in this image

Error is:

pkg_resources.VersionConflict: (mkdocs 1.1.2 (/usr/lib/python3.8/site-packages), Requirement.parse('mkdocs>=1.2.2'))

I've attempted to set the MKDOCS_VERSION env variable to a later version but that doesn't seem to work using docker-compose.

Error in common.py start() function

In the common.py file I think the start() function needs to change directory into the DOCS_DIRECTORY.

Here is what I get in the docker logs when I try to start:

Installing python modules: mkdocs-windmill mkdocs-ivory
Executing [ pip install -q mkdocs-windmill mkdocs-ivory ]:


Process finished with return code 0
Output: 


Modules installed.
Detected previous installation in (/workdir).
Starting MKDocs
LIVE RELOAD - [ ENABLED ]
FAST_MODE - [ ENABLED ]
Executing [ mkdocs serve -a 0.0.0.0:8000  --dirtyreload ]:

INFO    -  Building documentation...

Config file '/mkdocs/mkdocs.yml' does not exist.

Process finished with return code 1
Output: 
INFO    -  Building documentation...

Config file '/mkdocs/mkdocs.yml' does not exist.

As you can see it finds my previous installation but then doesn 't load it.

ARM compatibile?

Is this docker image, compatible with arm architectures, like on a raspberry pi?

live reload problem

Hi, if I add the variable LIVE_RELOAD_SUPPORT='true' the reload feature is disabled.
When I checked the bootstrap.sh I found this :

    if [[ ${LIVE_RELOAD_SUPPORT} == 'true' ]]; then
        LRS='--no-livereload'
    else
        LRS=''
    fi

I think the IF is wrong, if I set the variable in true is because I want the reload support enabled.

If I remove the variable the reload support is enabled.

Best regards.

Please push arm64 images as well as amd64

Currently docker-mkdocs is pushed only as an amd64 image, but that means it gets loaded with the wrong architecture on mac M1 machines.

Could you please use docker buildx build to build and push with both architectures?

Build on Windows Local Fails

Building on Windows with Linux containers fails to execute because the script permissions are broken.
Adding to the dockerfile:
'RUN chmod +x /bootstrap.sh'

Updating to MkDocs 1.5.3

Hello,

Any chance of a new release to include the latest 1.5.3 upstream release?

Happy to attempt to do it and make a PR if that makes life easier.

Updating to MkDocs 1.5.x

Any chance of tagging a new release of this project to include the latest 1.5.x updatream release ?

Bad owner or permissions on /root/.ssh/config

mkdocs    | Bad owner or permissions on /root/.ssh/config
mkdocs    | fatal: Could not read from remote repository.
mkdocs    |
mkdocs    | Please make sure you have the correct access rights
mkdocs    | and the repository exists.
mkdocs    | '

Specifying theme

How do you specify which theme to use?

e.g. where do you put the mkdocs.yml?

Add FAST_MODE for build using --dirty arg

--dirty

Bump to 1.4.2

Failure With Swarm Deployment

The bash script to get IP will fail if you deploy this into a swarm services environment because the IP get shell script returns multiple IP addresses. This line:

mkdocs serve -a $(ip addr show eth0 | grep "inet\b" | awk '{print $2}' | cut -d/ -f1):8000 $LRS

I fixed this by doing the following, which also works fine in the local implementation as well.

mkdocs serve -a 0.0.0.0:8000 $LRS

I don't know if there was a specific reason you needed the specific service IP and and port, so I didn't submit this as a PR.

readme documentation is wrong

1. There is no "INSTALL_THEMES" environmental variable in your code. The correct variable name is ADD_MODULES.
2. The ADD_MODULES value can't have ticks around it. Just list out the modules you want installed.

live reload issues

Just a quick note, thank for the container. I am using it to host a static site for myself.

I was running into issues with the live reload feature. My site was behind a proxy and the live reload js file couldn't be reached. This caused the site load, but hang while the request failed for to the livereload.js, which was horrible.

I recommend turning it off or making a config option to do so, I did the following

start_mkdocs () {
    cd /workdir/mkdocs
    echo "Starting MKDocs"
    mkdocs serve -a $(ip addr show eth0 | grep "inet\b" | awk '{print $2}' | cut -d/ -f1):8000 --no-livereload
}

Thanks

Last tag not pushed

Hi,

Seems your last update was not pushed to dockerhub due to an error in CI.

Regards,

Auto-Reload on git based content - triggered on new commit in repository

Thanks for this docker image - very useful.

I am trying to understand the flow for live reload when cloning a git repo.

I can see the repo is created when the docker command runs, but I don't see it updating the local repo after that. I was thinking that this should trigger a git pull when the remote is updated. Am I missing something?

Steve

Feat: Adding Cairo support #68

To achieve this, you can modify your Dockerfile to include these packages.
Assuming you have a Dockerfile for your project, you can add the necessary package installation commands. For Example:

Use the base image with the desired version
FROM your_base_image:version

Install required packages
RUN apk --no-cache add cairo freetype-dev jpeg-dev

Additional steps for your Dockerfile...
Replace your_base_image:version with the actual base image and version you are using. The apk add command is used to install packages, and --no-cache is used to avoid caching the package index locally, saving space in the Docker image.

Rebuild your Docker image after making these changes:

docker build -t your_image_name:tag .