Skip to content

Setup on Ubuntu (WSL)

First of all I need to mention that I’m working on a Windows machine… Which sometimes can be very frustrating…

Even if this documentation page is hosted online on gitlab, it is easier to use a local copy of the project to modify the website. To be able to use the local copy and generate the website we also need to install a few things locally.

It is possible to deal with package using the windows terminal with a piece of software named chocolatey. Chocolatey is a powerful package manager. However, I already installed mkdocs a few month ago. To my mind, chocolatey don’t help this much. I want you to know about a more practical solution, creating a hybrid windows-linux os. You may have heard about installing a dualboot to have both linux and windows on the same machine. But want about using them together at the same time on a single machine ?

I decided to install linux WSL. WSL (for windows sub-system linux) is a linux system running into windows, both os can share files, hardware… Of course, you’ll have linux as a terminal (I’m not sure if you can have graphical ubuntu this way), but this is convenient for documentation.

Why WSL The WSL is a convenient way to take advantage of Linux without setupping a dual boot on your local machine. The WSL is a Windows10 features allowing you to run simultaneously with shared ressources and data (This is not a VM) Using WSL with Visual studio code is a pretty convenient way to maximize your productivity if you need both Linux and Windows.

The project template supplied by fabacademy is based on mkdocs. Mkdocs is basically the website generator, it is based on python which is both a programming language and a software translating code to computer operation in realtime (It’s called an interpreted language). We will start by installing WSL, then we’ll install python & mkdocs into wsl.

Pre-requisite

Ubuntu installation

To get Ubuntu and Windows working together follow these steps :

  1. In windows startmenu type “feature” to launch the windows feature manager
  2. Select the Windows subsystem linux & click apply (You may need admin sessions)
  3. Open Microsoft store and install Ubuntu (Restart may be required)
  4. Start Ubuntu and create your login and password

Info

Alternatively you can type this command in powershell 

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
Ignore 1 & 2 if you use this method. More help

Python installation

MkDocs requires a recent version of Python and the Python package manager: pip, to be installed on your system.

Once Ubuntu is installed on your Windows machine,

You can check if you already have python installed from these command line:

$ python --version
Python 3.8.2
$ pip --version
pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8)
If you already have those packages installed, you may skip down to Installing MkDocs.

If Python isn’t installed Start Ubuntu and do the following :

Info

You can start the linux subsystem in any terminal using : > wsl

  1. Udpate package list using : 
    sudo apt-get update -y && sudo apt-get upgrade -y
  2. Install Python using : 
    sudo apt-get install python3.8

Website setup

Cloning project

To install Git simply type : 

sudo apt-get install git

Using SSH authentification

When working on documentation I must login to gitlab very often (each time I want to bring my changes online). It is possible to use git only using standard passwors / login methods… or you can use SSH !

Ssh-key security is a very good way to authentify everywhere. ssh-key are based on asymetric cryptography protocol. Which mean that when you generate a key, the program gives you a public key which can be shared with every one, and a private one which shouldn’t. When a website want to check you’re identity it can send a bunch of data encrypted using your public key, then to decrypt the data, the private key is needed, in theory only you’re computer should be able to decrypt the data and autentify.

Open a terminal and type : 

ssh-keygen
this will generate your own key. It is recommended to use a passphrase to increase the complexity of the key (but it is not mandatory). on Windows you can access to your public key at thuis path :

%userprofile%/.ssh/id_rsa.pub

Copy the whole content on this file and add it to your gitlab account. Go to your settings > SSH key and paste the content of the key.

Then you should be able to git clone, git commit, git push without typing your password ! Seems obvious but don’t share your private key to anyone !

Clonning a repository

To clone my repo, I used this command : 

$ git clone git@gitlab.fabcloud.org:academany/fabacademy/2021/labs/lamachinerie/students/jules-topart.git

Cloning into 'jules-topart'...
remote: Enumerating objects: 150, done.
remote: Counting objects: 100% (150/150), done.
remote: Compressing objects: 100% (113/113), done.
remote: Total 1044 (delta 65), reused 96 (delta 35), pack-reused 894
Receiving objects: 100% (1044/1044), 40.77 MiB | 4.46 MiB/s, done.
Resolving deltas: 100% (456/456), done.

This will create a floder contaning all your documentation site. Browse wisely before running the command.

Info

The git clone command can be use trough ssh or https depending on the URL you use. I cloned over SSH howerver the port 22 in sometimes blocked in university. You can use https as well but your password will be asked… (You can use port 443 instead or port 22 using the alternative ssh port of Gitlab)

When you’ve clonned the repo, use mkdocs serve to start the local server. your site should be accessible on 127.0.0.1:8000

Error

If the command didn’t worked for you, try this : 

python -m mkdocs serve

If this one does the job, pip installed mkdocs in a folder which isn’t in your path. Consider adding %appdata%/Python/Python39/Scripts to your path. The previous command should work.

When your docs is updated and you’re ready to post, use git add --all to add your changes to the next commit, then use git commit -m "Your commit message"

Note : I personnaly use the commit convention from here to name my commits.

When you’re ready to send your changes (and absolutely sure of what your doing) Type git push to send everything to your gitlab page. The page should build and after a few moment be updated !

Install all the required package using : 

pip install -r requirements.txt

Help

This should be run from inside your repository… This will install mkdocs and any other package required. Most of the time pip is installed with python but you can install it using sudo apt install python3-pip

Running the website

To start the local webserver run this command from the project root: 

mkdocs serve

Sources

Last update: March 16, 2022