Snippets: Se créer un répertoire de connaissances

Le monde de la tech est un monde qui change vite, avec beaucoup de technos diverses et variées et en temps que développeur on accumule une quantité certaine de connaissances au fur et à mesure des années. Ces connaissances ne sont pas toujours faciles à retrouver/récupérer et se souvenir de tout est relativement compliqué.

Pour répondre à cette problématique, une des solutions que j’ai trouvée consiste à se créer un répertoire de connaissances, des snippets.

Ce répertoire va nous donner quelques clefs pour réactiver des chemins mentaux pour accéder à des connaissances partiellement ou complètement oubliées, il n’a donc pas pour vocation d’énoncer une vérité absolue mais plutôt de stimuler des connaissances.

Dans cet article, je vais vous présenter un template pour créer des snippets facilement et rapidement, avec une stack Sphinx et Terraform le tout en Static Web Hosting sur un bucket AWS S3 avec une CI Gitlab pour déployer le tout de manière continue.

Aperçu de snippets comportant une barre de recherche et un menu de recherche à plusieurs niveaux.

Voici une apparence possible de vos snippets (par défaut), vous pourrez trouver d’autres apparences ici. Vous pourrez le changer en modifiant la variable ‘html_theme’ dans le fichier source/conf.py

Pré-requis

Pour la mise en place de ces snippets il va falloir un compte AWS et un utilisateur IAM avec une stratégie/policy AmazonS3FullAccess.

Pour ce faire, vous pouvez créer un compte gratuit AWS et créer l’utilisateur.

Après avoir fait ces deux étapes vous devriez avoir des credentials AWS_ACCESS_KEY_ID et AWS_SECRET_ACCESS_KEY, gardez les précieusement et ne les communiquez surtout pas.

Il faudra posséder un compte Gitlab.

Pour la partie Terraform, il suffit de récupérer le package qui convient à votre OS sur le site de Terraform et de le placer le bin dans le /usr/local/bin avec :

$ sudo mv terraform /usr/local/bin

Vous devez aussi disposer de python dans une version supérieure à 3.6 et de pip ( installation ici )

Mise en place

Pour commencer il vous faudra le projet template que vous pourrez directement forker ici puis clonez-le.

Pour ce projet vous pouvez créer un environnement virtuel python afin de garder votre poste de travail propre et éviter les potentiels conflits entre dépendances. Pour ce faire, à la racine du projet lancez:

$ sudo apt-get install python3-venv 
$ python3 -m venv snippets_venv 
$ source snippets_venv/bin/source 
$ which python #vérifier que python pointe vers le bon environnement

Vous pourrez ajouter le dossier /snippets_venv/ dans le .gitignore

Vous pouvez maintenant installer le projet en lançant dans votre venv:

$ pip install .

puis

$ python setup.py install

et enfin

$ make html

Un dossier build a été généré contenant un dossier html, vous pouvez directement accéder à vos snippets en local en ouvrant le fichier buid/html/index.html

Il va falloir changer quelques variables pour vous approprier ce template et en faire un répertoire de connaissances à vous.

Premièrement il va falloir remplacer le placeholder <MY_BUCKET_NAME> par le nom de votre bucket s3 (uniquement des lettres minuscules et des tirets) dans les fichiers: terraform/aws/terraform.tfvars (qui sont les variables que terraform va utiliser), terraform/aws/s3_policy.json (qui représente la stratégie IAM que nous allons associer à notre bucket s3 et qui va permettre à ce dernier d’être accessible depuis l’extérieur) et bin/web_publish.py (qui est le script python que nous allons utiliser dans l’intégration continue et qui va permettre d’uploader les sources html dans notre bucket s3).

Vous pouvez aussi changer le copyright et l’auteur dans le fichier source/conf.py car rappelons-le, ce sont vos snippets!

Maintenant vous pouvez exporter les credentials AWS en utilisant les credentials générés dans les pré-requis:

$ export AWS_ACCESS_KEY_ID=<INSERT_YOUR_AWS_ACCESS_KEY_ID>
$ export AWS_SECRET_ACCESS_KEY=<INSERT_YOUR_AWS_SECRET_ACCESS_KEY>
$ export AWS_DEFAULT_REGION=eu-west-1
$ export AWS_DEFAULT_OUTPUT=json

ou via la commande:

$ aws configure

Vous allez à présent pouvoir, après avoir changé de répertoire vers le répertoire /terraform/aws , initialiser terraform avec la commande:

$ terraform init

puis lancer:

$ terraform apply

Vous avez maintenant un site statique hébergé sur un bucket s3 d’AWS, vous pouvez récupérer l’url du site en allant dans la console AWS, service s3.

Nous allons à présent tester notre script de publication: web_publish.py

Pour cela nous allons lancer la commande:

$ ./bin/web_publish.py

Ce script va installer les dépendances avec le gestionnaire de dépendances pyhton pip, faire un make html pour générer l’html et un aws s3 sync pour uploader l’html sur notre bucket s3.

Intégration continue

A présent, nous allons faire en sorte qu’à chaque push sur le repository Gitlab, GitlabCI ajoute le nouveau contenu dans notre bucket s3. Pour cela, il faut ajouter les variables d’environnement AWS dans Gitlab.

Pour cela, rendez-vous sur votre repository Gitlab dans settings > CI/CD > Variables et ajoutez (et complétez avec les credentials AWS générés précédemment) deux variables AWS_ACCESS_KEY_ID et AWS_SECRET_ACCESS_KEY en protected et masked.

Vous pouvez à présent tester l’intégration continue en utilisant le script autocommit:

$ ./bin/autocommit

A vous de continuer

Maintenant c’est à vous de jouer, vous avez une base pour pouvoir gérer vos snippets comme vous le désirez. Le travail se fera au fil de l’eau et prendra du temps mais au final vous gagnerez à tenir à jour ce répertoire.