Running mkdocs-materials with docker/portainer

[ndeschamps-isto]

Hi all,

I want to create an MkDocs site for my team to write and access documentation. It’s supposed to be simple, but I’ve spent hours on it and just lost track. I would really appreciate some help!

I’ve been using Linux/Docker for a few months, but I’m still a beginner.

My plan is to use Material for MkDocs to create my website and host it in a Docker container. I already have a VM (Debian) with Docker and Portainer, along with a few apps running. I also have a domain name and Traefik as a proxy. I want the website content to be easily editable via GitLab CNRS from our institute.

Ideally, I want to run MkDocs in my Docker container with the Portainer interface and access it on the internet under my domain name.

My idea was to bind the Docker volume to my host machine, and then have a .sh routine to update the content from the repository. Is this a good solution?

For now, I’ve created a basic MkDocs structure (/home/ndeschamps/apps/mkdocs) with mkdocs.yml and docs/index.md. I also wrote the following Docker Compose file for my stack in Portainer:

services:
  mkdocs:
    image: squidfunk/mkdocs-material
    container_name: mkdocs_container_test
    labels:
      - traefik.enable=true
      - traefik.docker.network=frontend
      - traefik.http.routers.wiki-secure.entrypoints=websecure
      - traefik.http.routers.wiki-secure.rule=Host(docs.${_DOMAIN_NAME})
    networks:
      - frontend
      - backend
    volumes:
      - /home/ndeschamps/apps/mkdocs:/mkdocs
    restart: always

volumes:
  data:
    external:
      name: /home/ndeschamps/apps/mkdocs

networks:
  frontend:
    external: true
  backend:
    external: true

My container is running, but it cannot find my mkdocs.yml. I’m also not sure if it will be easy to update the volume content from the repository afterward...

Is there a better solution?

Can someone guide me?

I’ve spent a day searching for solutions but haven’t a solution.

thank you!

[niclasheinz]

Hello again @ndeschamps-isto

My idea was to bind the Docker volume to my host machine, and then have a .sh routine to update the content from the repository. Is this a good solution?

I recommend working with GitLab CI/CD if you have a GitLab runner. Although I'm not very familiar with Portainer and Traefik, I would suggest using a simple Nginx server. This Nginx server can retrieve the data from the folder where the MkDocs material repository is located. You can use the Nginx Server to get a Let's Encrypt Cert for your domain.

As you do, you could mount a specific folder in the container. You could automatically update this folder (not the folder inside the docker image) using CI/CD in GitLab after each commit on the default branch. However, this procedure is only possible if you have a GitLab Runner available. Alternatively, you could also write a bash script as you have already mentioned, to automate the updating process for your site.

If you're interested in this way, let me now.

services:
mkdocs:
image: squidfunk/mkdocs-material
container_name: mkdocs_container_test

I think the docker image of mkdocs-material is only limited to building the documentation and not publishing/hosting it.

To build my own documentation site I have a docker image which has all the dependencies in it. Afterwards I use the following command to build my mkdocs-material documentation into the folder public.

 docker run --rm -v $CI_PROJECT_DIR:/docs -e MKDOCS_GIT_COMMITTERS_APIKEY=${MKDOCS_GIT_COMMITTERS_APIKEY} -w /docs $CONTAINER_RELEASE_IMAGE bash -c "mkdocs build --clean -d public"

[ndeschamps-isto]

Hi again, and thanks again for your reply.
I couldn't reply to your post on the GitLab forum, as my topic and account have been locked...

I tried to build an MkDocs page with GitLab.com and it worked smoothly. The issue is that our self-hosted GitLab doesn’t provide runners... I tried to create one, but I failed.

I'm not familiar with CI/CD and runners, so I should probably learn a bit about them before trying to use them! I'm also not very familiar with Nginx servers, but it seems appropriate for my use case and better than a "manual" Bash script.

Which Docker image are you using?

I will try those solutions in the next days and let you know.

[niclasheinz]

Hi @ndeschamps-isto

I am using the official docker image of mkdocs-material for the build process and a nginx container which provides the mkdocs-material documentation. On the host itself I have set up a reverse proxy using nginx, which forwards the traffic from localhost:443 to localhost:8080.

To make it as clear as possible, I have created a repository that explains this again and provides you with all the necessary files.

Please note that you have to change some paths (like to the SSL certificates or your domain).

You can of course also use traffik as a reverse proxy instead of nginx if you are already using it. Unfortunately I can't help with the configuration of Traffik 😄

[ndeschamps-isto]

Hi, thank you for sharing your solution and your repository.
I think I will start with the easiest approach: creating a GitLab page on gitlab.com using my own runner. I will see later if it makes sense to host it on my server. The most important thing right now is to write the documentation itself!
It was an interesting and valuable experience exploring those options. Thanks again for your help!
Greetings.

[niclasheinz]

There is one more thing I would like to point out. You must ensure that no sensitive data is included in the documentation. Universities have a high level of data protection and usually require the data to be stored on a server where the university is located