Skip to content

Selfhosting mkdocs (mkdocs-material) on a vps under the wiki subdomain

the quick and dirty guide

Prerequisites:

  • You should have your own VPS with NGINX installed (if you followed landchad.net's guide you should be pretty good to go!)
  • Debian but it should be the same for different distros

1. Create a subdomain for your wiki (e.g. wiki)

  1. Go to your DNS provider
  2. Manage DNS records
  3. Create an A record that points to your server's IPv4:
  4. Create a AAAA recordthat points to your server's IPv6:

2. Setting up your mkdocs (or mkdocs-material) website

I'm not entirely sure if it's needed but create 2 files named CNAME (no extension, just CNAME) and place one in the root directory (outside of /docs) and one in /docs. Enter the URL of your website - in my case that will be wiki.vodoraslo.club and save it. Just one line, don't add additional spaces. Both of the files must point to the same URL so copy paste it!

On creating content:

  • All markdown files should be under the /docs folder
  • Create an /img folder for images, gifs and videos

Seeing how your website looks in real time is done with the following command - mkdocs serve. Use it in the root directory

Building your website (generating HTML files from markdown) is done with the following command - mkdocs build. The result should be a new folder called /site

3. Setting NGINX up

  1. Log in your VPS through SSH
  2. Create the following file in /etc/nginx/sites-available:
    • nano /etc/nginx/sites-available/wikimkdocs
  3. Create a folder where your /site files will reside in - mkdir /var/www/wikimkdocs
  4. Paste this in and change example.org to wiki.YOURDOMAIN.COM, also check if root /var/www/mysite corresponds to the folder you made in 3.: 
    server {
        listen 80 ;
        listen [::]:80 ;
        server_name example.org ;
        root /var/www/mysite ;
        index index.html index.htm index.nginx-debian.html ;
        location / {
                try_files $uri $uri/ =404 ;
        }
}
  5. ln -s /etc/nginx/sites-available/wikimkdocs /etc/nginx/sites-enabled
  6. systemctl reload nginx. It should reload with no issues
  7. certbot --nginx and either select only the wiki domain or do all domains
  8. Now you have to get /site into /var/www/wikimkdocs.

4. Getting content into /var/www/wikimkdocs

I did this by setting up a git repository for my wiki, then git pulling to get the differences. I DO NOT COMMIT FROM THE VPS!

Then I just use rsync:

rm -rf /var/www/wikimkdocs/*
rsync --info=progress2 --stats -ai site/* /var/www/wikimkdocs/

WARNING

Do bear in mind that I'm in the git repository directory before executing this command!

The first command will remove everything in that directory, then rsync will populate it with the newest stuff.

Then do another systemctl reload nginx just to be sure

If you followed this guide, you should have a wiki subdomain for your wiki, SSL and whatever content you made on it! :)

Last update: September 23, 2023