Source code of my website
🎉 : import jekyll content
+2345
+5
archetypes/default.md
+5
archetypes/default.md
+47
content/posts/2020-06-01-global-gitignore-file.md
+47
content/posts/2020-06-01-global-gitignore-file.md
···
1
+
---
2
+
created: "2020-04-16"
3
+
date: "2020-06-01T00:00:00Z"
4
+
language: en
5
+
modified: "2022-06-17"
6
+
tags:
7
+
- DevOps
8
+
- Git
9
+
title: "Configure a Global Gitignore \U0001F648"
10
+
slug: global-gitignore-file
11
+
---
12
+
13
+
This short articles shows how to setup a global `.gitignore` file, to exclude files or directories for all your git repositories.
14
+
15
+
This is very useful for editor files or `.env` file, and prevents accidental commits.
16
+
I also added common directories for Java and NodeJS related developments (`target/` and `node_modules`), and IntelliJ IDEA files (`*.iml` and `.idea/`)
17
+
18
+
Thus said, you should also always setup a `.gitignore` file in your projets, as the global file only work for you, and will not be shared with the code of your project.
19
+
20
+
## create the .gitignore file
21
+
22
+
On Linux systems, the default location for a global `.gitignore` file is `~/.config/git/ignore`.
23
+
24
+
Create this file if it doesn't exist, and put your content in it:
25
+
26
+
```shell
27
+
# create the directory if it doesn't exists
28
+
$ mkdir -p ~/.config/git
29
+
30
+
# create the global ignore file
31
+
$ cat <<EXCL >> ~/.config/git/ignore
32
+
# global gitignore file
33
+
34
+
# idea settings
35
+
.idea/
36
+
*.iml
37
+
38
+
# java
39
+
target/
40
+
41
+
# direnv
42
+
.envrc
43
+
.env
44
+
EXCL
45
+
```
46
+
47
+
And you are done!
+78
content/posts/2020-07-15-schedule-linux-commands.md
+78
content/posts/2020-07-15-schedule-linux-commands.md
···
1
+
---
2
+
created: "2020-07-15"
3
+
date: "2020-07-15T00:00:00Z"
4
+
language: en
5
+
modified: "2022-06-17"
6
+
tags:
7
+
- DevOps
8
+
title: Schedule a linux command to run later with `at`
9
+
slug: schedule-linux-commands
10
+
---
11
+
12
+
As I prepare and run a lot of scripts, sometimes I need to run a script at a precise time of the day.
13
+
14
+
When a script must be only run once, `cron` is not a viable solution.
15
+
So I discovered the `at` scheduler
16
+
17
+
You need to install it first, using `apt` as usual.
18
+
19
+
```shell
20
+
$ sudo apt install at
21
+
```
22
+
23
+
## Schedule a command to run
24
+
25
+
1. use the command `at` with a time / date
26
+
2. input the commands to run in the prompt
27
+
3. type CTRL+D to exit (^D)
28
+
29
+
```shell
30
+
$ at 9AM
31
+
warning: commands will be executed using /bin/sh
32
+
at> cd workspaces/github/dotfiles
33
+
at> git pull
34
+
at> <EOT>
35
+
job 1 at Sat Apr 16 09:00:00 2022
36
+
```
37
+
38
+
This example will pull a repository contents at 9 AM tomorrow !
39
+
40
+
`at` supports a lot of time specifications.
41
+
42
+
Here is an extract of its man page:
43
+
44
+
> At allows fairly complex time specifications, extending the POSIX.2 standard. It accepts times of the form
45
+
> HH:MM to run a job at a specific time of day. (If that time is already past, the next day is assumed.) You
46
+
> may also specify midnight, noon, or teatime (4pm) and you can have a time-of-day suffixed with AM or PM for
47
+
> running in the morning or the evening.
48
+
49
+
The commands are executed with the logged-in user account, using a `/bin/sh` shell.
50
+
It will use the available env-vars of the shell when the command `at` is executed, and will `cd` into the current directory before running your scruipt.
51
+
52
+
## view scheduled commands
53
+
54
+
```shell
55
+
$ atq
56
+
1 Sat Apr 16 09:00:00 2022 a jwittouck
57
+
```
58
+
59
+
## view the details of a job
60
+
61
+
```shell
62
+
$ at -c 1
63
+
64
+
65
+
cd /home/jwittouck || {
66
+
echo 'Execution directory inaccessible' >&2
67
+
exit 1
68
+
}
69
+
cd workspaces/github/dotfiles
70
+
git pull
71
+
72
+
```
73
+
74
+
## delete a job
75
+
76
+
```shell
77
+
$ atrm 1
78
+
```
+76
content/posts/2021-02-06-xdotool-cheatsheet.md
+76
content/posts/2021-02-06-xdotool-cheatsheet.md
···
1
+
---
2
+
created: "2021-02-06"
3
+
date: "2021-02-06T00:00:00Z"
4
+
language: en
5
+
modified: "2022-04-15"
6
+
tags:
7
+
- Tools
8
+
title: xdotool cheatsheet
9
+
slug: xdotool-cheatsheet
10
+
---
11
+
12
+
I played a lot these days with xdotool, to try to automate some stuff for my Elgato Streamdeck.
13
+
14
+
These are the things I try to do:
15
+
16
+
* Select a window, and send a Keyboard sequence (such as CTRL+B to mute/unmute a Teams call)
17
+
* Type emojis to the active window 😅
18
+
* More a window around, or resize it
19
+
20
+
Here are some links that I found about `xdotool`:
21
+
22
+
* [Xdotool - Window Stack](https://www.linux.org/threads/xdotool-%E2%80%93-window-stack.10687/)
23
+
* [Xdotool - Examples](https://www.linux.org/threads/xdotool-examples.10705/#post-36275)
24
+
25
+
26
+
Below are the commands I found useful during my research.
27
+
28
+
## get window classes
29
+
30
+
```
31
+
xprop | grep 'CLASS'
32
+
```
33
+
34
+
Click on the window you want to analyse after that.
35
+
36
+
More details about classes on this thread: [xdotool: what are "class" and "classname" for a window?](https://askubuntu.com/questions/1060170/xdotool-what-are-class-and-classname-for-a-window)
37
+
38
+
## find active window
39
+
40
+
```
41
+
xdotool getactivewindow
42
+
```
43
+
44
+
## find a window by class
45
+
46
+
```
47
+
xdotool search --onlyvisible --limit 1 --class "Firefox"
48
+
```
49
+
50
+
## focus a window
51
+
52
+
```
53
+
xdotool windowactivate 123456
54
+
```
55
+
56
+
## send a key
57
+
58
+
```
59
+
xdotool search --onlyvisible --limit 1 --class "Firefox" key ctrl+t
60
+
```
61
+
62
+
## send a key to firefox (by changing active window and come back)
63
+
64
+
```
65
+
ACTIVE_WINDOW=$(xdotool getactivewindow)
66
+
FIREFOX_WINDOW=$(xdotool search --onlyvisible --limit 1 --class "Firefox")
67
+
xdotool windowactivate $FIREFOX_WINDOW
68
+
xdotool key ctrl+s
69
+
xdotool windowactivate $ACTIVE_WINDOW
70
+
```
71
+
72
+
## change a window size
73
+
74
+
```
75
+
xdotool search --onlyvisible --limit 1 --class "Firefox" windowsize 800 600
76
+
```
+101
content/posts/2021-03-26-rewrite-git-history.md
+101
content/posts/2021-03-26-rewrite-git-history.md
···
1
+
---
2
+
created: "2021-03-26"
3
+
date: "2021-03-26T00:00:00Z"
4
+
language: fr
5
+
modified: "2022-04-22"
6
+
tags:
7
+
- DevOps
8
+
- Git
9
+
title: Réécrire une branche git
10
+
slug: rewrite-git-history
11
+
---
12
+
13
+
Je suis tombé sur un cas où un fichier a été ajouté dans git (commité), puis modifié par plusieurs commits successifs.
14
+
15
+
Malheureusement, ce fichier contient des credentials.
16
+
17
+
On va donc devoir supprimer ce fichier de tout l'historique git (oui ça implique une réécriture de la sainte branche `main` 😇).
18
+
19
+
## Trouver dans quel commit le fichier a été ajouté
20
+
21
+
Le fichier que je recherche s'appelle `config.json`.
22
+
23
+
Je vais faire un git log, pour trouver le commit qui a ajouté ce fichier.
24
+
25
+
On peut passer à la commande `git log` le nom du fichier à filtrer, ce qui nous permet d'avoir l'historique précis de ce fichier parmi tous les commits:
26
+
27
+
```shell
28
+
$ git log
29
+
d33736456c70ac9859da1e1f899c964db6f98cff (HEAD -> main, origin/main) 🔧 : update configuration
30
+
31157b8ce772c4b058d042fffef331dca87dadf5 ✨ : render button on http request
31
+
92587cbadee1063b9a9692cee014e362d99c1452 ✨ : add switch to page
32
+
de63402ee023daedb4f18cc916344ac170dcfdfd ♻ : use xdotool to write text instead of robotgo
33
+
15df7fd6e19c392dd29529b1b3b46c40961710bd ⚗️ : experiment with config loading
34
+
7f5f2abdfd67c588bb9c52b8c9c8dd4a6468a833 🙈 : add binary to .gitignore
35
+
dad0c5ec3d4b7334986b6aca4c483b1351cfa56a 📝 : add dependencies & build instructions
36
+
605e850fa4dffb49a14937400166c76b07ba817c 🙈 : add .gitignore
37
+
9a9e99a3bfd43b891bef3e2b16661d7b56dcf844 📝 : add README.md
38
+
39
+
```
40
+
41
+
```shell
42
+
$ git log config.json
43
+
d33736456c70ac9859da1e1f899c964db6f98cff (HEAD -> main) 🔧 : update configuration
44
+
15df7fd6e19c392dd29529b1b3b46c40961710bd ⚗️ : experiment with config loading
45
+
```
46
+
47
+
Ça filtre sur mon fichier, cool !
48
+
49
+
L'option `--diff-filter` permet de filtrer le log sur certaines opérations, pour l'ajout (`A`), modification (`M`) ou suppression (`D`) par exemple (voir la [doc](https://git-scm.com/docs/git-log#Documentation/git-log.txt---diff-filterACDMRTUXB82308203))
50
+
51
+
```shell
52
+
$ git log --diff-filter=A config.json
53
+
15df7fd6e19c392dd29529b1b3b46c40961710bd ⚗️ : experiment with config loading
54
+
```
55
+
56
+
C'est mon commit `15df7f` qui a créé le fichier !
57
+
58
+
## Remonter le temps
59
+
60
+
Maintenant que nous avons l'hisorique de notre fichier, l'idée est remonter le temps, et de réécrire l'ensemble des commits qui ont touché à ce fichier.
61
+
62
+
C'est une opération destructrice, qui va mettre à jour probablement pas mal de commits (seulement 2 dans notre exemple), donc à manipuler avec précaution.
63
+
64
+
Pour ré-écrire des branches git, on utilise la commande `git filter-branch` (voir la [doc](https://git-scm.com/docs/git-filter-branch)).
65
+
66
+
`git filter-branch` permet de ré-écrire de contenus ou des messages de commit.
67
+
68
+
`git filter-branch` prend en paramètre un nom de branche, ou un ensemble de révisions pour lister les commits à parcourir, voici quelques exemples:
69
+
70
+
* `HEAD` référence la branche courante (toute la branche sera parcourue)
71
+
* `main` permet de jouer le filtre sur la branche main.
72
+
* `HEAD~10..HEAD` permet de jouer le filtre sur les 10 derniers commits
73
+
74
+
Une option m'intéresse pour mon cas: `--tree-filter`.
75
+
Cette option permet de jouer une commande pour chaque commit de la branche, et re-commiter le résultat automatiquement, pratique !
76
+
77
+
Voici donc une commande qui permet de supprimer un fichier sur l'ensemble des commits de la branche courante:
78
+
```
79
+
$ git filter-branch --tree-filter 'rm -f config.json' HEAD
80
+
```
81
+
82
+
il est aussi possible de jouer sur toutes les branches avec l'option `--all`
83
+
84
+
```
85
+
$ git filter-branch --tree-filter 'rm -f config.json' -- --all
86
+
```
87
+
88
+
L'exécution prend un peu de temps, et affiche les commits modifiés :
89
+
90
+
```
91
+
Rewrite 15df7fd6e19c392dd29529b1b3b46c40961710bd (9/13) (0 seconds passed, remaining 0 predicted) rm 'config.json'
92
+
Rewrite de63402ee023daedb4f18cc916344ac170dcfdfd (10/13) (0 seconds passed, remaining 0 predicted) rm 'config.json'
93
+
Rewrite 92587cbadee1063b9a9692cee014e362d99c1452 (11/13) (0 seconds passed, remaining 0 predicted) rm 'config.json'
94
+
Rewrite 31157b8ce772c4b058d042fffef331dca87dadf5 (12/13) (0 seconds passed, remaining 0 predicted) rm 'config.json'
95
+
Rewrite d33736456c70ac9859da1e1f899c964db6f98cff (13/13) (0 seconds passed, remaining 0 predicted) rm 'config.json'
96
+
97
+
Ref 'refs/heads/main' was rewritten
98
+
Ref 'refs/remotes/origin/main' was rewritten
99
+
```
100
+
101
+
On a plus qu'a force push tout ça maintenant 💪
+274
content/posts/2021-04-06-implementation-cli-elgato-keylight.md
+274
content/posts/2021-04-06-implementation-cli-elgato-keylight.md
···
1
+
---
2
+
created: "2021-04-06"
3
+
date: "2021-04-06T00:00:00Z"
4
+
language: fr
5
+
modified: "2022-04-15"
6
+
tags:
7
+
- Go
8
+
title: Implémentation d'un CLI pour la Elgato KeyLight
9
+
slug: implementation-cli-elgato-keylight
10
+
---
11
+
12
+
## Adresse IP/URL du KeyLight
13
+
14
+
La KeyLight se connecte à votre réseau WiFi.
15
+
La première étape consiste à récupérer son adresse IP.
16
+
17
+
La keylight répond aux requêtes mDNS (multicast dns).
18
+
19
+
C'est d'ailleurs indiqué dans leur documentation:
20
+
21
+
* [What Communication Protocol Is Used by Elgato Wi-Fi Products?](https://help.elgato.com/hc/en-us/articles/360060048331-What-Communication-Protocol-Is-Used-by-Elgato-Wi-Fi-Products)
22
+
* [mDNS Service Strings for Elgato Devices](https://help.elgato.com/hc/en-us/articles/4413403384845-mDNS-Service-Strings-for-Elgato-Devices)
23
+
24
+
Pour obtenir l'IP du keylight, il suffit donc d'emettre une requête DNS:
25
+
26
+
```shell
27
+
dig -p 5353 PTR _elg._tcp.local @224.0.0.251
28
+
29
+
; <<>> DiG 9.16.15-Ubuntu <<>> -p 5353 PTR _elg._tcp.local @224.0.0.251
30
+
;; global options: +cmd
31
+
;; Got answer:
32
+
;; WARNING: .local is reserved for Multicast DNS
33
+
;; You are currently testing what happens when an mDNS query is leaked to DNS
34
+
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 18533
35
+
;; flags: qr aa; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 4
36
+
37
+
;; QUESTION SECTION:
38
+
;_elg._tcp.local. IN PTR
39
+
40
+
;; ANSWER SECTION:
41
+
_elg._tcp.local. 10 IN PTR Elgato\032Key\032Light\032Air\032F3DF._elg._tcp.local.
42
+
43
+
;; ADDITIONAL SECTION:
44
+
Elgato\032Key\032Light\032Air\032F3DF._elg._tcp.local. 10 IN SRV 0 0 9123 elgato-key-light-air-f3df.local.
45
+
Elgato\032Key\032Light\032Air\032F3DF._elg._tcp.local. 10 IN TXT "mf=Elgato" "dt=200" "id=3C:6A:9D:16:12:45" "md=Elgato Key Light Air 20LAB9901" "pv=1.0"
46
+
elgato-key-light-air-f3df.local. 10 IN A 192.168.1.11
47
+
elgato-key-light-air-f3df.local. 10 IN AAAA fe80::3e6a:9dff:fe16:1245
48
+
49
+
;; Query time: 120 msec
50
+
;; SERVER: 192.168.1.11#5353(224.0.0.251)
51
+
;; WHEN: Fri Apr 15 13:55:25 CEST 2022
52
+
;; MSG SIZE rcvd: 254
53
+
```
54
+
55
+
On obtient l'URL d'accès au Keylight `Elgato\032Key\032Light\032Air\032F3DF._elg._tcp.local.`, son IP `192.168.1.11` ainsi que son port d'écoute `9123`
56
+
57
+
## Découverte de l'API
58
+
59
+
La deuxième étape est de comprendre comment fonctionne l'API du KeyLight.
60
+
61
+
Elle très simple.
62
+
63
+
Un `GET /elgato/lights` permet de récupérer l'état de la KeyLight:
64
+
65
+
```
66
+
GET /elgato/lights
67
+
68
+
{
69
+
"numberOfLights": 1,
70
+
"lights": [
71
+
{
72
+
"on": 1,
73
+
"brightness": 100,
74
+
"temperature": 167
75
+
}
76
+
]
77
+
}
78
+
```
79
+
80
+
Nous avons donc 3 champs intéressants :
81
+
* `on` indique si la KeyLight est allumée (1) ou éteinte (0)
82
+
* `brightness` indique la puissance de la luminausité (de 0 à 100)
83
+
* `temperature` indique la température de la lumière (valeurs de 143 à 344) pour une couleur entre 2900 et 7000 kelvin
84
+
85
+
Une requête `PUT` permet de mettre à jour la KeyLight.
86
+
87
+
### Extinction de la KeyLight
88
+
89
+
```
90
+
PUT /elgato/lights
91
+
92
+
{
93
+
"lights": [
94
+
{
95
+
"on": 0
96
+
}
97
+
]
98
+
}
99
+
```
100
+
101
+
### Alumage de la KeyLight
102
+
103
+
```
104
+
PUT /elgato/lights
105
+
106
+
{
107
+
"lights": [
108
+
{
109
+
"on": 1
110
+
}
111
+
]
112
+
}
113
+
```
114
+
115
+
### Modification de la luminosité
116
+
117
+
```
118
+
PUT /elgato/lights
119
+
120
+
{
121
+
"lights": [
122
+
{
123
+
"brightness": 20
124
+
}
125
+
]
126
+
}
127
+
```
128
+
129
+
### Modification de la temperature
130
+
131
+
```
132
+
PUT /elgato/lights
133
+
134
+
{
135
+
"lights": [
136
+
{
137
+
"temperature": 200
138
+
}
139
+
]
140
+
}
141
+
```
142
+
143
+
## Développement d'un CLI en Kotlin
144
+
145
+
J'ai choisi pour m'amuser de développer un CLI en Kotlin, avec compilation native.
146
+
147
+
Ce n'est probablement pas le setup le plus pratique, mais cela permet de mettre en place la compilation native avec GraalVM.
148
+
149
+
Le CLI devra supporter les commandes suivantes :
150
+
151
+
```shell
152
+
keylight on
153
+
keylight off
154
+
keylight brightness <X>
155
+
keylight color <Y>
156
+
```
157
+
158
+
### Installation de GraalVM
159
+
160
+
L'installation de GraalVM est plutôt simple (comme un JDK habituel).
161
+
162
+
J'ai téléchargé le `.tar.gz` sur Github ici : https://github.com/graalvm/graalvm-ce-builds/releases/tag/vm-21.0.0.2
163
+
164
+
J'ai décompressé le tar dans mon répertoire `/opt`
165
+
166
+
J'ai aussi fait pointer ma variable `JAVA_HOME` au bon endroit :
167
+
168
+
```shell
169
+
~ > echo $JAVA_HOME
170
+
/opt/graalvm-ce-java11-21.0.0.2
171
+
```
172
+
173
+
### Création du projet
174
+
175
+
Dans IntelliJ, j'ai créé un nouveau projet Kotlin/Maven.
176
+
Je récupère donc un squelette de projet composé d'un `pom.xml`, et d'un `main.kt`.
177
+
178
+
Il n'y a plus qu'a combler les trous !
179
+
180
+
### Configuration de la compilation native GraalVM
181
+
182
+
Il faut tout d'abord installer l'outil `native-image` :
183
+
184
+
```shell
185
+
/opt/graalvm-ce-java11-21.0.0.2/bin > sudo ./gu install native-image
186
+
Downloading: Component catalog from www.graalvm.org
187
+
Processing Component: Native Image
188
+
Downloading: Component native-image: Native Image from github.com
189
+
Installing new component: Native Image (org.graalvm.native-image, version 21.0.0.2)
190
+
```
191
+
192
+
(j'exécute cette commande avec sudo, car mon répertoire /opt est protégé)
193
+
194
+
Ensuite, on va utiliser le plugin maven `native-image-maven-plugin` pour produire l'image native de notre projet.
195
+
On ajoute le bloc de configuration dans notre `pom.xml`:
196
+
197
+
```xml
198
+
<!-- building native image with graal VM -->
199
+
<plugin>
200
+
<groupId>org.graalvm.nativeimage</groupId>
201
+
<artifactId>native-image-maven-plugin</artifactId>
202
+
<version>${graalvm.version}</version>
203
+
<executions>
204
+
<execution>
205
+
<goals>
206
+
<goal>native-image</goal>
207
+
</goals>
208
+
<phase>package</phase>
209
+
</execution>
210
+
</executions>
211
+
<configuration>
212
+
<imageName>keyligh</imageName>
213
+
<mainClass>MainKt</mainClass>
214
+
<buildArgs>
215
+
--no-fallback
216
+
--enable-https
217
+
</buildArgs>
218
+
</configuration>
219
+
</plugin>
220
+
```
221
+
222
+
Les paramètres importants sont :
223
+
* imageName : le nom du binaire produit
224
+
* mainClass : le nom de la classe Java "point d'entrée" de notre application. Ici, notre fichier main.kt qui contient la fonction kotlin `main` sera transformé à la compilation en classe Java `MainKt`.
225
+
* --no-fallback : permet d'empêcher de produire un simple jar si la compilation native échoue
226
+
* --enable-https : permet d'activer le mode HTTPS (même si on ne l'utilise pas, le client Java HTTPClient instancie le mode par défaut)
227
+
228
+
La doc complète du plugin est ici https://www.graalvm.org/reference-manual/native-image/NativeImageMavenPlugin/
229
+
230
+
### Implémentation
231
+
232
+
L'implémentation du code est très basique, j'ai choisi d'utiliser la librairie `jmdns` pour exécuter les requêtes mDNS depuis le CLI, et le framework `picocli` pour implémenter la gestion des commandes et des paramètres.
233
+
234
+
Le code est disponible sur Github dans le repository [juwit/keylight-cli](https://github.com/juwit/keylight-cli/).
235
+
236
+
J'ai aussi configuré `picocli` pour la compilation native avec un l'annotation processor `picocli-codegen`, en m'inspirant de leur documentation [Picocli on GraalVM](https://picocli.info/picocli-on-graalvm.html) :
237
+
238
+
```xml
239
+
<plugin>
240
+
<groupId>org.jetbrains.kotlin</groupId>
241
+
<artifactId>kotlin-maven-plugin</artifactId>
242
+
<version>1.4.31</version>
243
+
<executions>
244
+
<execution>
245
+
<id>kapt</id>
246
+
<goals>
247
+
<goal>kapt</goal>
248
+
</goals>
249
+
<configuration>
250
+
<sourceDirs>
251
+
<sourceDir>src/main/kotlin</sourceDir>
252
+
</sourceDirs>
253
+
<annotationProcessorPaths>
254
+
<annotationProcessorPath>
255
+
<groupId>info.picocli</groupId>
256
+
<artifactId>picocli-codegen</artifactId>
257
+
<version>${picocli.version}</version>
258
+
</annotationProcessorPath>
259
+
</annotationProcessorPaths>
260
+
</configuration>
261
+
</execution>
262
+
</executions>
263
+
</plugin>
264
+
```
265
+
266
+
### Conclusion
267
+
268
+
Ce petit projet m'a permis:
269
+
270
+
* d'outiller mon Keylight d'Elgato avec un CLI sous Linux (que je vais pouvoir cabler avec mon Streamdeck)
271
+
* de découvrir le protocole mDNS !
272
+
* et de tester `picocli` et la compilation native de `GraalVM`
273
+
274
+
Rien de très compliqué, mais de bout en bout, j'y ai bien passé 8 à 10 heures. Le résultat est plutôt cool, et je me sert du CLI presque tous les jours !
+202
content/posts/2022-06-17-direnv-pour-votre-shell.md
+202
content/posts/2022-06-17-direnv-pour-votre-shell.md
···
1
+
---
2
+
created: "2022-06-17"
3
+
date: "2022-06-17T00:00:00Z"
4
+
language: fr
5
+
modified: "2022-08-05"
6
+
tags:
7
+
- DevOps
8
+
- Shell
9
+
title: direnv pour booster votre shell
10
+
slug: direnv-pour-votre-shell
11
+
---
12
+
13
+
# direnv pour booster votre shell
14
+
## Le problème
15
+
Je suis le genre de développeur qui travaille toujours avec un terminal ouvert sur le côté, en plus de mon IDE.
16
+
Je lance souvent des commandes `mvn` pour m'assurer que mon projet compile et que mes tests s'exécutent correctement. C'est un vieux réflexe qui date de l'époque où les IDE n'avaient qu'un support limité de *Maven*. Lancer ces commandes hors-IDE m'aide souvent à valider que tout fonctionnera bien dans un environnement de CI par exemple.
17
+
J'ai donc parfois besoin de changer de version de *Java* en fonction du projet dans lequel je me trouve.
18
+
*Maven* utilise la variable d'environnement `JAVA_HOME` pour localiser l'installation de *Java* à utiliser. Donc être capable de charger des variables d'environnement différentes en fonction d'un projet peut s'avérer pratique.
19
+
Un autre usage courant consiste à venir charger des clé d'API ou des secrets d'accès cloud comme des variables `AWS_ACCESS_KEY` ou autres en fonction de mes différents projets.
20
+
## direnv
21
+
`direnv` ([lien](https://direnv.net/)) est un outil écrit en go qui permet de charger des variables d'environnement dans la session courante du terminal, lorsqu'on change de répertoire en effectuant un `cd` .
22
+
### Installation
23
+
`direnv` est disponible dans les dépots de nombreuses distributions Linux, l'installation sur Ubuntu se fait avec les commandes habituelles, à savoir `apt install direnv`.
24
+
L'installation pour d'autres distributions se fait à partir des dépôts, ou bien directement à partir de binaires pré-compilés à récupérer sur Github dans [les releases de direnv](https://github.com/direnv/direnv/releases).
25
+
### Configuration
26
+
Une fois installé, il faut indiquer au shell d'appeler le binaire `direnv` à chaque changement de répertoire.
27
+
Le shell que j'utilise au quotidien est `zsh`. Pour `zsh`, la configuration de `direnv` consiste à venir modifier mon fichier `~/.zshrc` pour y ajouter la ligne suivante:
28
+
```shell
29
+
eval "$(direnv hook zsh)"
30
+
```
31
+
Les procédures de configuration pour les autres shells sont détaillées [sur le site de direnv](https://direnv.net/docs/hook.html) et sont du même ordre que la procédure ci-dessus.
32
+
## Utilisation basique
33
+
L'utilisation de `direnv` se fait au travers d'un fichier `.envrc` à positionner dans le répertoire souhaité.
34
+
Ce fichier peut contenir :
35
+
* des commandes `export` pour déclarer des variables d'environnement
36
+
* des appels de fonction de la stdlib `direnv`
37
+
* des appels de fonction customisés
38
+
* du code shell (bash)
39
+
40
+
Un exemple de fichier `.envrc` déposé dans un répertoire `~/workspaces/demo-direnv`:
41
+
```shell
42
+
export JAVA_HOME=/opt/jdk-17.0.1+12
43
+
export MAVEN_HOME=/opt/apache-maven-3.8.4
44
+
```
45
+
Ce fichier déclare deux variables d'environnement qui me sont utiles dans un projet Java.
46
+
À l'entrée dans le répertoire contenant ce fichier, `direnv` va tenter de charger le fichier. Les variables d'environnement exportées par le fichier seront alors chargées dans la session shell courante.
47
+
Au premier chargement d'un fichier, ou après une modification, `direnv` demandera une validation explicite pour autoriser le fichier.
48
+
```shell
49
+
~/workspaces > cd demo-direnv
50
+
direnv: error /home/jwittouck/workspaces/demo-direnv/.envrc is blocked. Run `direnv allow` to approve its content
51
+
```
52
+
J'exécute donc `direnv allow` pour autoriser le chargement de mon fichier `.envrc`:
53
+
```shell
54
+
~/workspaces/demo-direnv > direnv allow
55
+
direnv: loading ~/workspaces/demo-direnv/.envrc
56
+
direnv: export +JAVA_HOME +MAVEN_HOME
57
+
~/workspaces/demo-direnv >
58
+
```
59
+
`direnv` nous indique qu'il a chargé notre fichier, ainsi que nos deux variables d'environnement.
60
+
Nous pouvons maintenant les utiliser:
61
+
```shell
62
+
~/workspaces/demo-direnv > echo $JAVA_HOME
63
+
/opt/jdk-17.0.1+12
64
+
~/workspaces/demo-direnv > echo $MAVEN_HOME
65
+
/opt/apache-maven-3.8.4
66
+
```
67
+
Si on quitte le répertoire, les variables sont déchargées:
68
+
```shell
69
+
~/workspaces/demo-direnv > cd ..
70
+
direnv: unloading
71
+
~/workspaces > echo $JAVA_HOME
72
+
# rien ici !
73
+
```
74
+
## Modification du PATH
75
+
Pour nous simplifier la vie, `direnv` propose des fonctions qui permettent de manipuler le `PATH` facilement. La fonction `PATH_add` permet d'ajouter simplement une nouvelle valeur au `PATH`. En voici un exemple dans mon fichier `.envrc` précédent:
76
+
```shell
77
+
export JAVA_HOME=/opt/jdk-17.0.1+12
78
+
export MAVEN_HOME=/opt/apache-maven-3.8.4
79
+
80
+
PATH_add $JAVA_HOME/bin
81
+
PATH_add $MAVEN_HOME/bin
82
+
```
83
+
Avec cette nouvelle version de mon fichier, j'ai donc ajouté mes versions de `java` et `maven` au `PATH`. Ces ajouts seront retirés à la sortie du répertoire:
84
+
```shell
85
+
# je rentre dans mon répertoire demo-direnv
86
+
~/workspaces > cd demo-direnv
87
+
direnv: loading ~/workspaces/demo-direnv/.envrc
88
+
direnv: export +JAVA_HOME +MAVEN_HOME ~PATH
89
+
90
+
# le $PATH a été modifié
91
+
~/workspaces/demo-direnv > java --version
92
+
openjdk 17.0.1 2021-10-19
93
+
OpenJDK Runtime Environment Temurin-17.0.1+12 (build 17.0.1+12)
94
+
OpenJDK 64-Bit Server VM Temurin-17.0.1+12 (build 17.0.1+12, mixed mode, sharing)
95
+
96
+
# je sors du répertoire
97
+
~/workspaces/demo-direnv > cd ..
98
+
direnv: unloading
99
+
100
+
# le $PATH ne contient plus la commande java
101
+
~/workspaces > java --version
102
+
zsh: command not found: java
103
+
```
104
+
Avec `direnv`, je peux donc changer de version de `java` dans mon `PATH`, simplement en changeant de répertoire.
105
+
## Utilisation avancée
106
+
Pour aller plus loin, `direnv` propose une librairie de fonctions qu'ils nomment *stdlib*. Ces fonctions sont listées et documentées dans la documentation de direnv [man/direnv-stdlib.1](https://direnv.net/man/direnv-stdlib.1.html).
107
+
Voici quelques unes de ces commandes que j'utilise régulièrement.
108
+
### [source_up](https://direnv.net/man/direnv-stdlib.1.html#codesourceup-ltfilenamegtcode)
109
+
Cette commande permet d'aller chercher et exécuter le premier fichier `.envrc` dans l'arborescence remontante des fichiers, ce qui permet de factoriser un peu le contenu de mes fichiers `.envrc`.
110
+
Un exemple concret d'arborescence de fichiers:
111
+
```shell
112
+
.
113
+
└── workspaces
114
+
├── .envrc
115
+
├── projet-java-11
116
+
│ └── .envrc
117
+
└── projet-java-17
118
+
└── .envrc
119
+
```
120
+
Le fichier `~/workspaces/.envrc` contient les variables communes à mes deux projets:
121
+
```shell
122
+
export MAVEN_HOME=/opt/apache-maven-3.8.4
123
+
PATH_add $MAVEN_HOME/bin
124
+
```
125
+
Le fichier `~/workspaces/projet-java-11/.envrc` contient une configuration pour *Java* 11, ainsi que la commande `source_up` qui permet de charger le fichier `~/workspaces/.envrc`:
126
+
```shell
127
+
source_up
128
+
export JAVA_HOME=/opt/jdk-11.0.13+8
129
+
PATH_add $JAVA_HOME/bin
130
+
```
131
+
Le fichier `~/workspaces/projet-java-17/.envrc` contient une configuration similaire pour *Java* 17:
132
+
```shell
133
+
source_up
134
+
export JAVA_HOME=/opt/jdk-17.0.1+12
135
+
PATH_add $JAVA_HOME/bin
136
+
```
137
+
Avec cette utilisation, la variable `MAVEN_HOME` est disponible dans les sous-répertoires. Cette configuration permet de factoriser mes fichiers `.envrc` pour tous mes projets.
138
+
### [dotenv](https://direnv.net/man/direnv-stdlib.1.html#codedotenv-ltdotenvpathgtcode)
139
+
`direnv` peut aussi scruter les fichiers `.env`, qui doivent exposer les variables d'environnement sous forme de clé/valeur. Les fichiers `.env` sont moins souple car aucun script ne peut y être écrit. La commande `dotenv` peut néanmoins aider si des `.env` existent déjà sur un projet.
140
+
Voici un exemple de fichier `.env`:
141
+
```shell
142
+
AWS_ACCESS_KEY_ID=xxxx-xxx-xxx-xxxx
143
+
AWS_SECRET_ACCESS_KEY=xxxx-xxx-xxx-xxxx
144
+
```
145
+
Et un exemple de fichier `.envrc` qui charge le fichier `.env`:
146
+
```shell
147
+
dotenv
148
+
```
149
+
Dans le cas où beaucoup de projets utilisent des `.env`, on peut aussi configurer `direnv` pour charger ces fichiers automatiquement, en plus des `.envrc` (qui restent chargés en priorité)
150
+
Cette configuration se fait dans `~/.config/direnv/direnv.toml`:
151
+
```toml
152
+
[global]
153
+
load_dotenv = true
154
+
```
155
+
### [whitelist](https://direnv.net/man/direnv.toml.1.html#whitelist)
156
+
Par défaut, pour chaque fichier `.envrc`, nouveau ou modifié, `direnv` affichera ce message:
157
+
```text
158
+
direnv: error .envrc is blocked. Run `direnv allow` to approve its content
159
+
```
160
+
Il faut donc utiliser la commande `direnv allow` pour autoriser ces fichiers. Cela peut être assez rébarbatif quand cela arrive sur de nombreux projets.
161
+
`direnv` fournit une configuration permettant de whitelister les fichiers et de les autoriser automatiquement. J'y ai ajouté mon répertoire de travail. Cette configuration se fait dans `~/.config/direnv/direnv.toml`:
162
+
```toml
163
+
[whitelist]
164
+
prefix = ["/home/jwittouck/workspaces"]
165
+
```
166
+
### Fonction customisées
167
+
Pour améliorer l'exemple plus haut concernant la gestion de la variable `JAVA_HOME`, il est aussi possible d'enrichir les fonctions disponibles de `direnv`.
168
+
Pour cela, il faut les ajouter au fichier `~/.config/direnv/direnvrc`.
169
+
Pour mon usage, j'ai créé cette fonction :
170
+
```shell
171
+
function use_java(){
172
+
echo "Using Java version $1"
173
+
export JAVA_HOME=$(find /opt -maxdepth 1 -type d -name "jdk-$1*")
174
+
echo "Loading JAVA_HOME $JAVA_HOME"
175
+
PATH_add $JAVA_HOME/bin
176
+
}
177
+
```
178
+
Tous mes JDK sont installés dans `/opt`. Cette fonction permet de trouver le JDK qui correspond au premier paramètre de la fonction et de positionner les variables `JAVA_HOME` et `PATH`.
179
+
Elle s'utilise dans un `.envrc` de cette manière:
180
+
```shell
181
+
use_java 17
182
+
# ou
183
+
# use_java 11
184
+
```
185
+
et voici ce que loggue `direnv` à l'entrée du répertoire :
186
+
```shell
187
+
~/workspaces > cd demo-direnv
188
+
direnv: loading ~/workspaces/demo-direnv/.envrc
189
+
direnv: using java 17
190
+
Using Java version 17
191
+
Loading JAVA_HOME /opt/jdk-17.0.1+12
192
+
direnv: export +JAVA_HOME +MAVEN_HOME ~PATH
193
+
```
194
+
## Conclusion
195
+
`direnv` est un outil très pratique pour manipuler les variables d'environnement. Il s'adresse avant tout à ceux qui passent du temps dans un shell, devs ou sysadmins.
196
+
Cet article a présenté principalement les usages que j'en ai pour mes projets *Java*, mais `direnv` propose aussi des fonctions pour les projets `node`, `ruby`, `python` et d'autres.
197
+
C'est vite devenu un indispensable dans mes shells.
198
+
### Liens
199
+
* la page d'accueil du projet sur [direnv.net](https://direnv.net/)
200
+
* le repository Github du projet [direnv/direnv](https://github.com/direnv/direnv)
201
+
* la documentation d'install [docs/installation](https://direnv.net/docs/installation.html)
202
+
* la documentation de la stdlib [man/direnv-stdlib](https://direnv.net/man/direnv-stdlib.1.html)
+413
content/posts/2022-07-22-skaffold-et-minikube/index.md.md
+413
content/posts/2022-07-22-skaffold-et-minikube/index.md.md
···
1
+
---
2
+
created: "2022-07-22"
3
+
date: "2022-07-22T00:00:00Z"
4
+
language: fr
5
+
modified: "2022-07-29"
6
+
tags:
7
+
- DevOps
8
+
- Kubernetes
9
+
- Skaffold
10
+
- Minikube
11
+
- Docker
12
+
- Tutorial
13
+
title: Exécuter une application localement sur minikube avec skaffold
14
+
slug: skaffold-et-minikube
15
+
---
16
+
17
+
# Exécuter une application localement sur minikube avec skaffold
18
+
Lors du développement d'une application pour Kubernetes, le développeur est souvent lié à une boucle de feedback assez longue:
19
+
1. Développement
20
+
2. Contruction de l'image Docker (quelques secondes/minutes)
21
+
3. Push de l'image sur un registry
22
+
4. Déploiement sur Kubernetes (quelques minutes)
23
+
24
+
Cette boucle est généralement implémentée par des pipelines de CI/CD. Ces pipelines augmentent encore le temps entre le développement et une application démarrée sur Kubernetes. Ce temps est relativement long lorsqu'on compare un cycle de développement local auquel un développeur peut être habitué.
25
+
26
+
[`skaffold`](https://skaffold.dev), développé par Google, est un outil open-source en license Apache, qui permet d'implémenter cette boucle de développement sur un environnement Kubernetes local ou distant. La promesse de `skaffold` est de rendre le développement sur Kubernetes simple, rapide et reproductible.
27
+
28
+
29
+
30
+
`skaffold` implémente un *pipeline* qui se déroule en plusieurs étapes:
31
+
1. *build* : construction des images docker avec:
32
+
* Docker (sur base d'un `Dockerfile`)
33
+
* Buildpacks
34
+
* Jib
35
+
2. *tag* de l'image docker en utilisant différentes stratégies :
36
+
* l'identifiant du commit git (par défaut)
37
+
* une date
38
+
* des variables d'environnement
39
+
* un hash des fichiers source
40
+
* push de l'image sur un registry
41
+
* chargement direct de l'image dans un cluster Kubernetes
42
+
3. *deploy* : déploiement de l'application sur Kubernetes (local ou distant) en utilisant:
43
+
* `kubectl` et des fichiers yaml
44
+
* `kustomize`
45
+
* `helm`
46
+
4. *tail logs & port forward* : affiche les logs de l'application et redirige un port local
47
+
5. *status check* : attend la fin du bon déploiement de application
48
+
49
+
`skaffold` a besoin d'un code à déployer, ainsi qu'un accès à un cluster Kubernetes. L'accès au cluster se configure de la même manière que pour `kubectl`, à travers un fichier `~/.kube/config`. Pour la suite de cet article, j'utilise un cluster `minikube` que j'installe sur mon poste pour l'occasion.
50
+
51
+
## Déployer un cluster minikube localement
52
+
La première étape consiste à déployer un cluster `minikube` sur mon poste de développement.
53
+
Pour ce faire, le plus pratique est de suivre les étapes d'installation de l'outil détaillées [dans leur documentation d'installation](https://minikube.sigs.k8s.io/docs/start/).
54
+
55
+
56
+
57
+
Voici les commandes que j'ai exécuté pour installer `minikube` sur mon poste Linux :
58
+
```shell
59
+
$ curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
60
+
sudo install minikube-linux-amd64 /usr/local/bin/minikube
61
+
```
62
+
`docker` étant déjà installé sur mon poste, je peux tout de suite démarrer un cluster Kubernetes local avec la commande `minikube start`:
63
+
```shell
64
+
$ minikube start
65
+
😄 minikube v1.24.0 on Debian bookworm/sid
66
+
🎉 minikube 1.26.0 is available! Download it: https://github.com/kubernetes/minikube/releases/tag/v1.26.0
67
+
💡 To disable this notice, run: 'minikube config set WantUpdateNotification false'
68
+
69
+
✨ Using the docker driver based on existing profile
70
+
👍 Starting control plane node minikube in cluster minikube
71
+
🚜 Pulling base image ...
72
+
🔄 Restarting existing docker container for "minikube" ...
73
+
74
+
🧯 Docker is nearly out of disk space, which may cause deployments to fail! (92% of capacity)
75
+
💡 Suggestion:
76
+
77
+
Try one or more of the following to free up space on the device:
78
+
79
+
1. Run "docker system prune" to remove unused Docker data (optionally with "-a")
80
+
2. Increase the storage allocated to Docker for Desktop by clicking on:
81
+
Docker icon > Preferences > Resources > Disk Image Size
82
+
3. Run "minikube ssh -- docker system prune" if using the Docker container runtime
83
+
🍿 Related issue: https://github.com/kubernetes/minikube/issues/9024
84
+
85
+
🐳 Preparing Kubernetes v1.22.3 on Docker 20.10.8 ...
86
+
🔎 Verifying Kubernetes components...
87
+
▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
88
+
▪ Using image k8s.gcr.io/ingress-nginx/kube-webhook-certgen:v1.1.1
89
+
▪ Using image k8s.gcr.io/ingress-nginx/controller:v1.0.4
90
+
▪ Using image k8s.gcr.io/ingress-nginx/kube-webhook-certgen:v1.1.1
91
+
🔎 Verifying ingress addon...
92
+
🌟 Enabled addons: storage-provisioner, default-storageclass, ingress
93
+
🏄 Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default
94
+
```
95
+
Par défaut, `minikube` va générer un fichier de configuration pour `kubectl` dans `~/.kube/config`. La commande `kubectl` sera donc immédiatement utilisable:
96
+
```shell
97
+
$ kubectl get nodes
98
+
NAME STATUS ROLES AGE VERSION
99
+
minikube Ready control-plane,master 1d v1.22.3
100
+
```
101
+
Si la commande `kubectl` n'est pas installée, `minikube` l'intègre et elle est utilisable de cette manière:
102
+
```shell
103
+
$ minikube kubectl get nodes
104
+
NAME STATUS ROLES AGE VERSION
105
+
minikube Ready control-plane,master 1d v1.22.3
106
+
```
107
+
Pour ma part, j'ai installé `kubectl` avec l'outil de packaging de mon système en suivant [cette procédure](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/#install-using-native-package-management).
108
+
Une fois que `minikube` et `kubectl` sont installés, démarrés et configurés, je peux passer à l'installation de `skaffold`.
109
+
## Installation de skaffold
110
+
L'installation de `skaffold` est similaire à celle de `minikube` et `kubectl`.
111
+
J'ai suivi la procédure sur [dans leur documentation](https://skaffold.dev/docs/install/) et installé la version Linux avec ces commandes:
112
+
```shell
113
+
$ curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 && \
114
+
sudo install skaffold /usr/local/bin/
115
+
```
116
+
`skaffold` est maintenant disponible sur mon poste:
117
+
```shell
118
+
$ skaffold version
119
+
v1.39.1
120
+
```
121
+
## Configuration d'un projet
122
+
`skaffold` se configure avec un fichier `skaffold.yml` à positionner à la racine de votre projet.
123
+
J'ai pris pour exemple un projet Micronaut avec lequel je suis en train d'expérimenter:
124
+
```shell
125
+
.
126
+
├── micronaut-cli.yml
127
+
├── mvnw
128
+
├── mvnw.bat
129
+
├── pom.xml
130
+
├── README.md
131
+
└── src
132
+
└── main
133
+
├── java
134
+
│ └── com
135
+
│ └── example
136
+
│ ├── Application.java
137
+
│ └── pokemons
138
+
│ ├── PokemonController.java
139
+
│ ├── Pokemon.java
140
+
│ ├── PokemonRepository.java
141
+
│ └── PokemonService.java
142
+
└── resources
143
+
├── application.yml
144
+
├── bootstrap.yml
145
+
└── logback.xml
146
+
```
147
+
La configuration initiale du projet se fait en utilisant la commande `skaffold init` . Cette commande propose différentes options ([documentation](https://skaffold.dev/docs/pipeline-stages/init/)) en interactif pour créer son fichier de configuration. Cette étape est plus simple qu'écrire le fichier à la main.
148
+
Comme je n'ai pas encore écrit de fichiers manifest Kubernetes pour mon application, `skaffold` a une option pour les générer: `--generate-manifests`.
149
+
150
+
La première étape consiste à configurer la phase de *build* de l'application, à savoir la construction de l'image docker. Plusieurs options seront proposées, en fonction de ce qui est déjà disponible dans le code : `Dockerfile`, configuration de `jib`, ou manifests Kubernetes.
151
+
Mon projet Micronaut a déjà une configuration pour `jib` dans son `pom.xml`:
152
+
```xml
153
+
<build>
154
+
<plugins>
155
+
<plugin>
156
+
<groupId>com.google.cloud.tools</groupId>
157
+
<artifactId>jib-maven-plugin</artifactId>
158
+
<version>3.2.1</version>
159
+
</plugin>
160
+
</plugins>
161
+
</build>
162
+
```
163
+
164
+
`skaffold init` me propose alors de paramétrer ma phase de *build* avec Buildpacks ou Jib:
165
+
166
+
```shell
167
+
$ skaffold init --generate-manifests
168
+
? Which builders would you like to create Kubernetes resources for? [Use arrows to move, space to select, <right> to all, <left> to none, type to filter]
169
+
> [ ] Buildpacks (pom.xml)
170
+
[ ] Jib Maven Plugin (com.example:demo-app-pokemon-micronaut, pom.xml)
171
+
```
172
+
Je choisis l'option *Jib* étant donné que ce plugin est déjà configuré pour mon application.
173
+
174
+
L'étape suivante propose de configurer un port à forwarder pour mon image Docker, je saisis le port 8080 qui est le port par défaut de mon application:
175
+
```shell
176
+
? Select port to forward for pom-xml-image (leave blank for none): 8080
177
+
```
178
+
`skaffold` me propose ensuite un manifest Kubernetes et me demande si je souhaite générer les fichiers:
179
+
```shell
180
+
? Do you want to write this configuration, along with the generated k8s manifests, to skaffold.yaml? Yes
181
+
Generated manifest deployment.yaml was written
182
+
Configuration skaffold.yaml was written
183
+
You can now run [skaffold build] to build the artifacts
184
+
or [skaffold run] to build and deploy
185
+
or [skaffold dev] to enter development mode, with auto-redeploy
186
+
```
187
+
À noter que si des fichiers de déploiement Kubernetes sont déjà présents dans l'application, `skaffold` les détecte et les ajoute à sa configuration automatiquement.
188
+
Le fichier `deployment.yaml` généré pour Kubernetes est simple:
189
+
```yaml
190
+
apiVersion: v1
191
+
kind: Service
192
+
metadata:
193
+
name: pom-xml-image
194
+
labels:
195
+
app: pom-xml-image
196
+
spec:
197
+
ports:
198
+
- port: 8080
199
+
protocol: TCP
200
+
clusterIP: None
201
+
selector:
202
+
app: pom-xml-image
203
+
---
204
+
apiVersion: apps/v1
205
+
kind: Deployment
206
+
metadata:
207
+
name: pom-xml-image
208
+
labels:
209
+
app: pom-xml-image
210
+
spec:
211
+
replicas: 1
212
+
selector:
213
+
matchLabels:
214
+
app: pom-xml-image
215
+
template:
216
+
metadata:
217
+
labels:
218
+
app: pom-xml-image
219
+
spec:
220
+
containers:
221
+
- name: pom-xml-image
222
+
image: pom-xml-image
223
+
```
224
+
ainsi que le fichier `skaffold.yaml`
225
+
```yaml
226
+
apiVersion: skaffold/v2beta29
227
+
kind: Config
228
+
metadata:
229
+
name: demo-app-pokemon-micronaut
230
+
build:
231
+
artifacts:
232
+
- image: pom-xml-image
233
+
jib:
234
+
project: com.example:demo-app-pokemon-micronaut
235
+
deploy:
236
+
kubectl:
237
+
manifests:
238
+
- deployment.yaml
239
+
portForward:
240
+
- resourceType: service
241
+
resourceName: pom-xml-image
242
+
port: 8080
243
+
```
244
+
Le fichier généré contient de la configuration pour 3 étapes du pipeline de `skaffold`.
245
+
246
+
La phase de *build* est bien configurée pour construire une image Docker en utilisant *Jib*, l'image produite sera nommée `pom-xml-image`. Ce nom par défaut pourra être changé en modifiant ce fichier de configuration.
247
+
248
+
La phase de *deploy* est configurée pour déployer des manifests Kubernetes, ici le fichier `deployment.yaml` qui a été généré par la commande `skaffold init`. Ces fichiers manifest référencent l'image `pom-xml-image` dans la partie *Deployment* du manifest.
249
+
On voit donc ici comment on peut adapter cette configuration pour inclure d'autres fichiers, comme une *ConfigMap*.
250
+
251
+
J'ai pris le parti de déplacer les fichiers de manifest Kubernetes générés dans le répertoire `src/main/Kubernetes` de mon application et de renommer l'image générée.
252
+
Voici la structure de mon application après ces opérations:
253
+
```shell
254
+
.
255
+
├── micronaut-cli.yml
256
+
├── mvnw
257
+
├── mvnw.bat
258
+
├── pom.xml
259
+
├── README.md
260
+
├── skaffold.yaml
261
+
└── src
262
+
└── main
263
+
├── java
264
+
│ └── com
265
+
│ └── example
266
+
│ ├── Application.java
267
+
│ └── pokemons
268
+
│ ├── PokemonController.java
269
+
│ ├── Pokemon.java
270
+
│ ├── PokemonRepository.java
271
+
│ └── PokemonService.java
272
+
├── kubernetes
273
+
│ ├── configMap.yaml
274
+
│ ├── deployment.yaml
275
+
│ └── service.yaml
276
+
└── resources
277
+
├── application.yml
278
+
├── bootstrap.yml
279
+
└── logback.xml
280
+
```
281
+
Ainsi que le fichier `skaffold.yaml`:
282
+
```yaml
283
+
apiVersion: skaffold/v2beta29
284
+
kind: Config
285
+
metadata:
286
+
name: demo-skaffold
287
+
build:
288
+
artifacts:
289
+
- image: demo-skaffold
290
+
jib: {}
291
+
deploy:
292
+
kubectl:
293
+
manifests:
294
+
- src/main/kubernetes/*.yaml
295
+
portForward:
296
+
- resourceType: service
297
+
resourceName: demo-skaffold
298
+
port: 8080
299
+
```
300
+
## Démarrage de mon projet
301
+
Une fois les fichiers générés, la commande `skaffold dev` va:
302
+
* construire l'image docker en utilisant le builder *Jib* configuré
303
+
* déposer cette image directement dans l'environnement du `minikube`
304
+
* déployer les fichiers de configuration Kubernetes
305
+
* ouvrir un port-forward sur mon port d'écoute 8080
306
+
* afficher les logs de mon application dans mon shell
307
+
308
+
```shell
309
+
$ skaffold dev
310
+
Listing files to watch...
311
+
- demo-skaffold
312
+
Generating tags...
313
+
- demo-skaffold -> demo-skaffold:latest
314
+
Some taggers failed. Rerun with -vdebug for errors.
315
+
Checking cache...
316
+
- demo-skaffold: Found Locally
317
+
Tags used in deployment:
318
+
- demo-skaffold -> demo-skaffold:275bf648a141313e52f422d73ad69379be4f4d7c3e9e50fe3c16289da8391c33
319
+
Starting deploy...
320
+
- configmap/demo-skaffold created
321
+
- deployment.apps/demo-skaffold created
322
+
- service/demo-skaffold created
323
+
Waiting for deployments to stabilize...
324
+
- deployment/demo-skaffold is ready.
325
+
Deployments stabilized in 2.047 seconds
326
+
Port forwarding service/demo-skaffold in namespace default, remote port 8080 -> http://127.0.0.1:8080
327
+
Press Ctrl+C to exit
328
+
Watching for changes...
329
+
[backend] __ __ _ _
330
+
[backend] | \/ (_) ___ _ __ ___ _ __ __ _ _ _| |_
331
+
[backend] | |\/| | |/ __| '__/ _ \| '_ \ / _` | | | | __|
332
+
[backend] | | | | | (__| | | (_) | | | | (_| | |_| | |_
333
+
[backend] |_| |_|_|\___|_| \___/|_| |_|\__,_|\__,_|\__|
334
+
[backend] Micronaut (v3.5.1)
335
+
[backend]
336
+
[backend] 14:15:41.202 [main] INFO i.m.context.env.DefaultEnvironment - Established active environments: [k8s, cloud]
337
+
[backend] 14:15:41.557 [main] INFO io.micronaut.runtime.Micronaut - Startup completed in 803ms. Server Running: http://demo-skaffold-5bfb47c8fc-cvld4:8080
338
+
```
339
+
340
+
341
+
En quelques minutes, mon application est démarré sur mon cluster `minikube` local.
342
+
Je peux voir avec une commande `kubectl get all` que mes manifests ont bien été déployés et que mon application tourne:
343
+
```shell
344
+
$ kubectl get all
345
+
NAME READY STATUS RESTARTS AGE
346
+
pod/demo-skaffold-5bfb47c8fc-cvld4 1/1 Running 0 19m
347
+
348
+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
349
+
service/demo-skaffold ClusterIP None <none> 8080/TCP 19m
350
+
service/kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 1d
351
+
352
+
NAME READY UP-TO-DATE AVAILABLE AGE
353
+
deployment.apps/demo-skaffold 1/1 1 1 19m
354
+
355
+
NAME DESIRED CURRENT READY AGE
356
+
replicaset.apps/demo-skaffold-5bfb47c8fc 1 1 1 19m
357
+
358
+
```
359
+
`skaffold` est aussi capable de faire du *hot-reload* sans configuration supplémentaire pour les applications buildées avec *jib*.
360
+
Il suffit de:
361
+
* modifier le code
362
+
* attendre quelques secondes que le code soit re-compilé et l'application est re-démarrée
363
+
364
+
```shell
365
+
Watching for changes...
366
+
Generating tags...
367
+
- pom-xml-image -> pom-xml-image:latest
368
+
Some taggers failed. Rerun with -vdebug for errors.
369
+
Checking cache...
370
+
- pom-xml-image: Not found. Building
371
+
Starting build...
372
+
Found [minikube] context, using local docker daemon.
373
+
Building [pom-xml-image]...
374
+
Target platforms: [linux/amd64]
375
+
376
+
...
377
+
378
+
Build [pom-xml-image] succeeded
379
+
Tags used in deployment:
380
+
- pom-xml-image -> pom-xml-image:c6d646c3c9ba7ac130cfe23c31b2391584b4bddfce984b2cc1f1f2c711c9d509
381
+
Starting deploy...
382
+
Waiting for deployments to stabilize...
383
+
- deployment/pom-xml-image is ready.
384
+
Deployments stabilized in 1.038 second
385
+
Port forwarding service/pom-xml-image in namespace default, remote port 8080 -> http://127.0.0.1:8080
386
+
Watching for changes...
387
+
```
388
+
C'est particulièrement pratique pour tester une application localement!
389
+
Si je veux arrêter de développer, j'utilise la combinaison de touches *CTRL+C*, qui va stopper l'application et faire le ménage sur le cluster Kubernetes:
390
+
```shell
391
+
^C
392
+
Cleaning up...
393
+
- configmap "demo-skaffold" deleted
394
+
- deployment.apps "demo-skaffold" deleted
395
+
- service "demo-skaffold" deleted
396
+
```
397
+
## Conclusion
398
+
`skaffold` permet de rendre accessible au développeur le déploiement sur un cluster Kubernetes, local ou distant. Cet article a présenté son usage sur un cluster local `minikube`, mais `skaffold` fonctionne de manière indifférenciée sur un cluster distant. Il permet aussi de réutiliser des fichiers de configuration Kubernetes, Kustomize ou Helm existants, ce qui est très pratique si l'application dispose déjà de ce type de fichiers.
399
+
400
+
Le port forward est très bien intégré et pratique à l'usage (pas besoin de taper une commande `kubectl` supplémentaire).
401
+
402
+
La [documentation de `skaffold`](https://skaffold.dev/docs/) est très complète et indique tous les paramètres que chaque phase de son pipeline accepte et fourni aussi des liens vers des tutoriaux.
403
+
404
+
Enfin, `skaffold` est au coeur des plugins *Cloud Code* de Google, pour IntelliJ IDEA et VSCode pour l'exécution et le déploiement des application sur Kubernetes.
405
+
406
+
De nombreux [exemples](https://github.com/GoogleContainerTools/skaffold/tree/main/examples) sont disponibles sur le repository Github de `skaffold`, il y en aura surement un qui correspondra à votre type de projet si vous voulez expérimenter.
407
+
408
+
### Liens
409
+
410
+
* le repository Github de [GoogleContainerTools/skaffold](https://github.com/GoogleContainerTools/skaffold)
411
+
* le site web [skaffold.dev](https://skaffold.dev/)
412
+
* la [documentation](https://skaffold.dev/docs/)
413
+
* les [exemples de code sur Github](https://github.com/GoogleContainerTools/skaffold/tree/main/examples)
content/posts/2022-07-22-skaffold-et-minikube/localhost.png
content/posts/2022-07-22-skaffold-et-minikube/localhost.png
This is a binary file and will not be displayed.
content/posts/2022-07-22-skaffold-et-minikube/minikube-install.png
content/posts/2022-07-22-skaffold-et-minikube/minikube-install.png
This is a binary file and will not be displayed.
content/posts/2022-07-22-skaffold-et-minikube/skaffold.png
content/posts/2022-07-22-skaffold-et-minikube/skaffold.png
This is a binary file and will not be displayed.
content/posts/2023-02-23-mkdocs-material/create-docs-website-content-page.png
content/posts/2023-02-23-mkdocs-material/create-docs-website-content-page.png
This is a binary file and will not be displayed.
content/posts/2023-02-23-mkdocs-material/create-docs-website-github-pages.png
content/posts/2023-02-23-mkdocs-material/create-docs-website-github-pages.png
This is a binary file and will not be displayed.
content/posts/2023-02-23-mkdocs-material/create-docs-website-preview.png
content/posts/2023-02-23-mkdocs-material/create-docs-website-preview.png
This is a binary file and will not be displayed.
content/posts/2023-02-23-mkdocs-material/create-docs-website-theme.png
content/posts/2023-02-23-mkdocs-material/create-docs-website-theme.png
This is a binary file and will not be displayed.
content/posts/2023-02-23-mkdocs-material/create-docs-website-workflow.png
content/posts/2023-02-23-mkdocs-material/create-docs-website-workflow.png
This is a binary file and will not be displayed.
+414
content/posts/2023-02-23-mkdocs-material/index.md
+414
content/posts/2023-02-23-mkdocs-material/index.md
···
1
+
---
2
+
created: "2023-02-23"
3
+
date: "2023-02-23T00:00:00Z"
4
+
language: fr
5
+
modified: "2023-03-09"
6
+
tags:
7
+
- Git
8
+
- Tools
9
+
- Docs
10
+
- Tutorial
11
+
title: Créer un site web de documentation statique avec MkDocs
12
+
slug: mkdocs-material
13
+
---
14
+
15
+
# Créer un site web de documentation statique avec MkDocs
16
+
17
+
Que ce soit pour un projet d'entreprise ou un projet open-source, la documentation utilisateur et technique est cruciale.
18
+
Dans une documentation d'usage, les utilisateurs doivent pouvoir retrouver les instructions leur permettant d'accomplir les gestes métier de tous les jours.
19
+
Pour la documentation technique, les administrateurs, opérateurs et développeurs doivent pouvoir retrouver les opérations d'installation, de mise à jour, ou encore de développement du produit.
20
+
21
+
La documentation peut prendre plusieurs formes:
22
+
23
+
* un document bureautique, de type LibreOffice Writer ou Microsoft Word
24
+
* des pages dans un référentiel documentaire de type _wiki_, ou _Atlassian Confluence_
25
+
* un site web dédié
26
+
27
+
Les documents bureautique sont bien adaptés à la documentation de procédures, ou de spécifications. Cependant, ils souffrent de nombreux défauts comme le manque d'archivage des modifications, une recherche compliquée, un fort liant entre le format et le contenu et sont souvent portés par des formats propriétaires (le fameux `.docx`).
28
+
29
+
Les référentiels de type _wiki_ répondent au problèmes de recherche et d'archivage des historiques de modifications. Cependant, ils nécessitent souvent une infrastructure avec une base de données, et ont donc un coût d'hébergement et de maintenance.
30
+
31
+
Le cas du site web statique dédié est le plus adapté à un projet open-source. Le site sera exposé sur internet, aidant à mettre en visibilité le projet. Un site web statique nécessite un hébergement minimum, sans base de données, et sera donc plus simple à mettre en place.
32
+
33
+
# _documentation-as-Code_
34
+
35
+
Pour encourager les développeurs à rédiger plus de documentation, il est intéressant de considérer l'approche *documentation-as-code*.
36
+
Cette approche s'appuie sur les process et outils de développement pour proposer aux développeurs un moyen moderne d'écrire et publier leur documentation.
37
+
38
+
Dans un processus de _documentation-as-code_, les développeurs rédigent et archivent la documentation au même endroit que le code source, dans un repository _git_.
39
+
Cela permet de fournir une documentation plus précise, et plus à jour. Les mises à jour de documentation sont effectuées en même temps que les mises à jour du code source.
40
+
41
+
Un site web de documentation pourra alors être généré à partir des documents rédigés par les développeurs. Ce site pourra être publié avec des chaînes d'intégration continue.
42
+
43
+
## Les formats _asciidoc_ et _markdown_
44
+
45
+
En _documentation-as-code_, la documentation sera écrite dans un format simple, déjà maitrisé par les développeurs. Un des avantages principaux est que ces formats peuvent être édités dans les IDE que les développeurs utilisent déjà.
46
+
47
+
Les deux formats les plus utilisés sont l'_asciidoc_ et le _markdown_.
48
+
49
+
L'intérêt d'utiliser ces formats est multiple:
50
+
51
+
* le développeur se concentre sur la rédation du contenu plutôt que sur le formattage des données
52
+
* la documentation peut être archivée comme du code source, voire dans le même repository que le projet
53
+
* ces formats sont simples d'utilisation, même pour des personnes ayant peu ou pas de connaissances techniques
54
+
55
+
## Les générateurs de sites web statiques
56
+
57
+
Des fichiers _markdown_ ou _asciidoc_ sur un repository _git_ peuvent parfois être suffisant. _Gitlab_ et _Github_ sont capables d'afficher des fichiers _markdown_ ou _asciidoc_ directement dans leur interface. C'est le cas par exemple des fameux `README.md` qu'on retrouve sur une majorité de projets.
58
+
Cet usage peut suffire pour documenter une librairie ou un projet simple.
59
+
D'autres projets, plus compliqués, auront plus de pages de documentation, et des besoins de personnalisation, c'est là où un générateur de site web statique sera utile.
60
+
61
+
### _asciidoc_ et _asciidoctor_
62
+
63
+
La suite de cet article ne décrira pas comment mettre en place _asciidoc_ et _asciidoctor_, mais il était important de mentionner ces outils, qui sont utilisés par de nombreux projets.
64
+
65
+
_asciidoc_, couplé au générateur *asciidoctor* permet directement de générer des pages _HTML_ statiques à partir de un ou plusieurs fichiers de documentation source.
66
+
Les pages _HTML_ générées peuvent alors être publiées directement.
67
+
C'est ce qui est utilisé par le framework Java *Spring* par exemple.
68
+
69
+
Voici à titre d'exemple la [documentation générée pour le framework Spring](https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/) , à partir des documents *asciidoc* disponible sur _Github_:
70
+
71
+
72
+
73
+
74
+
Les sources sont visibles sur le [_Github_ de _Spring_](https://github.com/spring-projects/spring-boot/tree/main/spring-boot-project/spring-boot-docs/src/docs/asciidoc).
75
+
76
+
*Spring* utilise donc *asciidoctor* pour générer leur documentation dans 3 formats différents:
77
+
78
+
* un pdf complet
79
+
* une page HTML complète (autonome)
80
+
* un ensemble de pages HTMLs liées entre elles
81
+
82
+
### _markdown_ et _MkDocs_
83
+
84
+
Bien qu'*asciidoctor* propose de générer plusieurs formats, d'autres générateurs compatibles Markdown existent:
85
+
86
+
* [_Jekyll_](https://jekyllrb.com/), est plutôt orienté blogging
87
+
* [_Hugo_](https://gohugo.io/), est orienté site web généraliste
88
+
* [_MkDocs_](https://www.mkdocs.org/), est orienté documentation
89
+
90
+
Ces générateurs amènent une structure de site web classique, avec une navigation à plusieurs niveaux de menus, et souvent des champs de recherche.
91
+
92
+
Parmis ces 3 solutions, _MkDocs_ est le plus orienté documentation, c'est cet outil que nous allons mettre en place dans la suite de cet article.
93
+
94
+
# Mise en place de _MkDocs_
95
+
96
+
Nous allons voir dans la suite de cet article:
97
+
98
+
* l'installation et la configuration de _MkDocs_
99
+
* l'utilisation et la configuration d'un thème et sa customisation (logo, couleurs)
100
+
* la rédaction de quelques pages
101
+
* la publication en site statique avec _Github Actions_ & _Github Pages_
102
+
103
+
# Création du projet de documentation
104
+
105
+
La documentation peut être créée comme un repository Git dédié, ou comme un répertoire d'un repository existant, dans le cas d'une approche _mono-repo_ par exemple.
106
+
107
+
C'est cette deuxième solution que nous allons suivre.
108
+
Dans un projet existant, on commence par créer un répertoire `docs`:
109
+
110
+
```bash
111
+
mkdir docs/
112
+
```
113
+
114
+
La création du squelette de documentation peut se faire avec le _CLI_ (pour Command Line Interface) de _MkDocs_ et la commande [`mkdocs new`](https://www.mkdocs.org/user-guide/cli/#mkdocs-new), ou simplement en initialisant quelques fichiers à la main.
115
+
116
+
Nous allons créer l'arborescence suivante:
117
+
118
+
```text
119
+
.
120
+
├─ docs/
121
+
│ └─ index.md
122
+
└─ mkdocs.yml
123
+
```
124
+
125
+
Le contenu de notre fichier `mkdocs.yml` minimal est le suivant:
126
+
127
+
```yaml
128
+
site_name: Galactic Empire
129
+
```
130
+
131
+
Pour référence, la [documentation de _MkDocs_](https://www.mkdocs.org/user-guide/configuration/) liste les paramètres de configuration qui peuvent être modifiés dans le fichier `mkdocs.yml`.
132
+
133
+
Un fichier `docs/index.md` permet de servir de page d'accueil:
134
+
135
+
```markdown
136
+
# Documentation
137
+
138
+
Bienvenue sur la documentation de l'Empire Galactique
139
+
```
140
+
141
+
# Démarrage de _MkDocs_ en mode preview
142
+
143
+
_MkDocs_ est écrit en python, et peut être installé en quelques commandes. La [procédure d'installation](https://www.mkdocs.org/user-guide/installation/#installing-mkdocs) est simple:
144
+
145
+
```bash
146
+
pip install mkdocs
147
+
```
148
+
149
+
Il existe également des images _Docker_ dédiées, qui seront utiles pour l'automatisation avec _Github Actions_ ou _Gitlab CI_ pour la publication, bien que nous allons nous en passer.
150
+
151
+
Le démarrage du site, en mode _preview_, se fait en une commande:
152
+
153
+
```bash
154
+
$ mkdocs serve
155
+
INFO - Building documentation...
156
+
INFO - Cleaning site directory
157
+
INFO - Documentation built in 0.15 seconds
158
+
INFO - [09:32:45] Watching paths for changes: 'docs', 'mkdocs.yml'
159
+
INFO - [09:32:45] Serving on http://127.0.0.1:8000/
160
+
```
161
+
162
+
Le site web est construit, et disponible en local:
163
+
164
+
165
+
166
+
# Ajout d'un thème & customisation
167
+
168
+
Le thème par défaut n'est pas très élégant.
169
+
Plusieurs thèmes existent, et il est possible de créer le sien, à condition de savoir un peu développer en HTML/CSS.
170
+
171
+
Néanmoins, un thème populaire est [_Material for MkDocs_](https://squidfunk.github.io/mkdocs-material) (13k stars sur _Github_). Ce thème propose une interface épurée, personnalisable, et le support d'extensions à _markdown_.
172
+
173
+
L'installation du thème se fait en une ligne de commande:
174
+
175
+
```bash
176
+
pip install mkdocs-material
177
+
```
178
+
179
+
Pour utiliser notre thème, il faut le préciser dans le fichier `mkdocs.yml`:
180
+
181
+
```yaml
182
+
site_name: Galactic Empire
183
+
184
+
# configuration du thème
185
+
theme:
186
+
name: material
187
+
```
188
+
189
+
Nous allons maintenant un peu customiser notre thème.
190
+
Toutes les instructions sont disponible dans la [documentation de _Material for Mkdocs_](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/):
191
+
192
+
## Le logo
193
+
194
+
Pour changer le logo, il faut indiquer quel fichier utiliser dans la configuration.
195
+
Pour notre exemple, je suis allé chercher un logo libre de droits sur le site web [https://pngrepo.com](https://pngrepo.com), et je l'ai positionné dans un répertoire `docs/assets` que j'ai créé pour l'occasion:
196
+
197
+
```
198
+
.
199
+
├── docs
200
+
│ ├── assets
201
+
│ │ └── death-star.png
202
+
│ └── index.md
203
+
└── mkdocs.yml
204
+
```
205
+
206
+
Le logo est ensuite référencé dans le fichier de configuration:
207
+
208
+
```yaml
209
+
site_name: Galactic Empire project
210
+
211
+
# configuration du thème
212
+
theme:
213
+
name: material
214
+
logo: assets/death-star.png
215
+
```
216
+
217
+
À noter que le répertoire _assets_ déclaré dans la configuration est bien relatif au répertoire _docs_.
218
+
219
+
## Les couleurs
220
+
La configuration des couleurs passe par une déclaration CSS, si on veut sortir des couleurs proposées dans la palette de couleurs par défaut.
221
+
Un fichier css peut surcharger l'ensemble des variables de couleurs prédéfinies. La liste des variables est disponible dans le [fichier de définition des couleurs](https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss) du code source de _Material for MkDocs_.
222
+
223
+
Pour surcharger les couleurs principales, il suffit donc de les re-déclarer dans un fichier `.css`, de cette manière:
224
+
225
+
```css
226
+
:root {
227
+
--md-primary-fg-color: #394A59;
228
+
--md-accent-fg-color: #556567;
229
+
}
230
+
```
231
+
232
+
Le fichier `.css` doit être déposé où l'on souhaite. Ici, nous avons créé un répertoire `docs/stylesheets`:
233
+
234
+
```
235
+
.
236
+
├── docs
237
+
│ ├── assets
238
+
│ │ └── death-star.png
239
+
│ ├── index.md
240
+
│ └── stylesheets
241
+
│ └── galactic-empire.css
242
+
└── mkdocs.yml
243
+
```
244
+
245
+
Enfin, le fichier `.css` doit être référencé dans la configuration de notre site:
246
+
247
+
```yaml
248
+
site_name: Galactic Empire project
249
+
250
+
# configuration du thème
251
+
theme:
252
+
name: material
253
+
logo: assets/death-star.png
254
+
255
+
extra_css:
256
+
- stylesheets/galactic-empire.css
257
+
```
258
+
259
+
Et voici notre site avec le thème et sa customisation.
260
+
261
+
262
+
263
+
# L'ajout de contenu
264
+
L'ajout de contenu passe maintenant simplement par l'ajout de nouveaux fichiers _markdown_ dans le répertoire de documentation.
265
+
266
+
Voici un exemple de page de contenu supplémentaire:
267
+
268
+
```markdown
269
+
---
270
+
title: Organisation
271
+
author: Darth Vader
272
+
---
273
+
274
+
# Organisation de l'Empire Galactique
275
+
276
+
L'Empire Galactique est dirigé par l'Empereur Palpatine.
277
+
278
+
Son bras droit est le seigneur Vador.
279
+
280
+
Le Grand Moff Tarkin est le gouverneur régional de la Bordure Extérieur.
281
+
Il est à la tête du projet "Étoile de la mort", et son commandant.
282
+
```
283
+
284
+
L'en-tête du fichier est au format _Front Matter_, qui a été popularisé par [_Jekyll_](https://jekyllrb.com/docs/front-matter/).
285
+
286
+
Le rendu est le suivant:
287
+
288
+
289
+
290
+
Notez que :
291
+
292
+
* le titre de la page est celui du premier header Markdown `#`
293
+
* dans la navigation de gauche, le titre utilisé est celui du bloc de description de la page *Front Matter*.
294
+
* le nom de l'auteur apparaît dans les méta-données de la page générée:
295
+
296
+
```html
297
+
<head>
298
+
...
299
+
<meta name="author" content="Darth Vader">
300
+
...
301
+
</head
302
+
```
303
+
304
+
# Publication avec _Github Actions_ & _Github Pages_
305
+
306
+
Maintenant que notre site web est fonctionnel, nous allons le mettre à disposition sur le web avec _Github Pages_.
307
+
308
+
La création d'un repository _Github_ et les bases de _Github Actions_ sont en dehors du périmètre de cet article.
309
+
310
+
La construction du site web se fait avec la commande `mkdocs build`.
311
+
L'exécution de cette commande produit un nouveau répertoire `site` qui contient le site web généré:
312
+
313
+
```bash
314
+
$ mkdocs build
315
+
INFO - Cleaning site directory
316
+
INFO - Building documentation to directory: ekit3/mkdocs-website-sample/site
317
+
INFO - Documentation built in 0.16 seconds
318
+
```
319
+
Nous allons donc utiliser cette commmande pour générer notre site web à publier.
320
+
321
+
Voici un workflow _Github Actions_, qui installe le langage _Python_, _MkDocs_ et _Material for MkDocs_, et construit notre site:
322
+
323
+
```yaml
324
+
name: Build & Publish site
325
+
326
+
on:
327
+
push:
328
+
branches: [ "main" ]
329
+
pull_request:
330
+
branches: [ "main" ]
331
+
332
+
jobs:
333
+
build:
334
+
runs-on: ubuntu-latest
335
+
steps:
336
+
- uses: actions/checkout@v3
337
+
- name: Set up Python ${{ matrix.python-version }}
338
+
uses: actions/setup-python@v3
339
+
- name: Install dependencies
340
+
run: |
341
+
python -m pip install mkdocs
342
+
python -m pip install mkdocs-material
343
+
- name: Build site
344
+
run: |
345
+
mkdocs build
346
+
```
347
+
348
+
L'étape suivante consiste à publier le site construit sur _Github Pages_, ce qui se fait avec 2 actions dédiées.
349
+
350
+
L'action `upload-pages-artifact` permet de sélectionner un répertoire à envoyer à Github Pages, en l'occurence, notre répertoire `site`, qui contient notre site web.
351
+
352
+
```yaml
353
+
- name: Upload Pages Artifact
354
+
uses: actions/upload-pages-artifact@v1
355
+
with:
356
+
path: ./site
357
+
```
358
+
359
+
Cette action peut être ajoutée au job _build_ décrit plus haut.
360
+
361
+
Enfin, l'action `deploy-pages` permet d'exécuter le déploiement, nous l'ajoutons dans un job séparé:
362
+
363
+
```yaml
364
+
jobs:
365
+
build:
366
+
[...]
367
+
deploy:
368
+
needs: build
369
+
runs-on: ubuntu-latest
370
+
permissions:
371
+
pages: write
372
+
id-token: write
373
+
environment:
374
+
name: github-pages
375
+
url: ${{ steps.deployment.outputs.page_url }}
376
+
steps:
377
+
- name: Deploy to GitHub Pages
378
+
id: deployment
379
+
uses: actions/deploy-pages@v1
380
+
```
381
+
382
+
Le fichier final complet est disponible sur [le repository _Github_](https://github.com/ekit3/mkdocs-website-sample/blob/main/.github/workflows/publish.yml) contenant le code source de cet article.
383
+
384
+
À noter que le déploiement avec _Github Pages_ doit être activé dans le repository _Github_, et que le repository doit être public :
385
+
386
+
387
+
388
+
Une fois le fichier Github Actions publié, le workflow pourra s'exécuter, et publier le site web:
389
+
390
+
391
+
392
+
Le résultat final est visible [via ce lien](https://ekit3.github.io/mkdocs-website-sample/).
393
+
394
+
Le code source de cet article est disponible dans notre repository _Github_ [mkdocs-website-sample](https://github.com/ekit3/mkdocs-website-sample).
395
+
396
+
# Conclusion
397
+
398
+
En conclusion, nous avons vu les principes de documentation-as-code, et qu'il était très simple de publier une documentation sous la forme d'un site web.
399
+
Nous avons également vu comment utiliser le format _markdown_, couplé à l'outil _MkDocs_ et le thème _Material for MkDocs_ pour générer un site web et le personnaliser.
400
+
Enfin, nous avons vu comment utiliser _Github Actions_ et _Github Pages_ pour publier notre site de documentation sur internet.
401
+
402
+
_MkDocs_, couplé à un hébergement avec _Gitlab Pages_ ou _Github Pages_, permet de générer un site web en quelques étapes rapides.
403
+
Cela en fait l'outil idéal pour documenter un projet open-source ou interne.
404
+
405
+
# Liens
406
+
407
+
* [Documentation](https://www.mkdocs.org/) de _MkDocs_
408
+
* [Documentation](https://squidfunk.github.io/mkdocs-material/) de _Material for MkDocs_
409
+
* [La customisation](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/) de _Material for MkDocs_ (couleurs, fonts, icônes)
410
+
* L'icône _Death Star_ utilisée pour le site généré sur [pngrepo.com](https://www.pngrepo.com/svg/275952/death-star-star-wars)
411
+
* Les actions Github utilisées :
412
+
* [upload-pages-artifact](https://github.com/actions/upload-pages-artifact)
413
+
* [deploy-pages](https://github.com/actions/deploy-pages)
414
+
* Le [code source](https://github.com/ekit3/mkdocs-website-sample) associé à cet article
content/posts/2023-02-23-mkdocs-material/mkdocs-spring.png
content/posts/2023-02-23-mkdocs-material/mkdocs-spring.png
This is a binary file and will not be displayed.
content/posts/2023-05-25-anatomie-requete-http/client-server.png
content/posts/2023-05-25-anatomie-requete-http/client-server.png
This is a binary file and will not be displayed.
content/posts/2023-05-25-anatomie-requete-http/http-anatomy.jpg
content/posts/2023-05-25-anatomie-requete-http/http-anatomy.jpg
This is a binary file and will not be displayed.
+268
content/posts/2023-05-25-anatomie-requete-http/index.md
+268
content/posts/2023-05-25-anatomie-requete-http/index.md
···
1
+
---
2
+
created: "2023-05-25"
3
+
date: "2023-05-25T00:00:00Z"
4
+
language: fr
5
+
modified: "2023-07-01"
6
+
tags:
7
+
- Basics
8
+
title: Anatomie d'une requête HTTP
9
+
slug: anatomie-requete-http
10
+
---
11
+
12
+
# Anatomie d'une requête HTTP
13
+
14
+
15
+
16
+
HTTP, pour _Hypertext Transfer Protocol_, est le protocole principal pour les échanges internet. Il est utilisé aussi bien par le navigateur que vous utilisez pour lire cet article, que pour faire communiquer des applications.
17
+
Il s'appuie sur un éhange de requête et réponse, entre un client et un serveur, au format texte. L'avantage du format texte est qu'il est facile à implémenter dans tous les langages de programmation.
18
+
Le protocole HTTP est spécifié par la [RFC 2616](https://www.rfc-editor.org/rfc/rfc2616), protocole dont la toute première version d'HTTP date de 1990.
19
+
20
+
Cet article traite de la version 1.1 du protocole, qui a été normalisée en 1997. Une version 2.0 a été normalisée en 2015, et étend la version 1.1 avec d'autres capacités. Les bases de la version 1.1 ne sont donc pas obsolètes !
21
+
22
+
23
+
24
+
Dans cet article, nous allons étudier la structure d'une requête et d'une réponse HTTP.
25
+
26
+
## La structure d'une requête
27
+
28
+
Une requête est structurée en 3 parties :
29
+
30
+
* la ligne de requête, obligatoire, en première ligne
31
+
* les entêtes optionnels
32
+
* le corps de requête, lui aussi optionnel
33
+
34
+
```
35
+
REQUEST-LINE
36
+
[HEADERS]
37
+
38
+
[BODY]
39
+
```
40
+
41
+
Exemple de requête HTTP _GET_ sans corps de requête :
42
+
43
+
```
44
+
GET /articles/http-anatomy?version=1#headers HTTP/1.1
45
+
Host: ekite.tech
46
+
Accept: text/plain
47
+
Accept-Charset: utf-8
48
+
Accept-Encoding: gzip
49
+
Accept-Language: fr-fr
50
+
```
51
+
52
+
Exemple comportant un corps de requête :
53
+
54
+
```
55
+
POST /articles/ HTTP/1.1
56
+
Host: ekite.tech
57
+
Content-Type: application/json
58
+
Content-Length: 31
59
+
Authorization: Basic UmljayBBc3RsZXk6TmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAK
60
+
61
+
{"title":"mon nouvel article"}
62
+
```
63
+
64
+
### La _Request Line_
65
+
66
+
Les _HEADERS_ et _BODY_ sont facultatifs.
67
+
68
+
La _REQUEST-LINE_ est définie de cette manière :
69
+
70
+
```
71
+
METHOD REQUEST-URI HTTP-VERSION
72
+
```
73
+
74
+
_METHOD_ est le verbe HTTP. Il peut être `GET`, `POST`, `PUT`, `DELETE`, qui sont les verbes HTTP les plus courants.
75
+
La RFC 2616 définit aussi des méthodes supplémentaires, comme `HEAD`, `OPTIONS`, `TRACE`, `CONNECT`.
76
+
77
+
_REQUEST-URI_ est la ressource à appeler. Elle peut être une URI absolue, comme `https://ekite.tech/articles/http-anatomy`, ou une URI relative, comme `/articles/http-anatomy`. En pratique, ce sont plutôt des URI relatives qui sont utilisées, en combinaison avec un _Header_ `Host`.
78
+
79
+
Le champ `HTTP-VERSION` vaudra `HTTP/1.1`.
80
+
81
+
Une requête HTTP minimale est :
82
+
83
+
```
84
+
GET /articles/http-anatomy HTTP/1.1
85
+
```
86
+
87
+
### _URL_ et _URI_
88
+
89
+
Une _URI_, pour _Uniform Resource Identifier_, définit une ressource internet. Cette ressource peut être une page Web, un document au format PDF, ou encore une vidéo.
90
+
91
+
Une _URL_, pour _Uniform Resource Locator_, est une _URI_ particulière, qui contient les informations réseau pour accéder à une ressource.
92
+
Les _URI_ sont définies par un format texte composé de caractères _ASCII_.
93
+
94
+
La [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986) spécifie les formats des _URI_.
95
+
96
+
La structure d'une _URI_ absolue est :
97
+
98
+
```
99
+
SCHEME://HOST/PATH[?QUERY][#FRAGMENT]
100
+
```
101
+
Le _SCHEME_ est souvent associé au protocole, _http_, _https_, ou encore _file_ quand des fichiers locaux sont désignés.
102
+
Le _HOST_ est le nom du serveur hébergeant la ressource.
103
+
Le _PATH_ identifie le chemin vers la ressource.
104
+
La _QUERY_, aussi souvent appelé _Query Strings_, définit des paramètres supplémentaires que la ressource peut traiter, sous la forme `name=value`.
105
+
Le _FRAGMENT_ définit la partie de la ressource consultée.
106
+
_QUERY_ et _FRAGMENT_ sont optionnels.
107
+
108
+
Une _URI_ simple pour notre article est :
109
+
110
+
```
111
+
https://ekite.tech/articles/http-anatomy
112
+
\___/ \________/ \___________________/
113
+
| | |
114
+
scheme host path
115
+
```
116
+
117
+
Une _URI_ comportant des éléments supplémentaires :
118
+
119
+
```
120
+
https://ekite.tech/articles/http-anatomy?version=1#headers
121
+
\___/ \________/ \___________________/ \_______/ \_____/
122
+
| | | | |
123
+
scheme host path query fragment
124
+
```
125
+
126
+
Une _URI_ peut également être relative, et ne comporter qu'une partie du _PATH_.
127
+
Par exemple :
128
+
129
+
```
130
+
/http-anatomy?version=1#headers
131
+
```
132
+
133
+
### Les _Headers_ de requête
134
+
135
+
Les _Headers_ définissent des informations supplémentaires à propos de la requête, comme le format de données attendu en réponse, ou des informations concernant les données actuellement en cache côté client.
136
+
137
+
Cette structure définit les _Headers_ :
138
+
139
+
```
140
+
NAME: VALUE
141
+
```
142
+
143
+
La [RFC 2616](https://www.rfc-editor.org/rfc/rfc2616#page-38), définit des _Headers_ standards, mais les applications peuvent également définir leurs propres _Headers_.
144
+
Les principaux _Headers_ standards sont `Accept`, `Accept-Charset`, `Accept-Encoding` et `Accept-Language` pour la négociation de contenu.
145
+
Cette RFC définit aussi le _Header_ `Authorization` pour l'authentification des clients. Le _Header_ `Host` précise l'hôte auquel la requête est envoyée s'il n'est pas précisé dans l'URI de la requête.
146
+
147
+
Une requête HTTP comportant des _Headers_ est :
148
+
149
+
```
150
+
GET /articles/http-anatomy HTTP/1.1
151
+
Host: ekite.tech
152
+
Accept: text/plain
153
+
Accept-Charset: utf-8
154
+
Accept-Encoding: gzip
155
+
Accept-Language: fr-fr
156
+
```
157
+
158
+
### Le _Body_
159
+
160
+
Lorsqu'une requête comporte un corps, les _Headers_ `Content-Type` et `Content-Length` doivent être précisés et définir son type et sa taille en octets.
161
+
Un saut de ligne doit également séparer les _Headers_ du _Body_.
162
+
163
+
Exemple de requête avec un _Body_ au format `JSON` :
164
+
165
+
```
166
+
POST /articles/ HTTP/1.1
167
+
Host: ekite.tech
168
+
Content-Type: application/json
169
+
Content-Length: 31
170
+
171
+
{"title":"mon nouvel article"}
172
+
```
173
+
## La structure d'une réponse
174
+
175
+
Les réponses HTTP ont un format assez similaire à celui des requêtes.
176
+
```
177
+
STATUS-LINE
178
+
[HEADERS]
179
+
180
+
[BODY]
181
+
```
182
+
183
+
### La _Status Line_
184
+
185
+
La _Status Line_ représente la réponse codifiée du serveur à la requête.
186
+
187
+
_STATUS-LINE_ est définie de cette manière :
188
+
189
+
```
190
+
HTTP-VERSION CODE PHRASE
191
+
```
192
+
193
+
Le premier élément de la réponse est la version HTTP `HTTP/1.1`
194
+
195
+
Les codes utilisés sont représentés par 3 chiffres.
196
+
197
+
* Les codes `1xx` sont informationnels et rarement utilisés en pratique.
198
+
* Les codes `2xx` représentent une opération en succès.
199
+
* Les codes `3xx` indiquent une redirection.
200
+
* Les codes `4xx` indiquent une erreur du client (requête mal formée, ressource non existante).
201
+
* Les codes `5xx` représentent une erreur du serveur dans le traitement de la requête.
202
+
203
+
Les codes sont suivis d'une _Phrase_ descriptive.
204
+
205
+
Les codes les plus courants et des phrases associées sont définis dans la [RFC 2616](https://www.rfc-editor.org/rfc/rfc2616#section-6.1.1).
206
+
207
+
Exemple de réponse en erreur :
208
+
209
+
```
210
+
HTTP/1.1 404 Not Found
211
+
```
212
+
213
+
Exemple de réponse en succès :
214
+
215
+
```
216
+
HTTP/1.1 200 OK
217
+
```
218
+
219
+
### Les _Headers_ de réponse
220
+
221
+
Au même titre qu'une requête, une réponse peut contenir des _Headers_. Ils définissent le type et la taille du _Body_ de réponse, ou des paramètres pour indiquer au client que la réponse peut être stockée en cache. D'autres _Headers_ définissent la ressource à appeler en cas de redirection (code `3xx`).
222
+
223
+
Les _Headers_ de réponse sont définis de la même manière que les requêtes :
224
+
225
+
```
226
+
NAME: VALUE
227
+
```
228
+
229
+
Exemple de réponse HTTP comportant un _Header_ `Location` pour une redirection vers une page `index.html` :
230
+
231
+
```
232
+
HTTP/1.1 301 Moved Permanently
233
+
Location: index.html
234
+
```
235
+
236
+
### Le _Body_ de réponse
237
+
238
+
Le _Body_ est définit de la même manière que les requêtes, et impose également les mêmes règle de présence des _Headers_ `Content-Type` et `Content-Length`.
239
+
240
+
Exemple de réponse en succès comportant le contenu de notre article :
241
+
242
+
```
243
+
HTTP/1.1 200 OK
244
+
Content-Type: application/json
245
+
Content-Length: 31
246
+
247
+
{"title":"mon nouvel article"}
248
+
```
249
+
250
+
Exemple d'une erreur serveur, avec une page HTML la représentant :
251
+
252
+
```
253
+
HTTP/1.1 500 Internal Server Error
254
+
Content-Type: text/html
255
+
Content-Length: 56
256
+
257
+
<html><body><h1>Erreur de traitement</h1></body></html>
258
+
```
259
+
## Conclusion
260
+
261
+
Le protocole HTTP décrit un format texte, sous la forme de requête et réponse, facile à implémenter dans tous les langages de programmation.
262
+
Sa simplicité et son expressivité sont la clé de son succès depuis les années 90, jusqu'aux nouvelles versions qui continuent de s'appuyer sur le même format.
263
+
264
+
## Références
265
+
266
+
* [RFC 2616](https://www.rfc-editor.org/rfc/rfc2616) : Hypertext Transfer Protocol -- HTTP/1.1
267
+
* [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986) : Uniform Resource Identifier (URI) : Generic Syntax
268
+
* [RFC 7540](https://www.rfc-editor.org/rfc/rfc7540) : Hypertext Transfer Protocol Version 2 (HTTP/2)
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/clever-addon-create.png
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/clever-addon-create.png
This is a binary file and will not be displayed.
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/clever-env.png
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/clever-env.png
This is a binary file and will not be displayed.
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/clever-open-starting.png
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/clever-open-starting.png
This is a binary file and will not be displayed.
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/clever-open.png
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/clever-open.png
This is a binary file and will not be displayed.
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/clever-scale.png
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/clever-scale.png
This is a binary file and will not be displayed.
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/clever-service-link-addon.png
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/clever-service-link-addon.png
This is a binary file and will not be displayed.
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/create-sonarqube.png
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/create-sonarqube.png
This is a binary file and will not be displayed.
+10
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/diagrams.drawio
+10
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/diagrams.drawio
···
1
+
<mxfile host="Electron" modified="2023-11-02T14:28:07.869Z" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/21.3.7 Chrome/112.0.5615.204 Electron/24.5.0 Safari/537.36" etag="qV1sjR1Wv6CTG9wR4SCB" version="21.3.7" type="device">
2
+
<diagram name="Page-1" id="ukJr07_c3Hn4pDndtCBV">
3
+
<mxGraphModel dx="144" dy="535" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
4
+
<root>
5
+
<mxCell id="0" />
6
+
<mxCell id="1" parent="0" />
7
+
</root>
8
+
</mxGraphModel>
9
+
</diagram>
10
+
</mxfile>
+421
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/index.md
+421
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/index.md
···
1
+
---
2
+
created: "2023-11-02"
3
+
date: "2023-11-02T00:00:00Z"
4
+
language: fr
5
+
modified: "2023-11-09"
6
+
slug: "deploy-sonarqube-on-clever-cloud"
7
+
tags:
8
+
- Clever Cloud
9
+
- SonarQube
10
+
- Tutorial
11
+
title: Déployer une instance de SonarQube sur Clever Cloud
12
+
---
13
+
14
+
Dans cet article, nous allons voir comment déployer _SonarQube_ sur _Clever Cloud_ en deux temps. Le premier consistera en un déploiement très simple, qui est équivalent à une installation locale. Dans un second temps, nous utiliserons une base de données _PostgreSQL_ externalisée pour assurer la persistance des données.
15
+
16
+
Cet article suppose que vous avez déjà un compte actif sur _Clever Cloud_, et que votre CLI est installé et configuré.
17
+
L'installation du CLI est décrite dans [la documentation de _Clever Cloud_](https://www.clever-cloud.com/doc/getting-started/cli/).
18
+
19
+
# Le déploiement simple
20
+
21
+
La [documentation _SonarQube_](https://docs.sonarsource.com/sonarqube/latest/try-out-sonarqube/#installing-a-local-instance-of-sonarqube) propose de déployer une instance locale en utilisant la commande suivante :
22
+
23
+
```bash
24
+
$ docker container run -d \
25
+
--name sonarqube \
26
+
-e SONAR_ES_BOOTSTRAP_CHECKS_DISABLE=true \
27
+
-p 9000:9000 \
28
+
sonarqube:latest
29
+
```
30
+
31
+
_SonarQube_ fournit une [image _Docker_](https://hub.docker.com/_/sonarqube) prête à l'emploi que nous allons utiliser. Nous utiliserons le tag _Docker_ `10-community` pour nous assurer de rester sur la version majeure `10`.
32
+
33
+
La variable d'environnement `SONAR_ES_BOOTSTRAP_CHECKS_DISABLE` permet à _SonarQube_ d'ignorer les contrôles de démarrage du processus _Elasticsearch_ embarqué dans son serveur.
34
+
35
+
_SonarQube_ écoute par défaut sur le port `9000`.
36
+
37
+
Ces informations nous seront utiles par la suite !
38
+
39
+
## Création de l'application dans _Clever Cloud_
40
+
41
+
Nous allons tout d'abord créer un _repository_ Git qui hébergera notre code (et nos scripts si besoin), et qui sera utilisé par le CLI `clever` pour nos déploiements.
42
+
43
+
```bash
44
+
$ git init
45
+
```
46
+
47
+
Créer une application dans _Clever Cloud_ consiste en une ligne de commande :
48
+
49
+
```bash
50
+
$ clever create \
51
+
--type docker \
52
+
sonarqube-app
53
+
54
+
Your application has been successfully created!
55
+
```
56
+
57
+
Si vous déployez votre code dans une organisation, ajoutez le paramètre `--org` à votre ligne de commande :
58
+
59
+
```bash
60
+
$ clever create \
61
+
--type docker \
62
+
--org orga_a4fdf186-bcaa-4d9f-9249-b09d57bf4beb \
63
+
sonarqube-app
64
+
65
+
Your application has been successfully created!
66
+
```
67
+
68
+
L'application ainsi créée apparaît dans la console _Clever Cloud_ :
69
+
70
+
71
+
72
+
La commande `clever create` génère un fichier `.clever.json` dans notre répertoire courant qui contient les informations de notre application, en particulier son identifiant.
73
+
74
+
```json
75
+
{
76
+
"apps": [
77
+
{
78
+
"app_id": "app_765c79a9-e316-460b-a75a-054738784efd",
79
+
"org_id": "orga_a4fdf186-bcaa-4d9f-9249-b09d57bf4beb",
80
+
"deploy_url": "https://push-n3-par-clevercloud-customers.services.clever-cloud.com/app_765c79a9-e316-460b-a75a-054738784efd.git",
81
+
"name": "sonarqube-app",
82
+
"alias": "sonarqube-app"
83
+
}
84
+
]
85
+
}
86
+
```
87
+
88
+
Ce fichier peut être archivé dans _repository_ Git :
89
+
90
+
```bash
91
+
$ git add .clever.json && git commit -m "👷 : add .clever.json"
92
+
```
93
+
94
+
## Dimensionnement de l'instance
95
+
96
+
_SonarQube_ a besoin d'au moins 2 Go de RAM pour fonctionner ainsi que 1 Go de RAM disponible sur l'OS, nous allons donc utiliser une instance `M` qui disposera de 4 Go de RAM au total.
97
+
98
+
La modification du type d'instance se fait également en une ligne de commande :
99
+
100
+
```bash
101
+
$ clever scale --flavor M
102
+
103
+
App rescaled successfuly
104
+
```
105
+
106
+
Une fois la commande exécutée, la modification est visible dans l'onglet _Scalability_ de l'application :
107
+
108
+
109
+
110
+
## Configuration des variables d'environnement
111
+
112
+
_Clever Cloud_ requiert que les applications déployées écoutent sur le port `8080`.
113
+
114
+
Nous avons également vu précédemment que par défaut _SonarQube_ écoute sur le port `9000`.
115
+
116
+
La configuration de notre instance _SonarQube_ peut se faire avec des variables d'environnement ([doc](https://docs.sonarsource.com/sonarqube/latest/setup-and-upgrade/configure-and-operate-a-server/environment-variables/)).
117
+
118
+
Nous allons donc configurer la variable d'environnement `SONAR_WEB_PORT` avec la valeur `8080`.
119
+
Nous allons également en profiter pour configurer la variable `SONAR_ES_BOOTSTRAP_CHECKS_DISABLE` qui était précisée dans la ligne de lancement `docker` issue de la documentation _SonarQube_.
120
+
Pour configurer ces variables, nous utilisons la commande `clever env set` :
121
+
122
+
```bash
123
+
$ clever env set SONAR_WEB_PORT 8080
124
+
125
+
Your environment variable has been successfully saved
126
+
127
+
$ clever env set SONAR_ES_BOOTSTRAP_CHECKS_DISABLE true
128
+
129
+
Your environment variable has been successfully saved
130
+
```
131
+
132
+
Les variables d'environnement configurées sont visibles sur la console _Clever Cloud_, dans l'onglet _Environment Variables_ :
133
+
134
+
135
+
136
+
## Déploiement de l'image _Docker_
137
+
138
+
Une fois notre application créée et configurée, il nous faut la déployer.
139
+
140
+
Nous créons un simple `Dockerfile` dans notre _repository_ :
141
+
142
+
```docker
143
+
FROM sonarqube:10-community
144
+
```
145
+
146
+
Puis nous déployons l'application en créant un _commit_, et en faisant un `clever deploy` :
147
+
148
+
```bash
149
+
$ git add Dockerfile && git commit -m "🐋 : init Dockerfile"
150
+
$ clever deploy
151
+
152
+
App is brand new, no commits on remote yet
153
+
New local commit to push is 371a4224151b9e9bb8888a403a9626c88a0b1312 (from refs/heads/main)
154
+
Pushing source code to Clever Cloud…
155
+
Your source code has been pushed to Clever Cloud.
156
+
Waiting for deployment to start…
157
+
Deployment started (deployment_a13a283f-5e63-45da-b675-666603212a18)
158
+
Waiting for application logs…
159
+
160
+
[...]
161
+
162
+
2023-10-31T09:16:39.007Z: 2023.10.31 09:16:37 INFO ce[][o.s.s.p.ServerFileSystemImpl] SonarQube home: /opt/sonarqube
163
+
2023-10-31T09:16:39.007Z: 2023.10.31 09:16:37 INFO ce[][o.s.c.c.CePluginRepository] Load plugins
164
+
2023-10-31T09:16:39.007Z: 2023.10.31 09:16:38 INFO ce[][o.s.c.c.ComputeEngineContainerImpl] Running Community edition
165
+
2023-10-31T09:16:39.007Z: 2023.10.31 09:16:38 INFO ce[][o.s.ce.app.CeServer] Compute Engine is started
166
+
2023-10-31T09:16:39.007Z: 2023.10.31 09:16:38 INFO app[][o.s.a.SchedulerImpl] Process[ce] is up
167
+
2023-10-31T09:16:39.007Z: 2023.10.31 09:16:38 INFO app[][o.s.a.SchedulerImpl] SonarQube is operational
168
+
169
+
Deployment successful
170
+
```
171
+
172
+
Le message `Deployment successful` indique que notre instance est bien démarrée !
173
+
174
+
Nous pouvons maintenant ouvrir notre instance de _SonarQube_ avec la commande :
175
+
176
+
```bash
177
+
$ clever open
178
+
179
+
Opening the application in your browser
180
+
```
181
+
182
+
La page de démarrage de _SonarQube_ s'ouvre :
183
+
184
+
185
+
186
+
Quelques instants plus tard, une fois que l'instance _SonarQube_ est complètement démarrée, la page de _login_ s'affiche :
187
+
188
+
189
+
190
+
Nous nous loguons avec les identifiants par défaut `admin` / `admin`, puis nous changeons le mot de passe du compte `admin`.
191
+
Une fois ces étapes effectuées, la page d'accueil de notre instance _SonarQube_ s'affiche :
192
+
193
+
194
+
195
+
Le message affiché en bas de page nous indique que notre déploiement est, certes, fonctionnel, mais non adapté à un usage en production. Nous allons donc maintenant utiliser une base de données externalisée.
196
+
197
+
# Externaliser la base de données
198
+
199
+
Une base de données externalisée va permettre de rendre nos données persistantes.
200
+
_SonarQube_ est compatible avec les bases de données _PostgreSQL_, _SQL Server_ et _Oracle_.
201
+
202
+
_Clever Cloud_ propose diverses bases de données dans la section _Add-On_ de la console, ou _via_ les commandes CLI `clever addon`. _PostgreSQL_ fait partie des bases de données supportées, ce qui est parfait pour notre instance de _SonarQube_ !
203
+
204
+
## Créer l'_addon_ _PostgreSQL_
205
+
206
+
Pour lister les _addons_ disponibles, nous utilisons la commande `clever addon providers`, ce qui va nous permettre de récupérer l'identifiant de l'_addon_ _PostgreSQL_ :
207
+
208
+
```bash
209
+
$ clever addon providers
210
+
211
+
addon-matomo Matomo Analytics Matomo is a web analytics application as a service.
212
+
addon-pulsar Pulsar Namespace with all Pulsar possibilities
213
+
cellar-addon Cellar S3 storage S3-like online file storage web service
214
+
config-provider Configuration provider Expose configuration to your applications (via environment variables)
215
+
es-addon Elastic Stack Elasticsearch with Kibana and APM server as options
216
+
fs-bucket FS Buckets Persistent file system for your application
217
+
jenkins Jenkins Automation & CI with Clever Cloud runners
218
+
mailpace MailPace - Transactional Email Fast & Reliable Transactional Email
219
+
mongodb-addon MongoDB A noSQL document-oriented database
220
+
mysql-addon MySQL An open source relational database management system
221
+
postgresql-addon PostgreSQL A powerful, open source object-relational database system
222
+
redis-addon Redis Redis by Clever Cloud is an in-memory key-value data store, powered by Clever Cloud
223
+
```
224
+
225
+
L'_addon_ que nous allons utiliser est donc nommé `postgresql-addon`.
226
+
227
+
Nous listons ensuite les différentes versions de l'_addon_ _PostgreSQL_, et ses plans de facturation :
228
+
229
+
```bash
230
+
$ clever addon providers show postgresql-addon
231
+
232
+
PostgreSQL: A powerful, open source object-relational database system
233
+
234
+
Available regions: jed, mtl, par, rbx, rbxhds, scw, sgp, syd, wsw
235
+
236
+
Available plans
237
+
Plan dev
238
+
Backups: Daily - 7 Retained
239
+
Logs: No
240
+
Max DB size: 256 MB
241
+
Max connection limit: 5
242
+
Memory: Shared
243
+
Metrics: No
244
+
Migration Tool: Yes
245
+
Type: Shared
246
+
vCPUS: Shared
247
+
Plan xxs_sml
248
+
Backups: Daily - 7 Retained
249
+
Logs: Yes
250
+
Max DB size: 1 GB
251
+
Max connection limit: 45
252
+
Memory: 512 MB
253
+
Metrics: Yes
254
+
Migration Tool: Yes
255
+
Type: Dedicated
256
+
vCPUS: 1
257
+
Available versions: 10, 11, 12, 13, 14 (default), 15
258
+
Options for version 10:
259
+
encryption: default=false
260
+
Options for version 11:
261
+
encryption: default=false
262
+
Options for version 12:
263
+
encryption: default=false
264
+
Options for version 13:
265
+
encryption: default=false
266
+
Options for version 14:
267
+
encryption: default=false
268
+
Options for version 15:
269
+
encryption: default=false
270
+
[...]
271
+
```
272
+
273
+
Le plan _xxs_sml_ est le plus petit plan avec des ressources dédiées. 1 CPU, 512 Mo de RAM et 1 Go de stockage sont suffisants pour démarrer, sachant que le plan pourra être modifié à tout instant si besoin.
274
+
275
+
Nous pouvons maintenant créer notre _addon_ avec la commande `clever addon create` :
276
+
277
+
```bash
278
+
$ clever addon create \
279
+
--plan xxs_sml \
280
+
--org orga_a4fdf186-bcaa-4d9f-9249-b09d57bf4beb \
281
+
postgresql-addon \
282
+
sonarqube-db
283
+
284
+
Addon sonarqube-db (id: addon_2cc8bfaf-8800-43ef-87a0-4f162be73f2e) successfully created
285
+
```
286
+
287
+
Une fois la commande exécutée, notre base de données apparaît dans la console :
288
+
289
+
290
+
291
+
Nous pouvons ensuite lier notre base de données avec notre application. Ce lien va permettre de partager des variables d'environnement entre la base de données et notre application :
292
+
293
+
```bash
294
+
$ clever service link-addon sonarqube-db
295
+
296
+
Addon sonarqube-db successfully linked
297
+
```
298
+
299
+
Une fois l'application liée à la base de données, les variables d'environnement de la base de données apparaissent dans l'onglet _Environment Variables_ de notre application :
300
+
301
+
302
+
303
+
## Reconfigurer notre instance _SonarQube_
304
+
305
+
Notre addon _Clever Cloud_ expose des variables d'environnement _POSTGRESQL_ADDON_ qui vont nous servir pour configurer notre instance de _SonarQube_.
306
+
Cependant, _SonarQube_ se configure avec les variables d'environnement suivantes :
307
+
308
+
```
309
+
SONAR_JDBC_USERNAME
310
+
SONAR_JDBC_PASSWORD
311
+
SONAR_JDBC_URL
312
+
```
313
+
314
+
L'URL JDBC suit un schéma précis, qui est `jdbc:<driver>://<host>:<port>/<db>`. _Clever Cloud_ expose une variable d'environnement pour les `host`, `port` et `db`, donc nous pouvons calculer notre variable `SONAR_JDBC_URL` en utilisant ces variables. Voici donc la liste des variables fournies par l'_addon_ que nous allons utiliser :
315
+
316
+
```env
317
+
# pour SONAR_JDBC_USERNAME
318
+
POSTGRESQL_ADDON_USER
319
+
# pour SONAR_JDBC_PASSWORD
320
+
POSTGRESQL_ADDON_PASSWORD
321
+
# pour SONAR_JDBC_URL
322
+
POSTGRESQL_ADDON_HOST
323
+
POSTGRESQL_ADDON_PORT
324
+
POSTGRESQL_ADDON_DB
325
+
```
326
+
327
+
### Copie des variables d'environnement
328
+
329
+
{% include admonition.html type="note" title="Update 2023-11-09" body="Suite aux échanges avec le support de _Clever Cloud_, ils m'ont proposé un autre moyen de positionner les variables d'environnement. Cet autre moyen est décrit dans la section suivante. Cette section est donc obsolète. Le code source sur Github a également été mis à jour." %}
330
+
331
+
Malheureusement, ni _SonarQube_ ni _Clever Cloud_ ne supporte de renommer ses variables d'environnement, ou de les interpoler.
332
+
Nous devons donc créer les variables d'environnement _SONAR_ avec des valeurs en dur, issues des variables d'environnement _POSTGRESQL_ADDON_.
333
+
334
+
Notez que cette approche implique que notre application doit être reconfigurée en cas de changement de variables d'environnement, ce qui n'est pas idéal.
335
+
336
+
Nous allons donc dans un premier temps récupérer les variables d'environnement de notre application, et les stocker dans un fichier avec la commande `clever env`. Nous chargeons ensuite le fichier créé avec la commande `source` pour avoir les variables d'environnement disponibles dans notre _shell_ :
337
+
338
+
```bash
339
+
$ clever env --add-export > clever-env-vars.sh
340
+
341
+
$ source clever-env-vars.sh
342
+
343
+
$ echo $POSTGRESQL_ADDON_USER
344
+
u6qkhfs3dduj1rrlra99
345
+
```
346
+
347
+
Les commandes suivantes permettent de configurer la connexion à notre base de données avec les variables d'environnement _SONAR_ :
348
+
349
+
```bash
350
+
$ clever env set SONAR_JDBC_USERNAME $POSTGRESQL_ADDON_USER
351
+
$ clever env set SONAR_JDBC_PASSWORD $POSTGRESQL_ADDON_PASSWORD
352
+
$ clever env set SONAR_JDBC_URL "jdbc:postgresql://${POSTGRESQL_ADDON_HOST}:${POSTGRESQL_ADDON_PORT}/${POSTGRESQL_ADDON_DB}"
353
+
```
354
+
355
+
Pour déployer notre instance avec sa nouvelle configuration, il faut simplement redémarrer l'application avec la commande `clever restart` :
356
+
357
+
```bash
358
+
$ clever restart
359
+
```
360
+
361
+
Une fois _SonarQube_ redémarré, il nous demande à nouveau de changer le mot de passe de l'utilisateur `admin` puisque le précédent mot de passe a été stocké dans la base de données embarquée, et donc perdu à la migration.
362
+
363
+
### Script de démarrage customisé
364
+
365
+
{% include admonition.html type="note" title="Update 2023-11-09" body="Cette section a été ajoutée suite aux échanges avec le support de _Clever Cloud_" %}
366
+
367
+
Malheureusement, ni _SonarQube_ ni _Clever Cloud_ ne supporte de renommer ses variables d'environnement, ou de les interpoler.
368
+
Nous allons donc ajouter un script dans notre image _Docker_ pour retravailler nos variables d'enviroonement.
369
+
370
+
L'image _Docker_ de _SonarQube_ utilise pour `ENTRYPOINT` un script nommé `/opt/sonarqube/docker/entrypoint.sh`.
371
+
372
+
Notre script que nous appelons `clever-entrypoint.sh` va donc positionner les variables d'environnement nécessaires au démarrage de _SonarQube_ et rappeler le script de _SonarQube_ :
373
+
374
+
```bash
375
+
#!/bin/sh
376
+
377
+
export SONAR_JDBC_USERNAME=$POSTGRESQL_ADDON_USER
378
+
export SONAR_JDBC_PASSWORD=$POSTGRESQL_ADDON_PASSWORD
379
+
export SONAR_JDBC_URL="jdbc:postgresql://${POSTGRESQL_ADDON_HOST}:${POSTGRESQL_ADDON_PORT}/${POSTGRESQL_ADDON_DB}"
380
+
381
+
exec /opt/sonarqube/docker/entrypoint.sh
382
+
```
383
+
384
+
Nous ajoutons ce script dans le répertoire `/opt/sonarqube/docker` au niveau de notre `Dockerfile`, nous modifions l'`ENTRYPOINT` de notre image pour pointer vers notre script :
385
+
386
+
```docker
387
+
FROM sonarqube:10-community
388
+
389
+
ADD clever-entrypoint.sh /opt/sonarqube/docker/
390
+
391
+
ENTRYPOINT ["/opt/sonarqube/docker/clever-entrypoint.sh"]
392
+
```
393
+
394
+
Un `git commit` suivi d'un `clever deploy` nous permettent de mettre à jour notre application avec le script embarqué et de pointer vers notre base de données.
395
+
396
+
```bash
397
+
$ git add Dockerfile clever-entrypoint.sh
398
+
399
+
$ git commit -m "🔧 : add custom entrypoint for Clever Cloud"
400
+
401
+
$ clever deploy
402
+
```
403
+
404
+
Une fois _SonarQube_ redémarré, il nous demande à nouveau de changer le mot de passe de l'utilisateur `admin` puisque le précédent mot de passe a été stocké dans la base de données embarquée, et donc perdu à la migration.
405
+
406
+
# Conclusion
407
+
408
+
Il est relativement facile de déployer _SonarQube_ sur _Clever Cloud_. L'image _Docker_ fournie par _SonarQube_ nous permet de démarrer rapidement une instance.
409
+
410
+
Les bases de données proposées par _Clever Cloud_ sont également pratiques pour démarrer rapidement. Cependant, le manque de souplesse de _SonarQube_ dans sa configuration et l'impossibilité de renommer des variables d'environnement sur _Clever Cloud_ rendent la dernière étape de la configuration peu pratique et peu robuste. Un peu de scripting permet de rendre cette étape plus propre.
411
+
412
+
Pour exécuter l'infrastructure proposée dans cet article, il vous en coûtera environ 81,25 €/mois :
413
+
414
+
| article | prix/mois |
415
+
| ---------------------------- | ----------- |
416
+
| PostgreSQL - XXS Small Space | 5,25 € |
417
+
| Node Docker - Plan M | 76 € |
418
+
419
+
À titre de comparaison, un container de 4 CPU et 4 Go de RAM sur GCP Cloud Run coûte 174 €/mois, avec l'option _CPU always allocated_ requise par _SonarQube_ pour exécuter ses traitements en arrière-plan. Cela fait de _Clever Cloud_ un excellent choix économique !
420
+
421
+
Les scripts de cet article sont disponibles sur [Github](https://github.com/juwit/sonarqube-clever-cloud).
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/sonarqube-admin-pass.png
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/sonarqube-admin-pass.png
This is a binary file and will not be displayed.
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/sonarqube-empty.png
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/sonarqube-empty.png
This is a binary file and will not be displayed.
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/sonarqube-login.png
content/posts/2023-11-02-deploy-sonarqube-on-clever-cloud/sonarqube-login.png
This is a binary file and will not be displayed.
+36
hugo.toml
+36
hugo.toml
···
1
+
baseURL = 'https://codeka.io/'
2
+
languageCode = 'en-us'
3
+
title = 'Julien Wittouck'
4
+
theme = "poison"
5
+
6
+
[permalinks]
7
+
[permalinks.page]
8
+
posts = '/:year/:month/:day/:slug'
9
+
10
+
[params]
11
+
brand = "Julien Wittouck"
12
+
description = "freelance solution & software architect 🏗 - containers 🐋 & linux 🐧 ❤️ - teacher & trainer 🎓 @ univ-lille.fr - speaker 🎙"
13
+
front_page_content = ["posts", "projects"]
14
+
15
+
16
+
menu = [
17
+
{Name = "Posts", URL = "/posts/", Pre = "Recent", HasChildren = true, Limit = 5},
18
+
{Name = "Talks", URL = "/talks/"},
19
+
{Name = "Projects", URL = "/projects/"}
20
+
]
21
+
22
+
email_url = "mailto://julien.wittouck@gmail.com"
23
+
github_url = "https://github.com/juwit"
24
+
linkedin_url = "https://www.linkedin.com/in/julien-wittouck"
25
+
twitter_url = "https://www.twitter.com/CodeKaio"
26
+
27
+
28
+
# Hex colors for your sidebar.
29
+
moon_sun_background_color = "#515151" # default is #515151
30
+
moon_sun_color = "#FFF" # default is #FFF
31
+
sidebar_a_color = "#FFF" # default is #FFF
32
+
sidebar_bg_color = "#5ea4e2" # default is #202020
33
+
sidebar_h1_color = "#FFF" # default is #FFF
34
+
sidebar_img_border_color = "#515151" # default is #515151
35
+
sidebar_p_color = "#111111" # default is #909090
36
+
sidebar_socials_color = "#FFF" # default is #FFF