Différences

Ci-dessous, les différences entre deux révisions de la page.

--- admin:services:faq_services [2020/02/28 17:44] – admin
+++ admin:services:faq_services [2026/02/18 21:37] (Version actuelle) – [Dépôt Git d’un service] FAQ de la forge fhenry2
@@ Ligne 1: / Ligne 1: @@
 ======= FAQ Services =======
-L'administration système et de services en ligne implique des choix d'organisation, de nommage, de rangement… Ceux-ci peuvent être très variés d'une équipe à l'autre.
+L'administration système et de services en ligne implique des choix d'organisation, de nommage, de rangement…
+Ceux-ci peuvent être très variés d'une équipe à l'autre.
 Afin d'avoir une forme d'homogénéité dans le Chapril, voici sous forme de FAQ, quelques conventions techniques à suivre, dans la mesure du possible.
-Bien sûr, ces conventions sont ouvertes au changement et aux propositions d'évolution. Mais ça se fera de façon concertée. En attendant, elles restent une référence importante pour tout déploiement d'un service dans le Chapril.
+Bien sûr, ces conventions sont ouvertes au changement et aux propositions d'évolution.
+Mais ça se fera de façon concertée.
+En attendant, elles restent une référence importante pour tout déploiement d'un service dans le Chapril.
 ===== EtcKeeper ? =====
-Le dossier ''/etc/'' est « gité » via EtcKeeper. Penser à commiter dès que vous y faites une modification.
+Le répertoire ''/etc/'' est //gité// via [[https://etckeeper.branchable.com/|EtcKeeper]].
+Penser à //commiter// dès que vous y faites une modification.
-===== Tâches CRON ? =====
+===== Les fichiers de configuration HTTP ? =====
-La sagesse unixienne recommande aux utilisateurs de passer par ''crontab -u user -e'' pour déclarer une tâche cron sans perturber le système. C'est vraiment une bonne idée. Sauf que sur nos vm, nous ne sommes pas des utilisateurs mais des **adminsys**. Et même si certains services tournent sous un compte Unix dédié, il s'agit d'un compte système et non d'un compte utilisateur classique.
+Traditionnellement, le fichier de configuration d'un site Web est dans ''/etc/apache2/sites-available/'' ou ''/etc/nginx/sites-available/''.
-En conséquence, les recommandations sont les suivantes :
+Convention technique recommandée : donner le nom complet du service comme ''foo.chapril.org.conf''.
-  * les tâches cron sont à déclarer dans ''/etc/cron.d/'' ;
-  * les tâches cron sont à mettre dans un ou plusieurs fichiers dédiés au service ;
-  * le nommage doit reprendre le nom du service (''foochaprilorg'', ''foochaprilorg-bare'') ;
-  * penser à commiter en cas de modification (avoir bien configuré son SSH pour transférer les variables GIT nécessaires) ;
-  * logger la tâche cron (exemple : ''…/task.sh >> /var/log/foochaprilorg-bar.log 2>&1'').
-Exemples de nommage :
-<code>
-=(^-^)=root@lamp:/etc/cron.d# ll
-total 16
--rw-r--r-- 1 root root  63 juil. 18 16:30 backup
--rw-r--r-- 1 root root 375 janv.  6 23:10 datechaprilorg
--rw-r--r-- 1 root root 134 déc.   7 10:48 pastechaprilorg
--rw-r--r-- 1 root root 712 janv.  1  2017 php
-</code>
-Avantages :
-  * facilité d'accès pour les adminsys quand ils cherchent le cron d'un service ;
-  * historisation et traçabilité de la configuration ;
-  * alertes Icinga2 si oublie de commit ;
-  * sauvegarde automatique ;
-  * …
-===== Les fichiers de conf HTTP ? =====
-Traditionnellement, le fichier de configuration d'un site web est dans ''/etc/apache2/sites-available/'' ou ''/etc/nginx/sites-available/''.
-Conventions techniques recommandées :
-  * donner le nom complet du service : ''foo.chapril.org.conf''.
 Exemples :
+<code bash>
+cd /etc/apache2/sites-available/
+ll
+</code>
 <code>
-=(^-^)=root@lamp:/etc/apache2/sites-available# ll
 total 44
 -rw-r--r-- 1 root root  498 sept. 27 14:11 banner.chapril.org.conf
@@ Ligne 58: / Ligne 36: @@
 -rw-r--r-- 1 root root 1917 nov.  29 23:40 www.chapril.org.conf
 </code>
