Dev zone/Create devserver access/fr: Difference between revisions

From Nasqueron Agora
← Older edit
Ptdradmin (talk | contribs)
17 edits
Ptdradmin (talk | contribs)
17 edits
No edit summary
Ptdradmin (talk | contribs)
17 edits
No edit summary
 
Line 3: Line 3:
= Guide complet : Configuration de l'accès devserver avec Git et Arcanist =
= Guide complet : Configuration de l'accès devserver avec Git et Arcanist =


Ce guide explique comment configurer votre environnement de développement pour contribuer au projet Operations.
Ce guide explique comment configurer votre environnement de développement Windows (via WSL) pour contribuer au projet Operations et obtenir vos accès aux serveurs de développement (Devservers).


== 1. Création du dossier de travail ==
== 1. Prérequis et Environnement ==


Créez un dossier sur votre PC Windows pour organiser tous les fichiers du projet :
Avant de commencer, assurez-vous de disposer des outils suivants sur votre machine Windows :
* '''WSL (Windows Subsystem for Linux)''' avec une distribution Ubuntu installée.
* '''Visual Studio Code''' avec l'extension '''YAML''' (par Red Hat) installée. ''SaltStack est extrêmement strict sur l'indentation. Cette extension soulignera en rouge toute erreur d'espacement avant même que vous ne sauvegardiez.''
* '''Git''' installé sur Windows.


=== Configuration globale de Git (Fins de ligne) ===
Pour éviter que Windows n'insère des fins de ligne `CRLF` qui casseraient les fichiers Linux, ouvrez PowerShell et exécutez :
<syntaxhighlight lang="powershell">
<syntaxhighlight lang="powershell">
C:\STAGE 2025
git config --global core.autocrlf input
</syntaxhighlight>
</syntaxhighlight>
C'est dans ce dossier que vous allez ranger tout ce qui concerne le projet Operations.


----
----


== 2. Récupération et clonage du dépôt Operations ==
== 2. Création du dossier et clonage du dépôt ==


=== 2.1 Récupération de l'URL du dépôt ===
=== 2.1 Création du dossier de travail ===
 
Créez un dossier sur votre PC Windows pour organiser les fichiers du projet :
Rendez-vous sur la page du dépôt :
<syntaxhighlight lang="powershell">
* https://devcentral.nasqueron.org/source/operations/
mkdir "C:\STAGE 2025"
 
cd "C:\STAGE 2025"
Copiez l'URL Git pour pouvoir cloner le projet.
</syntaxhighlight>
 
=== 2.2 Clonage du dépôt ===
 
Ouvrez PowerShell et placez-vous dans votre dossier :


=== 2.2 Clonage du dépôt Operations ===
Toujours dans PowerShell, clonez le dépôt :
<syntaxhighlight lang="powershell">
<syntaxhighlight lang="powershell">
cd "C:\STAGE 2025"
git clone https://devcentral.nasqueron.org/source/operations.git
git clone https://devcentral.nasqueron.org/source/operations.git
</syntaxhighlight>
</syntaxhighlight>


Git crée un dossier <code>operations</code> avec tous les fichiers du projet.
----


----
== 3. Bascule sous WSL et création de branche ==


== 3. Configuration Git et création de branche dans WSL ==
À partir de maintenant, '''toutes les commandes Git et Arcanist seront exécutées dans WSL''' pour garantir un environnement Linux natif.


=== 3.1 Se placer dans le dossier du projet ===
=== 3.1 Se placer dans le dossier du projet ===
 
Ouvrez votre terminal Ubuntu (WSL) et naviguez vers le dossier cloné sous Windows :
Depuis WSL (Ubuntu), placez-vous dans le dossier du projet :
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
cd /mnt/c/STAGE\ 2025/operations
cd /mnt/c/STAGE\ 2025/operations
</syntaxhighlight>
</syntaxhighlight>


=== 3.2 Prévenir les problèmes de fins de ligne (CRLF) ===
=== 3.2 Création d'une branche dédiée ===
 
Ne travaillez jamais directement sur la branche principale (`main` ou `master`). Créez une branche pour votre arrivée :
Avant toute modification, configurez Git pour éviter que les fins de ligne Windows (CRLF) n'altèrent les fichiers du dépôt :
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
git config --global core.autocrlf input
git switch -c add-user-votrelogin
</syntaxhighlight>
</syntaxhighlight>
''Note : Si la branche existe déjà, utilisez simplement <code>git switch add-user-votrelogin</code>.''
----


=== 3.3 Création d'une nouvelle branche ===
== 4. Génération de votre clé SSH ==


Créez une branche dédiée à vos modifications au lieu de travailler sur la branche principale :
Votre clé SSH servira à vous authentifier sur les serveurs Nasqueron une fois votre compte créé.


=== 4.1 Générer la paire de clés ===
Dans WSL, générez une clé ED25519 :
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
git switch -c add-user-votrelogin
ssh-keygen -t ed25519 -C "votre.email@example.com"
</syntaxhighlight>
</syntaxhighlight>
''Appuyez sur Entrée pour accepter l'emplacement par défaut. Vous pouvez laisser la passphrase vide ou en choisir une.''


'''Attention :''' Si la branche existe déjà, Git affichera :
=== 4.2 Récupérer la clé publique ===
<code>fatal: a branch named 'add-user-votrelogin' already exists</code>
Affichez le contenu de votre clé publique pour la copier :
 
Dans ce cas, basculez simplement sur la branche existante :
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
git switch add-user-votrelogin
cat ~/.ssh/id_ed25519.pub
</syntaxhighlight>
</syntaxhighlight>
Copiez l'intégralité de la ligne affichée (elle commence par <code>ssh-ed25519</code>).


----
----


== 4. Modifications dans les fichiers du dépôt ==
== 5. Modifications des fichiers Salt (Pillars) ==
 
=== 4.1 Vérification de l'emplacement des fichiers ===
 
Vérifiez où se trouvent les vrais fichiers <code>users.sls</code> et <code>groups.sls</code> :
 
<syntaxhighlight lang="bash">
ls -la pillar/core/
</syntaxhighlight>
 
'''Important :''' Les vrais fichiers sont dans <code>pillar/core/</code>, pas dans <code>operations/pillar/core/</code>.
 
=== 4.2 Ajout de votre utilisateur dans users.sls ===


Ouvrez le fichier avec VS Code :
Ouvrez le dossier du projet dans VS Code.
<syntaxhighlight lang="text">
'''Rappel vital :''' En YAML, l'indentation est significative. Utilisez '''uniquement des espaces''' (jamais de tabulations). Respectez l'indentation existante (généralement 2 espaces par niveau).
pillar/core/users.sls
</syntaxhighlight>


Ajoutez votre utilisateur dans la section <code>shellusers:</code> par ordre alphabétique.
=== 5.1 Ajout dans users.sls ===
Ouvrez le fichier <code>pillar/core/users.sls</code>.
Ajoutez votre utilisateur dans la section <code>shellusers:</code> '''par ordre alphabétique'''.


'''Important :''' '''L'indentation est significative en YAML.''' Utilisez des espaces (jamais de tabulations). <code>fullname</code>, <code>ssh_keys</code> et <code>uid</code> doivent être indentés sous votre nom d'utilisateur.
* '''UID :''' Repérez le plus grand <code>uid</code> actuellement présent dans le fichier (qui est supérieur à 5000, ex: 5002) et incrémentez-le de 1 (ex: 5003). ''N'utilisez jamais de valeurs inférieures à 1024, elles sont réservées au système.''
* '''SSH Keys :''' Collez la clé publique générée à l'étape 4.2.


