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

From Nasqueron Agora
← Older edit

Ptdradmin (talk | contribs)

17 edits
m Update categories
Ptdradmin (talk | contribs)
17 edits
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
__TOC__
= 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. Gestion de 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 Création d'une nouvelle branche ===
=== 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 :
Créez une nouvelle branche pour vos modifications :
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
git switch -c feature/add-gui-user
git switch -c add-user-votrelogin
</syntaxhighlight>
</syntaxhighlight>
 
''Note : Si la branche existe déjà, utilisez simplement <code>git switch add-user-votrelogin</code>.''
Avertissement|Si la branche existe déjà, Git affichera :
<code>fatal: a branch named 'feature/add-gui-user' already exists</code>
 
Dans ce cas, basculez simplement sur la branche existante :
<syntaxhighlight lang="bash">
git switch feature/add-gui-user
</syntaxhighlight>
 


----
----


== 4. Modifications dans les fichiers du dépôt ==
== 4. Génération de votre clé SSH ==


=== 4.1 Vérification de l'emplacement des fichiers ===
Votre clé SSH servira à vous authentifier sur les serveurs Nasqueron une fois votre compte créé.


Vérifiez où se trouvent les vrais fichiers <code>users.sls</code> et <code>groups.sls</code> :
=== 4.1 Générer la paire de clés ===
Dans WSL, générez une clé ED25519 :
<syntaxhighlight lang="bash">
ssh-keygen -t ed25519 -C "votre.email@example.com"
</syntaxhighlight>
''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 :
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
ls -la pillar/core/
cat ~/.ssh/id_ed25519.pub
</syntaxhighlight>
</syntaxhighlight>
Copiez l'intégralité de la ligne affichée (elle commence par <code>ssh-ed25519</code>).
----


Important|Les vrais fichiers sont dans <code>pillar/core/</code>, pas dans <code>operations/pillar/core/</code>.
== 5. Modifications des fichiers Salt (Pillars) ==


=== 4.2 Ajout de votre utilisateur dans users.sls ===
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).


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