+===== Les fichiers Web  ? =====
+L'emplacement par défaut pour les fichiers Web d'un service, c'est ''/var/www/foo.chapril.org''.
 ===== Les fichiers de logs HTTP ? =====
-Traditionnellement, les logs HTTP sont dans ''/var/log/apache2/'' ou ''/var/log/nginx/''. C'est bien. Mais comme on est susceptible d'avoir beaucoup de service et que les fichiers sont « logrotatées », ça devient vite illisible.
+Traditionnellement, les logs HTTP sont dans ''/var/log/apache2/'' ou ''/var/log/nginx/''.
+C'est bien.
+Mais comme on est susceptible d'avoir beaucoup de services et que les fichiers sont //logrotated//, ça devient vite illisible.
 Conventions techniques recommandées :
-  * pour chaque site web, créer un dossier dédié pour les logs : ''/var/log/apache2/foo.chapril.org/'' ;
+  * Pour chaque site Web, créer un répertoire dédié pour les logs : ''/var/log/apache2/foo.chapril.org/'' ;
-  * nommage du fichier de log nominal : ''foo.chapril.org-access.log'' ;
+  * Nommage du fichier de log nominal : ''foo.chapril.org-access.log'' ;
-  * nommage du fichier de log erreurs : ''foo.chapril.org-error.log''.
+  * Nommage du fichier de log erreurs : ''foo.chapril.org-error.log''.
 Exemples :
+<code bash>
+cd /var/log/apache2/
+ll */*access*log
+</code>
 <code>
-=(^-^)=root@lamp:/var/log/apache2# ll */*access*log
 -rw-r----- 1 root adm 2562895 janv.  9 09:22 banner.chapril.org/banner.chapril.org-access.log
 -rw-r----- 1 root adm 3692761 janv.  9 09:23 date.chapril.org/date.chapril.org-access.log
@@ Ligne 77: / Ligne 64: @@
 -rw-r----- 1 root adm 2105783 janv.  9 09:22 v2.chapril.org/v2.chapril.org-access.log
 -rw-r----- 1 root adm 5313214 janv.  9 09:23 www.chapril.org/www.chapril.org-access.log