<syntaxhighlight lang="yaml">
<syntaxhighlight lang="yaml">
Line 109: Line 99:
</syntaxhighlight>
</syntaxhighlight>


'''Important :''' Remplacez <code>votrelogin</code>, <code>Prénom Nom</code>, l'adresse e-mail et la clé SSH par '''vos propres informations'''. Pour <code>uid</code>, repérez le plus grand UID actuellement présent dans le fichier (qui est supérieur à 5000) et incrémentez-le de 1 (ex: 5003). N'utilisez pas de valeurs inférieures à 1024 car elles sont réservées au système.
=== 5.2 Ajout dans groups.sls ===
 
Ouvrez le fichier <code>pillar/core/groups.sls</code>.
=== 4.3 Ajout de votre compte dans groups.sls ===
Ajoutez votre nom d'utilisateur dans la liste <code>members:</code> des groupes correspondant à vos besoins.
 
Ouvrez également le fichier :
<syntaxhighlight lang="text">
pillar/core/groups.sls
</syntaxhighlight>


Ajoutez votre nom d'utilisateur dans la liste <code>members:</code> (en minuscules) de chacun des groupes suivants selon vos besoins :
'''⚠️ ATTENTION À LA CASSE :''' La clé doit être strictement en minuscules : <code>members:</code> (et non <code>Members:</code>).
'''⚠️ GROUPES INEXISTANTS :''' Il n'existe '''pas''' de groupe système « core » (<code>core</code> est un rôle Salt) ni de groupe « nasqueron ».


* <code>nasquenautes</code> (pour les serveurs de développement généraux : WindRiver / Ysul)
Ajoutez-vous uniquement aux groupes suivants selon vos besoins :
* <code>nasqueron-dev-docker</code> (si vous avez besoin de Docker sur Dwellers)
* <code>nasquenautes</code> : Pour les serveurs de développement généraux (WindRiver / Ysul). '''(Recommandé)'''
* <code>shell</code> (optionnel, pour le serveur IRC Eglide)
* <code>nasqueron-dev-docker</code> : Si vous avez besoin de Docker sur Dwellers.
* <code>shell</code> : (Optionnel) Pour le serveur IRC Eglide.


<syntaxhighlight lang="yaml">
<syntaxhighlight lang="yaml">
Line 130: Line 117:
     - votrelogin
     - votrelogin
</syntaxhighlight>
</syntaxhighlight>
<syntaxhighlight lang="yaml">
nasqueron-dev-docker:
  members:
    - ...
    - votrelogin
</syntaxhighlight>
'''Important :''' Utilisez impérativement <code>members:</code> en minuscules. Il n'existe pas de groupe « core » (<code>core</code> est un rôle Salt) ni de groupe « nasqueron ».


----
----


== 5. Commit des modifications ==
== 6. Nettoyage et Commit des modifications ==
 
=== 5.1 Nettoyage et correction des fins de ligne ===
 
Si des fins de ligne CRLF ont été introduites, nettoyez-les spécifiquement sur les fichiers modifiés avec <code>dos2unix</code> :


=== 6.1 Correction des fins de ligne (CRLF) ===
Si vous avez un doute sur les fins de ligne, nettoyez '''spécifiquement''' les fichiers modifiés avec <code>dos2unix</code> :
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
dos2unix pillar/core/users.sls pillar/core/groups.sls
dos2unix pillar/core/users.sls pillar/core/groups.sls
</syntaxhighlight>
</syntaxhighlight>
'''🚨 DANGER :''' N'exécutez '''JAMAIS''' <code>git restore .</code> à cette étape. Cette commande annulerait et supprimerait définitivement toutes les modifications que vous venez de faire dans les fichiers YAML !


'''Attention :''' N'exécutez jamais <code>git restore .</code> à cette étape, sous peine de supprimer définitivement toutes les modifications que vous venez de réaliser.
=== 6.2 Création du commit ===
 
=== 5.2 Ajout des bons fichiers ===
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
git add pillar/core/users.sls pillar/core/groups.sls
git add pillar/core/users.sls pillar/core/groups.sls
</syntaxhighlight>
=== 5.3 Commit des changements ===
<syntaxhighlight lang="bash">
git commit -m "Create new account for Prénom Nom (nasquenautes)"
git commit -m "Create new account for Prénom Nom (nasquenautes)"
</syntaxhighlight>
</syntaxhighlight>
=== 5.4 Vérification du commit ===
<syntaxhighlight lang="bash">
git show HEAD
</syntaxhighlight>
Vérifiez que vous voyez seulement les lignes que vous avez vraiment modifiées.


----
----


== 6. Premier essai de arc diff (échec - arc n'existe pas) ==
== 7. Installation d'Arcanist (WSL) ==


Essayez de lancer :
Arcanist (`arc`) est l'outil en ligne de commande pour interagir avec DevCentral. Le dépôt original (Phacility) étant fermé, nous utilisons notre fork maintenu.
 
<syntaxhighlight lang="bash">
arc diff
</syntaxhighlight>
 
'''Erreur attendue :'''
<syntaxhighlight lang="text">
arc: command not found
</syntaxhighlight>
 
Il faut installer Arcanist.
 
----
 
== 7. Installation d'Arcanist avec WSL ==
 
=== Pourquoi installer Arcanist ? ===
 
Arcanist (ou <code>arc</code>) est l'outil officiel de ligne de commande pour interagir avec Phabricator / DevCentral, le système de revue de code utilisé par le projet Operations.
 
* Il permet de créer, mettre à jour et soumettre des révisions (<code>arc diff</code>) directement depuis votre environnement local.
* Il gère les linters et les tests automatiques configurés par le projet avant l'envoi de modifications.
* Sans Arcanist, vous ne pouvez pas soumettre vos changements pour revue ni intégrer les vérifications automatiques du projet.
 
=== 7.1 Mise à jour d'Ubuntu ===
 
Avant d'installer quoi que ce soit :


=== 7.1 Dépendances PHP ===
Arcanist est écrit en PHP. Installez les prérequis :
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
sudo apt update
sudo apt update
sudo apt upgrade -y
</syntaxhighlight>
=== 7.2 Installation des dépendances ===
Arcanist a besoin de PHP, Git et dos2unix :
<syntaxhighlight lang="bash">
sudo apt install -y php-cli php-curl php-xml php-mbstring git curl unzip dos2unix
sudo apt install -y php-cli php-curl php-xml php-mbstring git curl unzip dos2unix
</syntaxhighlight>
</syntaxhighlight>


=== 7.3 Téléchargement d'Arcanist (Dépôts Nasqueron) ===
=== 7.2 Clonage et installation ===
 
Création d'un dossier pour Arcanist et clonage depuis le dépôt maintenu par Nasqueron :
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
mkdir -p ~/phabricator
mkdir -p ~/phabricator
cd ~/phabricator
cd ~/phabricator
git clone https://github.com/nasqueron/arcanist.git
git clone https://github.com/nasqueron/arcanist.git
</syntaxhighlight>
=== 7.4 Rendre arc accessible partout ===
Pour ne pas devoir écrire tout le chemin :
<syntaxhighlight lang="bash">
sudo ln -s ~/phabricator/arcanist/bin/arc /usr/local/bin/arc
sudo ln -s ~/phabricator/arcanist/bin/arc /usr/local/bin/arc
</syntaxhighlight>
Si le cache Bash ne reconnaît pas la commande :
<syntaxhighlight lang="bash">
hash -r
hash -r
</syntaxhighlight>
</syntaxhighlight>


=== 7.5 Vérification de l'installation ===
Vérifiez l'installation :
 
Test de la commande :
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
arc version
arc version
Line 254: Line 164:
----
----


== 8. Deuxième essai de arc diff (échec - authentification requise) ==
== 8. Authentification Arcanist ==


Retournez dans le projet :
Pour qu'Arcanist puisse communiquer avec DevCentral, vous devez générer un Token API (Conduit Token) :
# Connectez-vous sur [https://devcentral.nasqueron.org DevCentral].
# Cliquez sur votre pseudo en haut à droite > '''Settings'''.
# Allez dans '''Conduit Tokens''' et cliquez sur '''Generate Token'''.
# Copiez le token généré.


Retournez dans le dossier du projet et installez le certificat :
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
cd /mnt/c/STAGE\ 2025/operations
cd /mnt/c/STAGE\ 2025/operations
arc diff
</syntaxhighlight>
'''Erreur attendue :'''
<syntaxhighlight lang="text">
YOU NEED TO AUTHENTICATE TO CONTINUE
</syntaxhighlight>
Il faut installer le certificat.
----
== 9. Authentification Arcanist ==
=== Pourquoi exécuter arc install-certificate ? ===
Cette commande permet d'associer votre environnement local à votre compte Phabricator / DevCentral via un token sécurisé.
* Elle est nécessaire pour que Arcanist puisse créer, mettre à jour et soumettre vos révisions (<code>arc diff</code>) sur le serveur.
* Sans ce certificat, Arcanist ne peut pas authentifier vos commandes et toutes les opérations de soumission de code échoueront.
* Le token est spécifique à votre compte et doit être généré depuis l'interface web (DevCentral -> Paramètres -> Jetons Conduit).
=== 9.1 Installation du certificat ===
<syntaxhighlight lang="bash">
arc install-certificate
arc install-certificate
</syntaxhighlight>
</syntaxhighlight>
 
''Collez le token lorsqu'il vous est demandé et suivez les instructions.''
Suivez le lien fourni, récupérez le token API et collez-le dans le terminal. Arcanist est maintenant connecté à votre compte.
 
----
 
== 10. Troisième essai de arc diff (éviter de dégrader .arclint) ==
 
<syntaxhighlight lang="bash">
arc diff --nolint
</syntaxhighlight>
 
'''Note :''' L'utilisation de l'option <code>--nolint</code> est recommandée pour soumettre directement sans altérer le fichier local <code>.arclint</code>. Ne modifiez jamais le linter de manière permanente dans votre commit.


----
----


== 11. Quatrième essai de arc diff (succès et remplissage de la révision) ==
== 9. Soumission de la révision (arc diff) ==


=== 11.1 Lancement d'Arcanist ===
Nous allons soumettre le code pour qu'il soit revu par l'équipe Ops.
'''Note :''' Nous utilisons <code>--nolint</code> pour éviter qu'Arcanist ne modifie votre fichier <code>.arclint</code> local ou ne bloque sur des règles de formatage non pertinentes pour votre ajout.


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
Line 310: Line 190:
</syntaxhighlight>
</syntaxhighlight>


Puis, si Arcanist vous demande d'utiliser le message sauvegardé :
=== 9.1 Remplissage du message de révision ===
<syntaxhighlight lang="text">
Arcanist va récupérer le message de votre dernier commit Git et ouvrir l'éditeur `nano`.
Do you want to use this message? [Y/n] Y
Assurez-vous que le résumé est correct. '''N'écrivez pas « dans le groupe core »'''.
</syntaxhighlight>
 