Ajoutez votre utilisateur dans la section <code>shellusers:</code> par ordre alphabétique :
* '''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">
ptdradmin:
shellusers:
   fullname: Doba Gui
   ...
  ssh_keys:
  votrelogin:
    - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAFtlR4OeXNHfJXNrvrLeU9nGu7ufcxc38xUGqlwiY5L doba.guimartinien@gmail.com
    fullname: Prénom Nom
  uid: 1001
    ssh_keys:
      - ssh-ed25519 AAAA... votre.email@example.com
    uid: 5003
  ...
</syntaxhighlight>
</syntaxhighlight>


=== 4.3 Ajout de votre compte dans groups.sls ===
=== 5.2 Ajout dans groups.sls ===
Ouvrez le fichier <code>pillar/core/groups.sls</code>.
Ajoutez votre nom d'utilisateur dans la liste <code>members:</code> des groupes correspondant à vos besoins.


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


Ajoutez-vous dans le groupe <code>core</code> :
Ajoutez-vous uniquement aux groupes suivants selon vos besoins :
* <code>nasquenautes</code> : Pour les serveurs de développement généraux (WindRiver / Ysul). '''(Recommandé)'''
* <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">
core:
nasquenautes:
   Members:
   members:
     - ptdradmin
     - ...
    - votrelogin
</syntaxhighlight>
</syntaxhighlight>


----
----


== 5. Commit des modifications ==
== 6. Nettoyage et Commit des modifications ==
 
=== 5.1 Suppression des fichiers créés par erreur ===
 
Si vous avez créé des fichiers vides dans <code>operations/</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">
rm -rf operations/
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 !


=== 5.2 Ajout des bons fichiers ===
=== 6.2 Création du commit ===
 
<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
git commit -m "Create new account for Prénom Nom (nasquenautes)"
</syntaxhighlight>
</syntaxhighlight>
=== 5.3 Commit des changements ===
<syntaxhighlight lang="bash">
git commit -m "Ajout de Doba Gui comme user et dans le groupe core"
</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.
=== 5.5 Modification du dernier commit (si nécessaire) ===
Si vous avez corrigé des fichiers après le commit :
<syntaxhighlight lang="bash">
git commit --amend
</syntaxhighlight>
----
== 6. Premier essai de arc diff (échec - arc n'existe pas) ==
Essayez de lancer :
<syntaxhighlight lang="bash">
arc diff
</syntaxhighlight>
'''Erreur attendue :'''
<syntaxhighlight>
arc: command not found
</syntaxhighlight>
Il faut installer Arcanist.


----
----


== 7. Installation d'Arcanist avec WSL ==
== 7. Installation d'Arcanist (WSL) ==
 
=== Pourquoi installer Arcanist ? ===
 
Arcanist (ou <code>arc</code>) est l'outil officiel de ligne de commande pour interagir avec Phabricator, 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 ===
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.
 
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
sudo apt install -y php-cli php-curl php-xml php-mbstring git curl unzip dos2unix
</syntaxhighlight>
</syntaxhighlight>


=== 7.2 Installation des dépendances ===
=== 7.2 Clonage et installation ===
 
Arcanist a besoin de PHP et Git :
 
<syntaxhighlight lang="bash">
sudo apt install -y php-cli php-curl php-xml php-mbstring git curl unzip
</syntaxhighlight>
 
=== 7.3 Téléchargement d'Arcanist ===
 
Création d'un dossier pour Arcanist :
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
mkdir -p ~/phabricator
mkdir -p ~/phabricator
cd ~/phabricator
cd ~/phabricator
</syntaxhighlight>
git clone https://github.com/nasqueron/arcanist.git
 
Téléchargement des fichiers :
 
<syntaxhighlight lang="bash">
git clone https://github.com/phacility/arcanist.git
git clone https://github.com/phacility/libphutil.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
</syntaxhighlight>
</syntaxhighlight>
Note|Une erreur sur shellcheck-linter peut apparaître, mais la version devrait s'afficher. Répondre "y" pour continuer.


----
----


== 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>
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 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 Phabricator
* 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 de Phabricator
=== 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 (échec - shellcheck-linter manquant) ==
 
<syntaxhighlight lang="bash">
arc diff
</syntaxhighlight>
 
Arc vous demande de choisir la branche de référence, choisissez <code>origin/main</code>.
 
'''Nouvelle erreur :'''
<syntaxhighlight>
Failed to load library at location "shellcheck-linter"
</syntaxhighlight>


----
----


== 11. Installation de shellcheck-linter ==
== 9. Soumission de la révision (arc diff) ==
 
<syntaxhighlight lang="bash">
cd ~/phabricator
git clone https://github.com/pinterest/arcanist-linters.git shellcheck-linter
</syntaxhighlight>
 
----
 
== 12. Quatrième essai de arc diff (échec - linter invalide) ==
 
Retournez dans le projet :
 
<syntaxhighlight lang="bash">
cd /mnt/c/STAGE\ 2025/operations
arc diff
</syntaxhighlight>
 
'''Nouvelle erreur :'''
<syntaxhighlight>
Linter 'shell' specifies invalid type 'shellcheck'
</syntaxhighlight>
 
Le type <code>shellcheck</code> n'est pas reconnu.
 
----
 
== 13. Correction du linter shellcheck ==
 
Ouvrez <code>.arclint</code> avec VS Code et modifiez :
 
'''Avant :'''
<syntaxhighlight lang="json">
"shell": {
  "type": "shellcheck",
  "include": ["(\\.sh$)"]
}
</syntaxhighlight>
 
'''Après :'''
<syntaxhighlight lang="json">
"shell": {
  "type": "text",
  "include": ["(\\.sh$)"]
}
</syntaxhighlight>
 
Avertissement|Ne pas commiter ce changement, c'est juste pour que ça fonctionne localement.


'''Alternative :''' Bypass des tests si nécessaire :
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 346: Line 190:
</syntaxhighlight>
</syntaxhighlight>


----
=== 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`.
== 14. Cinquième essai de arc diff (échec - problème CRLF) ==
Assurez-vous que le résumé est correct. '''N'écrivez pas « dans le groupe core »'''.
 
<syntaxhighlight lang="bash">
arc diff
</syntaxhighlight>
 
Arc détecte 1,011 fichiers modifiés. C'est un problème de fins de ligne Windows/Linux.
 
=== 14.1 Correction des problèmes de fins de ligne ===
 
<syntaxhighlight lang="bash">
git config --global core.autocrlf input
git restore .
</syntaxhighlight>
 
Avertissement|Assurez-vous d'être bien dans <code>/mnt/c/STAGE\ 2025/operations</code> avant d'exécuter ces commandes.
 
----
 
== 15. Sixième essai de arc diff (succès !) ==


=== 15.1 Vérification de l'état de Git ===
<syntaxhighlight lang="text">
 
Summary: Create new account for Prénom Nom (nasquenautes)
Pour vous assurer qu'il n'y a pas de fichiers non suivis :
Test Plan: Syntax check on YAML pillar files
 
<syntaxhighlight lang="bash">
git status
</syntaxhighlight>
 
'''Résultat attendu :''' Aucun fichier non commité ne doit apparaître.
 
=== 15.2 Lancement d'Arcanist ===
 
<syntaxhighlight lang="bash">
arc diff
</syntaxhighlight>
 
Arc vous demande si vous voulez amend les changements dans <code>.arclint</code> :
<syntaxhighlight>
Do you want to amend these 1 change(s) to the current commit? [y/N] y
</syntaxhighlight>
 
Puis il vous demande si vous voulez utiliser le message sauvegardé :
<syntaxhighlight>
Do you want to use this message? [Y/n] Y
</syntaxhighlight>
 
