# dalidoc `dalidoc` est la chaine de production de documents de DALIBO. Elle est basée sur les outils open-source suivants: * [pandoc] * [pandocker] * [mkdocs] * Le template latex [eisvogel] * Le template HTML uikit * Le template HTML revealjs Ce projet est surcouche qui coordonne tous ces outils et facilite leur utilisation. [pandocker]: https://github.com/dalibo/pandocker [eisvogel]: https://github.com/Wandmalfarbe/pandoc-latex-template [pandoc]: https://pandoc.org/ [mkdocs]: https://www.mkdocs.org/ ## Pré-requis Pour utiliser dalidoc, il faut installer les outils suivants: * [docker] * `git`, `gawk`, `rsync` et `make` * [uv] pour gérer le virtualenv python de mkdocs * [powerline.bash] est optionnel mais recommandé La version stable de [pandocker] est automatiquement téléchargée et utilisée. [uv]: https://docs.astral.sh/uv/ [powerline.bash]: https://gitlab.com/bersace/powerline.bash [docker]: https://docs.docker.com/engine/install ## Démarrer 1. Installer dalidoc en tant que sous-module à l'intérieur de votre projet : ``` git config --global submodule.recurse true git submodule add ../../../dalibo/dalidoc ``` L'option `--global` est très pratique mais totalement optionnelle, il est possible d'activer la récursion au cas par cas. > IMPORTANT: Le chemin du submodule dalidoc est relatif à celui de votre > projet dans l'arborescence de l'instance gitlab. 2. Récupérer les fichiers de configuration modèle depuis le sous-module dalidoc : ``` rsync -a dalidoc/templates/project/ . ``` 3. Vérifier que le Makefile fonctionne ``` make help ``` 4. Lancer la création des PDF ``` make pdf ``` ## Cloner un projet client Penser à ajouter l'option `recursive` lorsque l'on clone un dépôt client: ``` git clone --recurse-submodules git@gitlab.dalibo.info:clients/00xxx-foobar/projet.git ``` ## Vérifier la version de dalidoc Dans le répertoire `dalidoc` : ``` make check_dalidoc ``` ## Monter la version de dalidoc ``` git -C dalidoc fetch origin # vérifier la dernière version sur https://gitlab.dalibo.info/dalibo/dalidoc/-/tags git -C dalidoc checkout 5.0.2 ``` ## Si le dossier dalidoc est vide Cela signifie probablement que le dépôt n'a pas été cloné en mode récursif. Si ton dossier dalidoc était vide, cela signifie probablement que tu n'avais pas activé le récursion Vérifier la config `git` et activer l'option `submodule.recurse`: ``` git config --get submodule.recurse git config --global --get submodule.recurse ``` > Noter que l'option `--global` est très pratique mais totalement optionnelle, > il est possible d'activer la récursion au cas par cas Puis réparer en récupérant le conteneur du submodule avec la commande: ``` git submodule update --init --recursive ``` ## Linting Optionnellement on peut activer la vérification syntaxique avec [rumdl]. La vérification peut se faire à plusieurs niveaux : 1. dans l'éditeur : [rumdl-vim], [rumdl-vscode], etc. 2. via le hook de pre-commit ( `uv run prek install --config .pre-commit-config.yaml` 3. en tapant `make lint` 4. dans les pipelines de gitlab-ci Pour Gitlab-CI, activer le configuration suivante: ```yaml include: - project: 'dalibo/dalidoc' file: - 'ci/lint.yml' ``` Les [règles syntaxiques] communes sont définies dans le fichier `dalidoc/.rumdl.toml`. [rumdl-vim]: https://github.com/rvben/rumdl#editor-integration [rumdl-vscode]: https://github.com/rvben/rumdl-vscode [règles syntaxiques]: https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md ## Makefile Le `Makefile` du projet utilisateur peut se résumer à : ``` DALIDOC?=./dalidoc include $(DALIDOC)/Makefile ``` Un modèle de Makefile générique est disponible dans le dossier `dalidoc/templates/project/` : ``` cp dalidoc/templates/project/Makefile . ``` ## Gitlab-ci.yml Pour activer la compilation dans Gitlab, recopier le fichier `.gitlab-ci.yml` qui se trouve dans le dossier `dalidoc/templates/project/` ``` cp dalidoc/templates/project/.gitlab-ci.yml . ``` Ou télécharger le fichier à l'adresse ci-dessous: ## Proposer ou demander une évolution ## Publier le portail client Le "portail client" est un mini-site privé qui vous permet de transmettre à ce client les documents produits pendant un audit ( CR, rapports pgbadger, playbooks ansible, etc. ) et les procédures pour les clients ayant l'option REMOTEDBA (anciennes fiches KB privées). **Chaque projet support mantis est lié à 1 contrat support ERP qui est lié à 1 projet gitlab qui est lié à 1 portail client.** L'adresse du portail est similaire au namespace du projet gitlab. Par exemple, pour le projet le portail sera disponible sur : Chaque client peut accéder au portail de son projet en s'authentifiant avec ses code d'accès de la plateforme . Chaque salarié.e de DALIBO peut accéder à tous les portails avec ses codes d'accès SSO (`auth.dalibo.com`). Chaque consultant est responsable du contenu qu'il souhaite publier (ou pas) sur le portail. **IMPORTANT** : Le portail n'est **pas mis à jour au Merge d'une MR**, mais **quand un tag est posé** sur le dépôt gitlab, soit avec `git tag CR20261231 / git push --tags`, soit dans Gitlab/_Code_/_Tags_. Pour suivre le déploiement, aller voir dans les pipelines de Gitlab. ### Démarrage 1. Passer à dalidoc 5 (ou plus) ``` bash make check_dalidoc git -C dalidoc fetch origin git -C dalidoc checkout 5.x.y git commit dalidoc -m "Passage à dalidoc 5" ``` 2. Recopier le template de la page de portail ``` bash cp -pr dalidoc/templates/project/portal . cp dalidoc/templates/project/.gitlab-ci.yml . cp dalidoc/templates/project/.gitignore . ``` 3. Si les images ne sont pas dans le dossier "medias", ouvrir le Makefile et ajouter la ligne en haut du fichier (remplacer "img" par le nom du dossier) ``` ini DALIDOC_MEDIAS_DIR=img ``` 3. Éditer la page d'index (`portal/index.md`) et ajuster selon le contexte du client. 4. Committer et pousser ``` bash git add portal git commit -a -m 'Activation du portail' git push ``` 5. Voir sur validdelivery.dalibo.com le résultat (cf plus bas) (pour la production, il manque encore un tag). ### Ajouter un nouveau CRA / CRI * Rédiger le CRA/CRI comme d'habitude. * Mettre les images dans le dossier `medias` * Éditer le fichier `portal/index.md` et ajouter un lien vers le nouveau CR ```markdown * Intervention du JJ/MM/AAAA [:fontawesome-solid-globe:](DLB-00000-000-CRA-0000.md) [:fontawesome-solid-file-pdf:](DLB-00000-000-CRA-0000.pdf) ``` * Commiter, pousser * Contrôler sur validdelivery.dalibo.com * Pour livrer au client, ne pas oublier le tag. ### Ajouter un rapport pgbadger (ou autres) * Déposer le fichier `pgbadger_machin_truc.zip` dans le dossier `portal/rapports` * Editer le fichier `portal/index.md` et décommenter la section `rapports` ### Ajouter une procédure (ex: KB privée du client) * Créer un fichier `portal/procedures/machin_truc.md` * Editer le fichier `portal/index.md` et décommenter la section `procédures` > Les docs markdown situés dans le dossier `portal` NE sont PAS convertis > en PDF via pandoc ! On peut considérer que ce sont des pages wiki gérées > via git. ### Archiver des vieux documents Quand un CR est trop vieux, il n'est plus nécessaire de le recompiler à chaque fois. On peut le placer dans un dossier d'archivage. Pour un CR nommé "DLB-00000-000-CRT-0000.md", datant de 2019 : * Créer le dossier `portal/archives/2019` * Compiler le fichier PDF avec `make DLB-00000-000-CRT-0000.pdf` * `git mv DLB-00000-000-CRT-0000.md portal/archives/2019/` * `mv DLB-00000-000-CRT-0000.pdf portal/archives/2019/` * `git add portal/archives/2019/DLB-00000-000-CRT-0000.pdf` * Editer le fichier `portal/index.md` et décommenter la section `Archives` ## Modifier la configuration du portail Il est possible de changer la barre de navigation horizontale ou d'autres paramètres du portail et éditant le fichier `portal/mkdocs.yml` ### Compiler le portail en local [Installer uv](https://docs.astral.sh/uv/getting-started/installation/). Lancer la compilation des docs puis du portail ```bash make docs portal ``` Le portail se trouvera dans le dossier `_site` ### Compiler en CI Lorsqu'un dossier `portal` est présent la chaîne de CI va le compiler et le publier **à chaque commit** sur le portail de validation (`validdelivery.dalibo.com`) L'adresse du portail de la validation est similaire au namespace du projet gitlab. Par exemple, pour le projet clients/00828-fiducial/cr-fiducial> le portail sera disponible sur: Les clients NE peuvent PAS accéder au portail. Il est accessible uniquement via le VPN Si vous travaillez sur plusieurs MR en simultanée, la version publiée sur `validdelivery.dalibo.com` est celle de la dernière pipeline ayant réussie. ### Si ça ne marche pas * Vérifier que vous êtes passé à dalidoc 5.0 ou plus * Vérifier que le champs `Projet gitlab` est correctement renseigné sur la fiche du contrat dans l'ERP. (A voir avec Bertrand) * Pour `validdelivery.dalibo.com`, vérifier que le VPN est actif * Pour `delivery.dalibo.com`, vérifier qu'un tag a été posé sur le dépot ## Paramètres optionnels ### Ajouter de nouveau formats d'export Par défaut la cible `make docs` produit uniquement l'export pdf. Pour changer cela, ouvrir le Makefile et décommenter la variable `DALIDOC_TARGET_FORMATS` ``` DALIDOC_TARGET_FORMATS?= pdf odt epub ``` ### Ignorer les vieux fichiers source Par défaut, tous les fichiers markdown sont compilés... En général, on souhaite compiler uniquement le plus récent. Décommenter la variable `DALIDOC_IGNORE_OLDER_THAN` et préciser le nombre de jours d'ancienneté à partir duquel les fichiers seront ignorés... ``` DALIDOC_IGNORE_OLDER_THAN?=90 ``` Dans ce cas, seuls les fichiers modifiés il y a moins de 90 jours seront compilés... ## BONUS : Usages alternatifs ### Utiliser dalidoc pour d'autres projets Lorsque que l'on ajoute le sous-module, il faut utiliser un chemin relatif plutot que l'url du dépot [dalidoc] Concrètement il faut faire: ```console git submodule add -b stable ../../../dalibo/dalidoc ``` au lieu de : ```console git submodule add git@gitlab.dalibo.info:dalibo/dalidoc.git ``` La commande ci-dessus peut sembler plus élégante et plus logique mais **elle ne fonctionnera pas** avec Gitlab-CI. En effet, le chemin relatif (`../../../dalibo/dalidoc`) qui est donné ici représente l'emplacement du projet [dalidoc] **sur le serveur gitlab** **par rapport à un dépot de CR**. Ce n'est pas un chemin relatif à l'arborescence des fichiers locaux ! Concrètement dans le dépot projet `/clients/01518-cbnmed/cr-cbnmed`, la commande `git submodule add ../../../dalibo/dalidoc` entrainera un git checkout de l'URL suivante: `git@gitlab.dalibo.info:/clients/01518-cbnmed/cr-cbnmed/../../../dalibo/dalidoc` Cette URL sera automatiquement retraduite en `git@gitlab.dalibo.info:/dalibo/dalidoc` La valeur indiquée dans le fichier`.git/config` est la "traduction" de cette URL mais c'est bien le fichier `.gitmodules` qui reste la référence et qui contient le chemin relatif : ``` $ grep dalidoc .gitmodules [submodule "dalidoc"] path = dalidoc url = ../../../dalibo/dalidoc $ grep dalidoc .git/config [submodule "dalidoc"] url = git@gitlab.dalibo.info:dalibo/dalidoc ``` C'est pour cela que ce chemin relatif fonctionne même si on n'a pas cloné le dépot `dalibo/dalidoc` localement ! Dès lors, ce chemin relatif devra être adapté lorsqu'on utilise [dalidoc] pour un dépôt ayant une arborescence différente. Par exemple pour le dépôt `formation/workshops>` le chemin du sous-module sera `../../dalibo/dalidoc` Quoiqu'il en soit, cela n'a pas d'impact sur l'organisation de vos dossiers sur votre machine locale. **Vous pouvez cloner vos dépôts où vous voulez** ### Dalidoc et SELinux > Attention: L'usage de dalidoc avec SELinux n'est pas officiellement supporté. Si `SELinux` est activé sur votre poste, [pandocker] sera entravé et dalidoc ne fonctionnera pas. Dans ce cas, trois solutions sont possibles: * Désactiver SELinux * Utiliser l'[option --privileged de docker] * Configurer le [mode rootless de docker] Voir le ticket [ticket #48] pour plus de détails [option --privileged de docker]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities [mode rootless de docker]: https://docs.docker.com/engine/security/rootless/ [ticket #48]: https://gitlab.dalibo.info/dalibo/dalidoc/-/issues/48 ### Dalidoc et podman > Attention: L'usage de dalidoc avec podman n'est pas officiellement supporté. podman est une alternative à docker. Il est possible de faire fonctionner [pandocker] avec podman en suivant les conseils du [ticket #48]. Néanmoins `podman` n'est pas testé en CI et il n'y a pas d'engagement à fournir une résolution rapide en cas de problème...