=== 11.2 Remplissage des informations de révision ===
 
L'éditeur (nano) s'ouvre avec les informations à remplir :


<syntaxhighlight lang="text">
<syntaxhighlight lang="text">
Line 326: Line 201:
</syntaxhighlight>
</syntaxhighlight>


'''Important :''' N'écrivez pas « dans le groupe core » dans le résumé, car ce groupe n'existe pas.
=== 9.2 Sauvegarde et validation ===
# Dans `nano`, faites '''Ctrl + O''' puis '''Entrée''' pour sauvegarder.
# Faites '''Ctrl + X''' pour quitter.
# Si Arcanist demande <code>Do you want to use this message? [Y/n]</code>, répondez <code>Y</code>.


=== 11.3 Sauvegarde dans nano ===
À la fin du processus, Arcanist affichera l'URL de votre révision sur DevCentral (ex: <code>https://devcentral.nasqueron.org/DXXXX</code>).


# '''Sauvegarder le fichier :'''
----
#* Appuyez sur '''Ctrl + O''' (la lettre O) -> appuyez sur '''Entrée''' pour valider.
# '''Quitter nano :'''
#* Appuyez sur '''Ctrl + X'''.
 
Après cela, votre révision est créée sur DevCentral (un lien sous la forme <code>https://devcentral.nasqueron.org/DXXXX</code> s'affichera).


=== 11.4 Pour mettre à jour une révision existante (si le reviewer demande des corrections) ===
== 10. Cycle de vie de la révision (Mise à jour et Merge) ==


Si vous devez corriger des éléments demandés lors de la revue :
* '''NE MERGEZ PAS VOUS-MÊME :''' N'essayez '''jamais''' de faire <code>arc land</code> ou <code>git push</code>. Votre code entre dans une file de révision. Un membre de l'équipe Ops va le relire et le fusionner pour vous.
# Effectuez les modifications localement.
* '''Si le reviewer demande des corrections :'''
# Mettez à jour votre commit :
  # Faites les modifications demandées dans VS Code.
<syntaxhighlight lang="bash">
  # Mettez à jour votre commit existant : <code>git commit -a --amend</code>
git commit -a --amend
  # Renvoyez la mise à jour sur DevCentral : <code>arc diff --nolint</code>
</syntaxhighlight>
# Mettez à jour la révision sur DevCentral :
<syntaxhighlight lang="bash">
arc diff --nolint
</syntaxhighlight>


----
----


== 12. Finalisation et validation de l'accès ==
== 11. Finalisation et validation de l'accès ==
 
'''Attention :''' '''N'essayez pas de fusionner le commit ou d'exécuter `arc land` vous-même.'''


Une fois la révision soumise :
Une fois votre révision approuvée et fusionnée par un administrateur :
# Un membre de l'équipe **ops** contrôlera et validera votre demande sur DevCentral.
# Attendez que le déploiement Salt (highstate) s'exécute sur les serveurs (ou demandez à un admin de le déclencher).
# Un administrateur fusionnera votre révision (merge).
# Testez votre accès SSH depuis WSL :
# Dès que le déploiement Salt aura été exécuté sur les serveurs, testez votre accès SSH :
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
ssh votrelogin@windriver.nasqueron.org
ssh votrelogin@windriver.nasqueron.org
</syntaxhighlight>
</syntaxhighlight>
----
== 13. Vérification finale du dépôt local ==
Vérifiez que votre workspace est propre :
<syntaxhighlight lang="bash">
git status
</syntaxhighlight>
Résultat attendu : Aucun fichier non commité ne doit rester dans votre répertoire de travail.


----
----
Line 383: Line 236:
! Problème !! Solution
! Problème !! Solution
|-
|-
| Indentation YAML incorrecte dans <code>users.sls</code> / <code>groups.sls</code> || Respecter l'indentation existante du fichier (2 espaces par niveau)
| Indentation YAML incorrecte || Utiliser l'extension VS Code YAML. Respecter les 2 espaces. Jamais de tabulations.
|-
|-
| Utilisation de <code>core</code> ou <code>nasqueron</code> comme nom de groupe || Utiliser uniquement <code>nasquenautes</code>, <code>nasqueron-dev-docker</code> ou <code>shell</code> dans <code>groups.sls</code>
| Utilisation de <code>core</code> ou <code>nasqueron</code> comme groupe || Ces groupes n'existent pas. Utiliser <code>nasquenautes</code>, <code>nasqueron-dev-docker</code> ou <code>shell</code>.
|-
|-
| Nom de clé <code>Members:</code> avec majuscule || Utiliser exclusivement <code>members:</code> en minuscules
| Clé YAML <code>Members:</code> avec majuscule || Utiliser exclusivement <code>members:</code> en minuscules.
|-
|-
| Cache Bash pour <code>arc</code> || <code>hash -r</code>
| UID inférieur à 1024 || Utiliser un UID > 5000 (incrémenter le plus grand UID existant).
|-
|-
| Authentification manquante || <code>arc install-certificate</code>
| Effacement du travail avec <code>git restore .</code> || Utiliser <code>dos2unix</code> ciblé sur les fichiers modifiés pour corriger le CRLF.
|-
|-
| Effacement accidentel des modifications avec <code>git restore .</code> || Utiliser <code>dos2unix</code> ciblé sur les fichiers modifiés
| Modification du linter (.arclint) || Toujours utiliser <code>arc diff --nolint</code>.
|-
|-
| Clone de <code>phacility/arcanist</code> en 404 || Cloner le fork maintenu <code>https://github.com/nasqueron/arcanist.git</code>
| Clone de <code>phacility/arcanist</code> en 404 || Cloner le fork maintenu <code>https://github.com/nasqueron/arcanist.git</code>.
|}
|}


Line 402: Line 255:
== Points importants à retenir ==
== Points importants à retenir ==


* '''Toutes les commandes Git et Arcanist doivent être exécutées dans <code>/mnt/c/STAGE\ 2025/operations</code>, et non dans <code>~/phabricator</code>.'''
* '''Environnement :''' Le dépôt est cloné sous Windows, mais toutes les commandes Git/Arcanist s'exécutent dans WSL (<code>/mnt/c/...</code>).
* '''L'indentation YAML est significative : respectez celle déjà présente dans <code>users.sls</code> et <code>groups.sls</code> (2 espaces), n'utilisez jamais de tabulations.'''
* '''Sécurité Git :''' Ne jamais utiliser <code>git restore .</code> pour régler un problème de fin de ligne.
* '''Remplacez toujours les exemples (nom d'utilisateur, nom complet, e-mail, clé SSH, uid) par vos propres informations.'''
* '''Patience :''' Une fois <code>arc diff</code> réussi, votre travail est terminé. Attendez la validation et le déploiement par l'équipe Ops avant de tenter une connexion SSH.
* '''Pour l'UID, utilisez une valeur supérieure à 5000 (incrémentée depuis la plus haute valeur existante) et non 1002.'''
* '''Ne tentez jamais de pusher ou merger vous-même le commit : attendez la validation d'un administrateur ops.'''


[[Category:Contributor guide]]
[[Category:Contributor guide]]
[[Category:Reference]]
[[Category:Reference]]
[[Category:Internship guide]]
[[Category:Internship guide]]

Latest revision as of 14:53, 11 August 2026

Guide complet : Configuration de l'accès devserver avec Git et Arcanist

Ce guide explique comment configurer votre environnement de développement Windows (via WSL) pour contribuer au projet Operations et obtenir vos accès aux serveurs de développement (Devservers).

1. Prérequis et Environnement

Avant de commencer, assurez-vous de disposer des outils suivants sur votre machine Windows :

  • WSL (Windows Subsystem for Linux) avec une distribution Ubuntu installée.
  • Visual Studio Code avec l'extension YAML (par Red Hat) installée. SaltStack est extrêmement strict sur l'indentation. Cette extension soulignera en rouge toute erreur d'espacement avant même que vous ne sauvegardiez.
  • Git installé sur Windows.

Configuration globale de Git (Fins de ligne)

Pour éviter que Windows n'insère des fins de ligne `CRLF` qui casseraient les fichiers Linux, ouvrez PowerShell et exécutez : 

git config --global core.autocrlf input

2. Création du dossier et clonage du dépôt

2.1 Création du dossier de travail

Créez un dossier sur votre PC Windows pour organiser les fichiers du projet : 

mkdir "C:\STAGE 2025"
cd "C:\STAGE 2025"

2.2 Clonage du dépôt Operations

Toujours dans PowerShell, clonez le dépôt : 

git clone https://devcentral.nasqueron.org/source/operations.git

3. Bascule sous WSL et création de branche

À partir de maintenant, toutes les commandes Git et Arcanist seront exécutées dans WSL pour garantir un environnement Linux natif.

3.1 Se placer dans le dossier du projet

Ouvrez votre terminal Ubuntu (WSL) et naviguez vers le dossier cloné sous Windows : 

cd /mnt/c/STAGE\ 2025/operations

3.2 Création d'une branche dédiée

Ne travaillez jamais directement sur la branche principale (`main` ou `master`). Créez une branche pour votre arrivée : 

git switch -c add-user-votrelogin

Note : Si la branche existe déjà, utilisez simplement git switch add-user-votrelogin.

4. Génération de votre clé SSH

Votre clé SSH servira à vous authentifier sur les serveurs Nasqueron une fois votre compte créé.

4.1 Générer la paire de clés

Dans WSL, générez une clé ED25519 : 

ssh-keygen -t ed25519 -C "votre.email@example.com"

Appuyez sur Entrée pour accepter l'emplacement par défaut. Vous pouvez laisser la passphrase vide ou en choisir une.

4.2 Récupérer la clé publique

Affichez le contenu de votre clé publique pour la copier : 

cat ~/.ssh/id_ed25519.pub

Copiez l'intégralité de la ligne affichée (elle commence par ssh-ed25519).

5. Modifications des fichiers Salt (Pillars)

Ouvrez le dossier du projet dans VS Code. Rappel vital : En YAML, l'indentation est significative. Utilisez uniquement des espaces (jamais de tabulations). Respectez l'indentation existante (généralement 2 espaces par niveau).

5.1 Ajout dans users.sls

Ouvrez le fichier pillar/core/users.sls. Ajoutez votre utilisateur dans la section shellusers: par ordre alphabétique.

  • UID : Repérez le plus grand uid actuellement présent dans le fichier (qui est supérieur à 5000, ex: 5002) et incrémentez-le de 1 (ex: 5003). N'utilisez jamais de valeurs inférieures à 1024, elles sont réservées au système.
  • SSH Keys : Collez la clé publique générée à l'étape 4.2.
shellusers:
  ...
  votrelogin:
    fullname: Prénom Nom
    ssh_keys:
      - ssh-ed25519 AAAA... votre.email@example.com
    uid: 5003
  ...

5.2 Ajout dans groups.sls

Ouvrez le fichier pillar/core/groups.sls. Ajoutez votre nom d'utilisateur dans la liste members: des groupes correspondant à vos besoins.

⚠️ ATTENTION À LA CASSE : La clé doit être strictement en minuscules : members: (et non Members:). ⚠️ GROUPES INEXISTANTS : Il n'existe pas de groupe système « core » (core est un rôle Salt) ni de groupe « nasqueron ».

Ajoutez-vous uniquement aux groupes suivants selon vos besoins :

  • nasquenautes : Pour les serveurs de développement généraux (WindRiver / Ysul). (Recommandé)
  • nasqueron-dev-docker : Si vous avez besoin de Docker sur Dwellers.
  • shell : (Optionnel) Pour le serveur IRC Eglide.
nasquenautes:
  members:
    - ...
    - votrelogin

6. Nettoyage et Commit des modifications

6.1 Correction des fins de ligne (CRLF)

Si vous avez un doute sur les fins de ligne, nettoyez spécifiquement les fichiers modifiés avec dos2unix : 

dos2unix pillar/core/users.sls pillar/core/groups.sls

🚨 DANGER : N'exécutez JAMAIS git restore . à cette étape. Cette commande annulerait et supprimerait définitivement toutes les modifications que vous venez de faire dans les fichiers YAML !

6.2 Création du commit

git add pillar/core/users.sls pillar/core/groups.sls
git commit -m "Create new account for Prénom Nom (nasquenautes)"

7. Installation d'Arcanist (WSL)

Arcanist (`arc`) est l'outil en ligne de commande pour interagir avec DevCentral. Le dépôt original (Phacility) étant fermé, nous utilisons notre fork maintenu.

7.1 Dépendances PHP

Arcanist est écrit en PHP. Installez les prérequis : 

sudo apt update
sudo apt install -y php-cli php-curl php-xml php-mbstring git curl unzip dos2unix

7.2 Clonage et installation

mkdir -p ~/phabricator
cd ~/phabricator
git clone https://github.com/nasqueron/arcanist.git
sudo ln -s ~/phabricator/arcanist/bin/arc /usr/local/bin/arc
hash -r

Vérifiez l'installation : 

arc version

8. Authentification Arcanist

Pour qu'Arcanist puisse communiquer avec DevCentral, vous devez générer un Token API (Conduit Token) :

  1. Connectez-vous sur DevCentral.
  2. Cliquez sur votre pseudo en haut à droite > Settings.
  3. Allez dans Conduit Tokens et cliquez sur Generate Token.
  4. Copiez le token généré.

Retournez dans le dossier du projet et installez le certificat : 

cd /mnt/c/STAGE\ 2025/operations
arc install-certificate

Collez le token lorsqu'il vous est demandé et suivez les instructions.

9. Soumission de la révision (arc diff)

Nous allons soumettre le code pour qu'il soit revu par l'équipe Ops. Note : Nous utilisons --nolint pour éviter qu'Arcanist ne modifie votre fichier .arclint local ou ne bloque sur des règles de formatage non pertinentes pour votre ajout. 

arc diff --nolint

9.1 Remplissage du message de révision

Arcanist va récupérer le message de votre dernier commit Git et ouvrir l'éditeur `nano`. Assurez-vous que le résumé est correct. N'écrivez pas « dans le groupe core ». 

Summary: Create new account for Prénom Nom (nasquenautes)
Test Plan: Syntax check on YAML pillar files
Reviewers: dereckson
Subscribers:

9.2 Sauvegarde et validation

  1. Dans `nano`, faites Ctrl + O puis Entrée pour sauvegarder.
  2. Faites Ctrl + X pour quitter.
  3. Si Arcanist demande Do you want to use this message? [Y/n], répondez Y.

À la fin du processus, Arcanist affichera l'URL de votre révision sur DevCentral (ex: https://devcentral.nasqueron.org/DXXXX).

10. Cycle de vie de la révision (Mise à jour et Merge)

  • NE MERGEZ PAS VOUS-MÊME : N'essayez jamais de faire arc land ou git push. Votre code entre dans une file de révision. Un membre de l'équipe Ops va le relire et le fusionner pour vous.
  • Si le reviewer demande des corrections :
 # Faites les modifications demandées dans VS Code.
 # Mettez à jour votre commit existant : git commit -a --amend
 # Renvoyez la mise à jour sur DevCentral : arc diff --nolint

11. Finalisation et validation de l'accès

Une fois votre révision approuvée et fusionnée par un administrateur :

  1. Attendez que le déploiement Salt (highstate) s'exécute sur les serveurs (ou demandez à un admin de le déclencher).
  2. Testez votre accès SSH depuis WSL :
ssh votrelogin@windriver.nasqueron.org

Résumé des problèmes et erreurs évitées

Problème Solution
Indentation YAML incorrecte Utiliser l'extension VS Code YAML. Respecter les 2 espaces. Jamais de tabulations.
Utilisation de core ou nasqueron comme groupe Ces groupes n'existent pas. Utiliser nasquenautes, nasqueron-dev-docker ou shell.
Clé YAML Members: avec majuscule Utiliser exclusivement members: en minuscules.
UID inférieur à 1024 Utiliser un UID > 5000 (incrémenter le plus grand UID existant).
Effacement du travail avec git restore . Utiliser dos2unix ciblé sur les fichiers modifiés pour corriger le CRLF.
Modification du linter (.arclint) Toujours utiliser arc diff --nolint.
Clone de phacility/arcanist en 404 Cloner le fork maintenu https://github.com/nasqueron/arcanist.git.

Points importants à retenir

  • Environnement : Le dépôt est cloné sous Windows, mais toutes les commandes Git/Arcanist s'exécutent dans WSL (/mnt/c/...).
  • Sécurité Git : Ne jamais utiliser git restore . pour régler un problème de fin de ligne.
  • Patience : Une fois arc diff réussi, votre travail est terminé. Attendez la validation et le déploiement par l'équipe Ops avant de tenter une connexion SSH.
Retrieved from "https://agora.nasqueron.org/index.php?title=Dev_zone/Create_devserver_access/fr&oldid=2569"