=== 15.3 Remplissage des informations de révision ===
 
L'éditeur (nano) s'ouvre avec les informations à remplir :
 
<syntaxhighlight>
Summary: Ajout de Doba Gui comme user et dans le groupe core
Test Plan: Vérification de la syntaxe YAML et des informations utilisateur
Reviewers: dereckson
Reviewers: dereckson
Subscribers:
Subscribers:
</syntaxhighlight>
</syntaxhighlight>


=== 15.4 Sauvegarde dans nano ===
=== 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>.


# '''Sauvegarder le fichier :'''
À la fin du processus, Arcanist affichera l'URL de votre révision sur DevCentral (ex: <code>https://devcentral.nasqueron.org/DXXXX</code>).
#* Appuyez sur '''Ctrl + O''' (la lettre O, pas zéro)
#* Nano vous demandera le nom du fichier → appuyez sur '''Entrée''' pour garder le même
# '''Quitter nano :'''
#* Appuyez sur '''Ctrl + X'''


Après ça, vous retournez dans votre terminal et <code>arc diff</code> continuera le processus.
----


=== 15.5 Pour mettre à jour une révision existante ===
== 10. Cycle de vie de la révision (Mise à jour et Merge) ==


Si vous voulez mettre à jour une révision existante (ex. : D3888) :
* '''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.
 
* '''Si le reviewer demande des corrections :'''
<syntaxhighlight lang="bash">
  # Faites les modifications demandées dans VS Code.
arc diff --update D3888
  # Mettez à jour votre commit existant : <code>git commit -a --amend</code>
</syntaxhighlight>
  # Renvoyez la mise à jour sur DevCentral : <code>arc diff --nolint</code>


----
----


== 16. Vérification finale ==
== 11. Finalisation et validation de l'accès ==
 
Vérifiez que tout est propre :
 
<syntaxhighlight lang="bash">
git status
</syntaxhighlight>
 
Aucun fichier ne doit rester non commité.
 
Assurez-vous que votre révision contient bien vos modifications :


Une fois votre révision approuvée et fusionnée par un administrateur :
# Attendez que le déploiement Salt (highstate) s'exécute sur les serveurs (ou demandez à un admin de le déclencher).
# Testez votre accès SSH depuis WSL :
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
arc diff
ssh votrelogin@windriver.nasqueron.org
</syntaxhighlight>
</syntaxhighlight>
Succès|À ce stade, votre révision est prête à être relue par votre reviewer.


----
----


== Résumé des problèmes rencontrés ==
== Résumé des problèmes et erreurs évitées ==


{| class="wikitable"
{| class="wikitable"
! Problème !! Solution
! Problème !! Solution
|-
|-
| Fichiers vides dans operations/ || <code>rm -rf operations/</code> puis travailler dans <code>pillar/core/</code>
| 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 groupe || Ces groupes n'existent pas. Utiliser <code>nasquenautes</code>, <code>nasqueron-dev-docker</code> ou <code>shell</code>.
|-
|-
| Cache Bash pour arc || <code>hash -r</code>
| Clé YAML <code>Members:</code> avec majuscule || Utiliser exclusivement <code>members:</code> en minuscules.
|-
|-
| Authentification manquante || <code>arc install-certificate</code>
| UID inférieur à 1024 || Utiliser un UID > 5000 (incrémenter le plus grand UID existant).
|-
|-
| Bibliothèque shellcheck-linter manquante || Cloner dans <code>~/phabricator/</code>
| Effacement du travail avec <code>git restore .</code> || Utiliser <code>dos2unix</code> ciblé sur les fichiers modifiés pour corriger le CRLF.
|-
|-
| Erreur linter shellcheck || Changer <code>"type": "shellcheck"</code> en <code>"type": "text"</code> dans <code>.arclint</code>
| Modification du linter (.arclint) || Toujours utiliser <code>arc diff --nolint</code>.
|-
|-
| Problème CRLF/LF || <code>git config --global core.autocrlf input</code> puis <code>git restore .</code>
| Clone de <code>phacility/arcanist</code> en 404 || Cloner le fork maintenu <code>https://github.com/nasqueron/arcanist.git</code>.
|}
|}


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


Avertissement|
* '''Environnement :''' Le dépôt est cloné sous Windows, mais toutes les commandes Git/Arcanist s'exécutent dans WSL (<code>/mnt/c/...</code>).
* '''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>.'''
* '''Sécurité Git :''' Ne jamais utiliser <code>git restore .</code> pour régler un problème de fin de ligne.
* '''Ne pas commiter les modifications du fichier <code>.arclint</code> (changement de shellcheck en text).'''
* '''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.
* '''Les vrais fichiers sont dans <code>pillar/core/</code>, pas dans <code>operations/pillar/core/</code>.'''


[[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"