-=(^-^)=root@lamp:/var/log/apache2# ll */*error*log
+</code>
+<code bash>
+cd /var/log/apache2/
+ll */*error*log
+</code>
+<code>
 -rw-r----- 1 root adm   4093 janv.  9 01:19 banner.chapril.org/banner.chapril.org-error.log
 -rw-r----- 1 root adm 206183 janv.  9 09:23 date.chapril.org/date.chapril.org-error.log
@@ Ligne 85: / Ligne 77: @@
 -rw-r----- 1 root adm  23273 janv.  9 08:13 www.chapril.org/www.chapril.org-error.log
 </code>
+===== Format des logs HTTP ? =====
+Pour profiter des adresses IP //proxifiées//, activer le ''combined'' :
+<file apache /etc/apache2/sites-available/foo.chapril.org.conf>
+# Spécifique au service foo.chapril.org
+CustomLog ${APACHE_LOG_DIR}/foo.chapril.org/foo.chapril.org-access.log combined-proxy
+</file>
+===== Les autres fichiers de logs ? =====
+Pour le projet ''foo.chapril.org'', les mettre dans le répertoire ''/var/log/foo.chapril.org/''.
 ===== Home Directory du service ? =====
-Tout service a son « home directory » dans ''/srv/'' avec comme nom le nom complet du service. Le dossier ne sera jamais //gitifié//. L'idée est d'avoir un espace dédié aux fichiers du service, ceux d'exploitation ou simplement de maintenance (exports SQL…).
+Tout service ''foo.chapril.org'' a son //home directory// dans ''/srv/'' avec comme nom le nom complet du service.
+Le dossier ne sera jamais //gitifié//.
+L'idée est d'avoir un espace dédié aux fichiers du service, ceux d'exploitation ou simplement de maintenance (exports SQL…).
 Exemples :
+<code bash>
+cd /srv/
+ll
+</code>
 <code>
-=(^-^)=root@lamp:/srv# ll
 total 16
 drwxr-xr-x 2 root            root            4096 juil. 18 23:46 bin
@@ Ligne 100: / Ligne 109: @@
 </code>
-Dans ce dossier, on trouvera notamment :
+Dans ce répertoire, on trouvera notamment :
-  * un dossier ''tools'' : dépôt Git pour les scripts nécessaires à l'exploitation (sondes, rapport d'activité, autres…) ;
+  * Un répertoire ''tools/'' : dépôt Git pour les scripts nécessaires à l'exploitation (sondes, rapport d'activité, autres…) ;
   * des liens :
-    * www : vers le ''DocumentRoot'' du site du service,
+    * ''www/'' : vers le ''DocumentRoot''%%*%% du site du service,
-    * un vers le fichier cron.d s'il y en a un,
+    * Un vers le répertoire ''/etc/cron.d/'' s'il y en a un.
-    * …
+%%*%% La variable ''DocumentRoot'' est définie dans ''/etc/apache2/sites-available/foo.chapril.org.conf''.
 ===== Compte système du service ? =====
@@ Ligne 111: / Ligne 121: @@
 La création d'un utilisateur système dédié au service est optionnelle et dépend des besoins du service, de son déploiement et de son exploitation.
-Convention :
+Convention pour un service ''foo.chapril.org'' :
-  * nom du compte : prendre le nom complet du service sans les points (exemple : foochaprilorg) ;
+  * Nom du compte : prendre le nom complet du service sans les points comme ''foochaprilorg'' ;
-  * type de compte : donner le type système au compte ;
+  * Type de compte : donner le type système au compte ;
-  * shell : assigner ''/bin/false'' ou la valeur nécessaire au service ;
+  * Shell : assigner ''/bin/false'' ou la valeur nécessaire au service ;
-  * home directory : /srv/foo.chapril.org/
+  * //Home directory// : ''/srv/foo.chapril.org/''.
 ===== Base de données du service ? =====
-Nommages :
+L'idéal serait un nommage parlant :
-  * la base : ''foochaprilorg_redmine''_db ou ''foochaprilorg_bare_db'' ;
+  * La base : ''foochaprilorg_redmine_db'' ou ''foochaprilorg_bare_db'' ;
-  * le compte Mariadb : foochaprilorg_dbadmin.
+  * Le compte MariaDB : ''foochaprilorg_dbadmin''.
+Mais dans la pratique, on peut se simplifier la vie :
+  * La base : ''nomduproduit_db'' comme ''kanboard_db'' ou ''framadate_db'' ;
+  * Le compte : ''nomduproduit'' comme ''kanboard'' ou ''framadate''.
 ===== Partition dédiée du service ? =====
-Dans le cas d'un service nécessitant beaucoup d'espace disque, alors créer une partition dédiée. Cette partition ''data'' ne devra contenir que des données, pas de code de l'application du service.
+Dans le cas d'un service nécessitant beaucoup d'espace disque, on peut créer une partition dédiée.
+Cette partition de donnée ne devra contenir que des données, pas le code source de l'application du service.
-Exemple : https://admin.chapril.org/doku.php?id=admin:chatons:drop.chapril.org#preparation
+Suivre [[admin:services:drop.chapril.org#preparation|l’exemple du service Drop]].
+===== Quelle configuration SMTP ? =====
+L'équipe infra gère le flux de courriel.
+Configuration à faire : ''localhost'' sur le port ''25''.
 ===== Courriel du service ? =====
@@ Ligne 138: / Ligne 155: @@
 En cas de demande d'information sur ce courriel, ouvrir un ticket de traçage en prenant garde soit de masquer les informations sensibles, soit en cochant « privé » à la création du ticket.
-===== Nommage branche Chapril =====
+===== Tâches Cron ? =====
-Pour certains services, la personnalisation passe par la modification du code du service. Afin de suivre et pouvoir propager les modifications dans les futures versions, la mise sous Git du code est nécessaire (si ce n'est pas déjà fait).
+La sagesse unixienne recommande aux utilisateurs de passer par ''crontab -u user -e'' pour déclarer une tâche Cron sans perturber le système.
+C'est vraiment une bonne idée.
+Sauf que sur nos VM, nous ne sommes pas des utilisateurs mais des **adminsys**.
+Et même si certains services tournent sous un compte Unix dédié, il s'agit d'un compte système et non d'un compte utilisateur classique.
-À ce moment là, il faut créer une branche dédiée au Chapril nommée chapril-x.y.z en reprenant le numéro de la version du projet officielle.
+En conséquence, les recommandations sont les suivantes :
-===== Puis-je assigner un ticket ? =====
+  * Les tâches Cron sont à déclarer dans ''/etc/cron.d/'' ;
+  * les tâches Cron sont à mettre dans un ou plusieurs fichiers dédiés au service ;
+  * Le nommage doit reprendre le nom du service (''foochaprilorg'', ''foochaprilorg-bare'' etc.) ;
+  * Penser à //commiter// en cas de modification%%*%% ;
+  * //Logger// la tâche Cron%%**%%.
-En tant qu'animateur d'un service, bien sûr. Cela reste de la communication, au pire la personne le réassignera. Le mieux étant de la contacter avant.
+%%*%%  Penser à bien configurer son SSH pour transférer les variables d’environnement Git nécessaires.
+%%**%% Exemple : ''…/task.sh >> /var/log/foo.chapril.org/bar.log 2>&1''.
+Exemples de nommage :
+<code bash>
+cd /etc/cron.d/
+ll
+</code>
+<code>
+total 16
+-rw-r--r-- 1 root root  63 juil. 18 16:30 backup
+-rw-r--r-- 1 root root 375 janv.  6 23:10 datechaprilorg
+-rw-r--r-- 1 root root 134 déc.   7 10:48 pastechaprilorg
+-rw-r--r-- 1 root root 712 janv.  1  2017 php
+</code>
+Avantages :
+  * Facilité d'accès pour les adminsys quand ils cherchent le fichier Cron d'un service ;
+  * Historisation et traçabilité de la configuration ;
+  * Alertes Icinga2 si oublie de //commit// ;
+  * Sauvegarde automatique.
+===== Forge de l'infrastructure du Chapril =====
+La forge de l'infrastructure du Chapril est en dehors de son infrastructure pour plus de résilience si celle-ci n'est plus accessible.
+Elle permet de conserver et faire évoluer :
+  * Les modifications sur un service qui ne sont pas dans la version officielle de son logiciel%%*%% ;
+  * Les outils de monitoring (surveillance) et les rapports d'activités.
+En équipe, plusieurs contributeurs peuvent faire évoluer les sources.
+%%*%% Par exemple sur Paste des modifications ont lieu par rapport au logiciel Privatebin.
+===== Dépôt Git d’un service =====
+Un service ''foo.chapril.org'' peut être associé à un ou plusieurs dépôts Git gérés par le groupe de travail [[https://forge.april.org/Chapril/|Chapril dans forge interne de l’April]].
+Ces dépôts ont pour nom ''foo.chapril.org-tools'' pour l’outillage du service et ''foo.chapril.org-AUTRE'' quand ''AUTRE'' est un autre programme associé au service.
+Un tel dépôt externalise la gestion des tickets vers [[https://agir.april.org/|le service Agir de l’April]].
+Pour externaliser il suffit de paramétrer depuis la page //Paramètres// du dépôt, dans l’onglet //Dépôt// puis la section //Paramètres avancés//.
+On utilise alors un système de suivi de tickets externe avec pour adresse ''%%https://agir.april.org/projects/foo-chapril-org/issues%%''.
+L’URL de ce système sera ''%%https://agir.april.org/issues/{index}%%'' et le format du nombre de tickets sera numérique.
+Ce dépôt peut exporter aussi son wiki pour sa documentation vers [[https://wiki.april.org/|le wiki interne de l’April]].
+Toujours depuis la section //Paramètres avancés// on utilisera un wiki externe dont l’URL sera ''%%https://wiki.april.org/w/Chapril:services:foo:guide%%''.
+Les [[https://forge.april.org/adminsys/forge.april.org-faq/src/branch/master/README.md|FAQ de la forge de l’April]] peuvent ajouter quelques recommandations.
+===== Nommage de branche Chapril =====
+Pour certains services, la personnalisation passe par la modification du code du service.
+Afin de suivre et pouvoir propager les modifications dans les futures versions, la mise sous Git du code est nécessaire (si ce n'est pas déjà fait).
+À ce moment là, une branche dédiée au Chapril doit être créée et nommée ''main-chapril''.
+Pour chaque version ''x.y.z'' du dépôt d’origine une étiquette ''chapril-x.y.z'' est créée après la personnalisation du code pour le Chapril.
+Ces étiquettes doivent faciliter la mise à jour du service hébergé dans la VM via la commande ''git checkout''.
+===== Puis-je assigner un ticket ? =====
+En tant qu'animateur d'un service, bien sûr.
+Cela reste de la communication, au pire la personne le réassignera.
+Le mieux étant de la contacter avant.
 ===== Jardinage/revue des tickets ? =====
-Les tickets ne sont pas le cœur du projet. Le cœur du projet, ce sont l'équipe, les utilisateurs et les services. Les tickets servent à construire une image de où on en est. Donc ce n'est pas la priorité mais quand même bien nécessaire pour suivre et assurer une qualité à l'activité.
+Les tickets ne sont pas le cœur du projet.
+Le cœur du projet, ce sont l'équipe, les utilisateurs et les services.
+Les tickets servent à construire une image de où on en est.
+Donc ce n'est pas la priorité mais quand même bien nécessaire pour suivre et assurer une qualité à l'activité.
 Quelques principes :
-  * un ticket non assigné est un ticket en souffrance ;
+  * Un ticket non assigné est un ticket en souffrance ;
-  * ne pas laisser trop longtemps les tickets en statut « Résolu » ;
+  * Ne pas laisser trop longtemps les tickets en statut « Résolu » ;
-  * …
 ===== Besoin d'une action infra ? ======
-L'organisation du Chapril est faite pour faciliter la vie des animateurs de services. Besoin d'une action en dehors de la vm du service ? Alors interpeler un membre de l'équipe infra :D
+L'organisation du Chapril est faite pour faciliter la vie des animateurs de services.
+Besoin d'une action en dehors de la VM du service ?
+Alors interpeler un membre de l'équipe infra. :D
-===== Module FPM vs open_basedir ? ======
+===== Module FPM vs ''open_basedir'' ? ======
 Par simplicité, si possible, privilégier la directive ''php_admin_value open_basedir''.
 ===== Réception d'un courriel sur l'adresse de support ? ======
-Chaque service du Chapril a son courriel de support : foo-support@chapril.org.
+Chaque service du Chapril a son courriel de support : ''foo-support@chapril.org''.
-Et parfois, des utilisateurs écrivent à cette adresse. Voici un plan de traitement :
+Et parfois, des utilisateurs écrivent à cette adresse.
-  * 1) répondre en privé :
+Voici un plan de traitement :
-    * expéditeur :
-      * utiliser son courriel @april.org, c'est l'idéal,
-      * éviter **absolument** d'utiliser une adresse GAFAM ou FAI,
-    * en copie :
-      * foo-support@chapril.org
-    * contenu :
-      * dire qui l'on est :
-  Bonjour […] je suis l'animateur du service foo.chapril.org…
+  - Répondre en privé :
+    * Expéditeur :
+      * Utiliser son courriel ''@april.org'', c'est l'idéal,
+      * Éviter **absolument** d'utiliser une adresse de GAFAM ou de FAI ;
+    * Copie carbone :
+      * ''foo-support@chapril.org'',
+      * Contenu : dire qui on est%%*%% ;
+  - Créer un ticket :
+    * Objet : copiercollerlesujetducourrielavecescrochets,
+    * Description : copier/coller le courriel en anonymisant un peu%%**%%,
+    * Ajouter en commentaire le copier/coller de votre réponse ;
+  - Partager sur ''chapril@'' si le sujet est pertinent %%***%%.
-  * 2) créer un ticket :
+%%*%% Modèle de courriel de réponse :
-    * sujet : « date-support : copiercollerlesujetducourriel »
+<code>
-    * description : copier/coller le courriel en anonymisant un peu :
+  Bonjour Ada,
+  Je suis Christian Momon, l'animateur bénévole du service foo.chapril.org. Nous sommes
+heureux que nos services numériques libres, éthiques et loyaux puissent vous être utiles.
+ [réponse à la demande]
+ En vous souhaitant, au nom de toute l'équipe du Chapril, un agréable
+usage de nos services libres, éthiques et loyaux.
+ Librement,
+ Christian (Cpm).
+</code>
+%%**%% Modèle de description :
+<code>
   Le 20/01/2010, Laurence R. a écrit sur foo-support@chapril.org :
     Bonjour,
     […]
+</code>
-    * ajouter en commentaire le copier/coller de votre réponse
-  * 3) partager sur chapril@
-    * si le sujet est pertinent : par exemple, en cas de remerciements, ça fera toujours plaisir à l'équipe :-)
+%%***%% Par exemple, en cas de remerciements, ça fera toujours plaisir à l'équipe. :-)
-    * …
+===== Charset des bases de données ? ======
-===== Charset des bases de donneés ? ======
+Privilégier l'encodage UTF8.
+Par exemple, avec MySQL ou MariaDB, systématiquement faire du ''utf8mb4''.
-Privilégier l'UTF8. Par exemple, avec Mysql/MariaDB, systématiquement faire du utf8mb4. Ça permet de gérer les émoticons dans la base.
+Ça permet de gérer les émojis dans la base.
+Ça permettra surtout d'éviter des migrations de bases…
 Exemple :
-<code>
+<code sql>
 CREATE DATABASE IF NOT EXISTS gitea_db DEFAULT CHARACTER SET utf8mb4 COLLATE 'utf8mb4_unicode_ci';
 </code>