Running mkdocs-materials with portainer and git repository content

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