diff --git a/README.md b/README.md index b43756940b00ec72851debb22478d1894c7e7d25..9eac24703bfbd399d832e1df83b3f4d597888c43 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,31 @@ Ce dépôt centralise les Dockerfiles et autre ressources utilisées pour construire **et** déployer les images Docker tournant en production sur l'infrastructure de Picasoft. +## Philosophie + +Historiquement, Picasoft procède de la manière suivante : +* Construire ses Dockerfile à la main et les pousser sur un registre privé. +* Gérer un Docker Compose global par VM, qui contient la configuration et les secrets. + +Cette approche pose plusieurs problèmes. Comment savoir ce qu'il y a dans une image, si on perd le Dockerfile ? Quel Dockerfile correspond à quelle version de l'image ? Si on perd l'accès à la machine, comment récupérer la configuration, remonter rapidement le service ? Comment versionner les changements de configuration ? Revenir à la version d'il y a deux semaines ? + +L'objectif de ce dépôt est de rendre possible le déploiement de n'importe quel service Picasoft avec la procédure suivante : +* Cloner le dépôt +* Se rendre dans le répertoire du service +* Lancer un `docker-compose up -d` + +Son objectif secondaire est de pouvoir revenir à l'état antérieur d'un service. En versionnant toute la configuration nécessaire, revenir à une ancienne version du service revient à : +* Cloner le dépôt +* Checkout un commit quelconque +* Lancer le service normalement + +Pour y arriver, il construit automatiquement les images de l'ensemble des services et les met à disposition sur un registre, avec une version. Mise à part les données à proprement parler du service, il n'y a donc aucune différence entre un service lancé sur une de nos machines et un service lancé à partir de ce dépôt sur une machine virtuelle quelconque, ce qui s'inscrit dans la philosophie Docker. + ## Contenu du dépôt Ce dépôt contient toutes les ressources permettant de déployer les services que nous maintenons sur n'importe quelle machine virtuelle de l'infrastructure de Picasoft, sans prérequis. -Cela signifie que le bon fonctionnement d'un service n'est pas dépendant de la machine virtuelle sur laquelle on essaye de le lancer (en adéquation avec la philosophie Docker). +Cela signifie que le bon fonctionnement d'un service n'est pas dépendant de la machine virtuelle sur laquelle on essaye de le lancer. Ainsi, chaque service versionné sur ce dépôt contiendra : @@ -23,19 +43,19 @@ Un exemple concret peut être trouvé au niveau de [pica-mattermost](./pica-matt ## Mais je commence par où, bordel ? -On peut vite se perdre sur ce dépôt, en fonction de ce que l'on veut faire. +Ce dépôt peut faire peur, mais pour la plupart des usages il est très simple à exploiter. ### Je veux lancer un service existant sur une machine virtuelle -Si le service que vous souhaitez lancer est référencé sur ce dépôt, la documentation pour le tester et le déployer se trouve [ici](./doc/guide_deploiement.md). +Si le service que vous souhaitez lancer est référencé sur ce dépôt, lisez [la documentation pour le tester et le déployer](./doc/guide_deploiement.md). ### Je veux mettre à jour un service -Il faut pour cela utiliser la chaîne d'intégration de ce dépôt, qui construit automatiquement les images Docker. La documentation utilisateur se trouve [ici](./doc/guide_utilisateur_ci.md). +Il faut pour cela utiliser la chaîne d'intégration de ce dépôt, qui construit automatiquement les images Docker. [Lisez la documentation utilisateur de la chaîne d'intégration.](./doc/guide_utilisateur_ci.md). ### Je veux mettre en place un nouveau service -Il faudra d'une part respecter les conventions utilisées par la chaîne d'intégration, qui sont disponibles [ici](./doc/guide_developpeur_ci.md#formalisme-du-dpt). +Il faudra d'une part [respecter les conventions utilisées par la chaîne d'intégration](./doc/guide_developpeur_ci.md#formalisme-du-dpt). Ensuite, il faudra jeter un oeil [aux bonnes pratiques](./doc/guide_bonnes_pratiques.md) à l'oeuvre sur l'infrastructure de Picasoft. @@ -43,4 +63,4 @@ Un dossier [template](./template) prêt à copier est aussi disponible. ### Je veux améliorer la chaîne d'intégration -Il existe une documentation "développeur" pour la chaîne d'intégration, qui rentre plus en détail, disponible [ici](./doc/guide_developpeur_ci.md). +Lisez la [documentation "développeur" pour la chaîne d'intégration](./doc/guide_developpeur_ci.md), qui rentre plus dans le détail. diff --git a/doc/guide_bonnes_pratiques.md b/doc/guide_bonnes_pratiques.md index c9b46ff104bca93d4cdf9963c9bab28a5b98d08b..97675d95a1754f511a1ad24b6cad7f851470eb83 100644 --- a/doc/guide_bonnes_pratiques.md +++ b/doc/guide_bonnes_pratiques.md @@ -41,6 +41,19 @@ Allez-y ! :D Une [série de recommendations](https://wiki.picasoft.net/doku.php?id=technique:docker:tips) est disponible ici pour l'écriture des Dockerfile. +## Builds reproductibles + +L'idée derrière un build "reproductible", c'est que si je me rends sur un ancien commit de ce dépôt et que je lance un `docker build` dans un dossier, comme `pica-mattermost`, l'image finale doit être la même quel que soit le temps écoulé depuis ce commit. Pourquoi ? Pour pouvoir relancer le build d'une ancienne version et la remettre en production en cas de problème. + +Souvent, un Dockerfile va récupérer du code sur un dépôt Git, ou encore un binaire sur un site de téléchargement de releases. +Il est fortement déconseillé de faire un `git clone` ou un `wget` de la dernière version (`latest`, `master`...), ce qui rend le build non reproductible et dépendant de cette dernière version. + +Il est donc important de gérer la version du service en question, par exemple avec une variable `ENV SERVICE_VERSION=1.0.1` qui sera ré-utilisée dans l'URL de téléchargement. + +En outre il existe deux solutions pour récupérer du code existant, versionné sur un dépôt Git distant : +* Installer Git dans le Dockerfile, utiliser un `git clone` puis un `git checkout <tag>` sur la version souhaitée et copier le code dans l'image. +* Utiliser un [submodule](https://git-scm.com/book/fr/v2/Utilitaires-Git-Sous-modules) dans le dossier du service, en particulier si le dépôt où se trouve le code est de petite taille et qu'il n'utilise pas les tags. En effet, comme un submodule est lié à un numéro de commit, chaque commit de ce dépôt sera associé à un commit précis du dépôt distant. On peut donc retrouver l'état du code distant avec le numéro de commit du submodule associé au commit local. + ## Volumes Une fois que l'on a identifié les dossiers du conteneur où l'on a besoin de persistence, il y a plusieurs manières de procéder : diff --git a/doc/guide_deploiement.md b/doc/guide_deploiement.md index 7438c178f8eef0eecea533c2489bcbe3541aac8c..4fc5fb42f7bda7a3b946cd7b3fecee43a5ee6d77 100644 --- a/doc/guide_deploiement.md +++ b/doc/guide_deploiement.md @@ -8,11 +8,13 @@ Avant de mettre un service en production, il faut vérifier que le service se la Il faut être connecté au registre de test pour la suite : on s'assure de bien avoir exécuté la commande `docker login registry.test.picasoft.net`. Les identifiants sont sur le [pass](https://gitlab.utc.fr/picasoft/interne/pass). -Pour que le service réponde à nos critères, il faut s'assurer qu'il démarre **indépendamment** de ce qui existe sur la machine. Le script [`docker_test.sh`](./docker_test.sh) s'occupe de tout cela pour vous. +Pour que le service réponde à nos critères, il faut s'assurer qu'il démarre **indépendamment** de ce qui existe sur la machine. Le script [`docker_test.sh`](./docker_test.sh) s'occupe de tout cela pour vous, tout en s'assurant que les URL soient adaptés à la machine de test, par exemple. Il suffit de lancer la commande `$ ./docker_test.sh <nom du dossier, e.g. pica-mattermost>`. Vérifiez que les logs ne produisent aucune erreur et que le service fonctionne bien sur l'infrastructure de test. +En cas d'erreur, vous pouvez lancer des commandes manuellement, relancer le service, changer les fichiers de configurations, etc, pour diagnostiquer. + ## Déploiement en production Lorsque le test a fonctionné, on se rend sur la page [Pipelines](https://gitlab.utc.fr/picasoft/projets/dockerfiles/pipelines) on choisit la pipeline correspondant au commit de modification que l'on a testé, et on lance le push de l'image sur le registre de production (`push-prod`). @@ -84,10 +86,9 @@ Error: No such image: postgres:9.4-alpine Pulling mattermost-db ... done Pulling mattermost ... done -==== Lauch pica-mattermost/ and restore repository ==== +==== Lauch pica-mattermost ==== Creating mattermost-db ... done Creating mattermost-app ... done -HEAD is now at 472e0d7 [Mattermost] Bump to version 5.19.0 ==== Print logs (use Ctrl+C to stop) ==== Attaching to mattermost-app, mattermost-db diff --git a/doc/guide_utilisateur_ci.md b/doc/guide_utilisateur_ci.md index 2b9cf138ca3cb901ba1ec0e0a432f22d5d414e05..4bc726d10ecef851d21da3b356ec13b7bbca6a94 100644 --- a/doc/guide_utilisateur_ci.md +++ b/doc/guide_utilisateur_ci.md @@ -7,7 +7,6 @@ Ce dépôt utilise la [chaîne d'intégration de Gitlab](https://docs.gitlab.com La CI est déclenchée dès lors qu'une modification est susceptible d'altérer un service est détectée. Elle va effectuer les opérations suivantes, partiellement ou complètement selon le contexte : -* Détection de l'image modifiée, * Construction de l'image Docker et push vers le registre de test, * Analyses de sécurité, * Push vers le registre de production. @@ -24,6 +23,11 @@ On peut vouloir mettre à jour : En principe, il suffit de récupérer ce dépôt, de faire les mises à jour souhaitées, de commit les changements et de les pousser pour que l'image soit construite si besoin. Le cas échéant, pour des services "maisons", il est de bon ton de mettre à jour un fichier `CHANGELOG.md` pour résumer les modifications. +Si le code du service à mettre à jour est intégré au dépôt par un submodule, on lancera la commande suivante pour le mettre à jour à la dernière version. Voir la documentation des submodules pour utiliser un tag ou une branche spécifique. +``` +git submodule update picasoft-metrics-bot +``` + Si vous mettez à jour un fichier de configuration qui nécessite de reconstruire l'image, il faudra lancer la CI manuellement depuis la page [Pipelines](https://gitlab.utc.fr/picasoft/projets/dockerfiles/pipelines). Si vous mettez à jour un fichier de configuration qui est monté dans le conteneur via Docker Compose, aucune action de la CI n'est nécessaire, **même pas l'action `push-prod`**. Notez que le **nom final** de l'image construite est celui que vous indiquez dans le `docker-compose.yml`. Si vous mettez à jour un service en lui-même (option 1 de la liste ci-dessus), il faut impérativement modifier la version de l'image construite dans ce fichier dans le `docker-compose.yml`. diff --git a/pica-metrics-bot/README.md b/pica-metrics-bot/README.md index d55dd8721925c4ba7df41c1f2559c8ffdab8a55c..71c520b6c3107858bb8f4aaee9e5527185192b18 100644 --- a/pica-metrics-bot/README.md +++ b/pica-metrics-bot/README.md @@ -8,7 +8,7 @@ Par rapport au projet original : * La configuration en production est versionnée ici, et un Docker Compose adapté est proposé * Un [entrypoint](./entrypoint.sh) modifié permet d'injecter des secrets sous forme de variables d'environnement * La construction de l'image est gérée par la chaîne d'intégration et permet d'analyser la sécurité de l'image -* Ajout d'InfluxDB directement adossé à Picasoft Metrics Bot, dans un seul Docker Compose! +* Ajout d'InfluxDB directement adossé à Picasoft Metrics Bot, dans un seul Docker Compose ## Premier lancement @@ -18,10 +18,14 @@ L'utilisateur InfluxDB qui doit être utilisé dans Picasoft Metrics Bot est cel ## Mise à jour -Le projet Picasoft Metrics Bot n'a pas de numéro de version : pour reconstruire l'image avec les dernières modifications, il suffira de changer le tag dans le fichier Docker Compose et de lancer manuellement la construction au niveau du Pipeline du commit. +Le projet Picasoft Metrics Bot n'a pas de numéro de version. -Lancer la commande suivante pour mettre à jour le submodule au dernier commit du dépôt contenant le code : +À la place, chaque construction par la chaîne d'intégration utilisera le numéro de commit associé au submodule pour construire l'image avec le code du dépôt Picasoft Metrics Bots. + +Il suffit de lancer la commande suivante pour mettre à jour le submodule au dernier commit du dépôt contenant le code : ```bash -git submodule update --recursive --remote +git submodule update picasoft-metrics-bot ``` + +Puis de changer le tag dans le fichier Docker Compose, de pousser les changements et de lancer manuellement la construction au niveau du Pipeline du commit.