Comment déployer un serveur GitLab avec Docker

GitLab est une plateforme de premier plan pour l’hébergement de dépôts Git, de pipelines CI et de flux de travail DevOps. Elle est disponible en tant qu’offre SaaS sur GitLab.com ou en tant que distribution autogérée pour une utilisation privée sur votre propre matériel.

GitLab est un système complexe formé d’un réseau de composants et de dépendances distincts. L’installation de paquets GitLab directement sur votre système d’exploitation ajoutera de nouveaux services lourds à votre machine, notamment PostgreSQL, Redis, Gitaly et l’application web principale GitLab basée sur Rails.

Déployer GitLab en tant que conteneur Docker est un moyen d’éviter de polluer votre environnement avec tous ces composants. Tout ce qui est lié à GitLab se trouve dans le conteneur, séparément du système de fichiers de votre hôte.

Dans ce guide, nous utiliserons Docker pour déployer une instance de GitLab prête pour la production, que vous pourrez utiliser pour héberger votre code source et collaborer sur des projets. Avant de commencer, il faut savoir que Docker n’élimine pas les exigences matérielles de base de GitLab : vous aurez besoin d’au moins 4 Go de RAM libre et d’environ 10 Go de stockage inutilisé.

GitLab propose une image Docker préconstruite qui contient tout ce dont vous avez besoin pour déployer le logiciel. Nous nous concentrons sur cette image dans ce tutoriel, mais il est important de prêter attention à ses limites.

L’image est monolithique par nature, regroupant tous les composants de GitLab afin qu’ils s’exécutent dans un seul conteneur. Cela simplifie la mise en place mais rend difficile la mise à l’échelle de votre installation à l’avenir. Elle va à l’encontre des meilleures pratiques de conteneurisation en exécutant plusieurs composants distincts dans le conteneur.

Cela signifie que l’image standard n’est pas forcément idéale pour les installations très fréquentées. Comme alternative, vous pouvez utiliser le graphique Helm de GitLab pour déployer sur un cluster Kubernetes. Cela lance chaque service en tant que son propre pod conteneurisé afin que vous puissiez faire évoluer les composants individuellement.

Déploiement de GitLab avec Docker

Installez Docker et configurez un enregistrement DNS A pour votre nom de domaine GitLab avant de poursuivre. Vous devez faire pointer l’enregistrement DNS vers l’adresse IP de votre hôte Docker. Nous utiliserons gitlab.example.com comme domaine dans le reste de ce guide.

Vous pouvez démarrer GitLab en exécutant la commande suivante :

docker run -d -p 22:22 -p 80:80 -p 443:443 \
–name gitlab \
–hostname gitlab.example.com \
–restart unless-stopped \
–shm-size 256m \
-v gitlab_config:/etc/gitlab \
-v gitlab_logs:/var/log/gitlab \
-v gitlab_data:/var/opt/gitlab \
gitlab/gitlab-ce:14.7.0-ce.0

Docker va télécharger l’image GitLab Community Edition (CE) et démarrer un nouveau conteneur en l’utilisant. La meilleure pratique est d’épingler une version spécifique de GitLab en sélectionnant la balise d’image correspondante, 14.7.0-ce.0 dans ce cas. Voici une explication des drapeaux utilisés dans la commande :

-d - Détacher le terminal du conteneur pour qu'il s'exécute en arrière-plan.
-p - Lier les ports 22, 80 et 443 du conteneur aux ports correspondants de votre hôte ; cela permet à GitLab de recevoir le trafic Git et Web via SSH et HTTP/S lorsqu'il est dirigé vers votre hôte.
--name - Attribue au conteneur un nom convivial afin que vous puissiez le référencer facilement lors de l'exécution de commandes Docker CLI à l'avenir.
--hostname - Définit le nom d'hôte du conteneur ; il doit correspondre au domaine que vous utilisez pour accéder à GitLab.
--restart - Attribue au conteneur une stratégie de redémarrage afin qu'il soit automatiquement redémarré lorsqu'il quitte le conteneur en raison d'une défaillance ou d'un redémarrage de l'hôte.
--shm-size - Ceci est expliqué dans la section suivante.
-v - Configurer des volumes Docker pour stocker de manière persistante les fichiers de configuration, les journaux et les données utilisateur générées de GitLab en dehors du conteneur. C'est essentiel pour ne pas perdre vos données lorsque le conteneur s'arrête !

Attendez plusieurs minutes pour que la configuration de la première exécution de GitLab soit terminée.

Finalement, vous devriez être en mesure de visiter gitlab.example.com pour voir la page de connexion. Connectez-vous en tant que root ; le mot de passe du compte est automatiquement généré et peut être récupéré en exécutant la commande suivante :

docker exec -it grep ‘Password:’ /etc/gitlab/initial_root_password.

Remplacez par le nom que vous avez attribué lors de la création de votre conteneur. Il s’agit de gitlab dans l’exemple ci-dessus.

Pour aller plus loin : Comment définir des variables dans vos pipelines GitLab CI

Investigation des problèmes de déploiement

Il est normal que les scripts d’installation prennent beaucoup de temps pour se terminer. GitLab doit configurer un grand nombre de composants avant que le service puisse commencer à fonctionner. Vous pouvez suivre la progression en consultant les journaux du conteneur :

docker logs gitlab –follow

Si l’interface Web de GitLab n’est pas disponible, la meilleure solution consiste à attendre un peu plus longtemps et à laisser la procédure de configuration se dérouler jusqu’à son terme. Si quelque chose ne va pas, que vous voyez des erreurs 500 dans votre navigateur et que les journaux du conteneur ne montrent pas de nouvelle activité, redémarrer le conteneur avec docker restart gitlab peut parfois aider.

Un message d’erreur courant que vous pouvez voir dans les journaux ressemble à ceci :

L’écriture d’une valeur dans /dev/shm/gitlab/… échoue en raison d’un fichier non mappé.

Cela se produit parce que les services fournis avec GitLab écrivent d’importantes quantités de données sur le système de fichiers temporaire /dev/shm. Par défaut, Docker n’alloue aux conteneurs qu’un espace /dev/shm de 64 Mo. Cet espace est rarement suffisant pour soutenir la collecte de métriques de GitLab via Prometheus, responsable de la plupart des écritures sur le système de fichiers.

La capacité de /dev/shm peut être augmentée à l’aide du drapeau –shm-size lorsque vous créez votre conteneur avec docker run. Cela est illustré dans l’exemple de déploiement ci-dessus où 256 Mo sont alloués, le minimum recommandé par GitLab. Les installations très actives peuvent nécessiter l’utilisation d’une taille supérieure.

Un autre problème concerne les fichiers journaux de GitLab : ils deviennent rapidement volumineux, ce qui peut provoquer des erreurs de détection de dépassement de mémoire tampon lors du démarrage de Docker. Vous pouvez éviter ce problème en effaçant périodiquement les anciens fichiers du répertoire /var/log/gitlab depuis votre conteneur GitLab :

docker exec -it gitlab rm /var/log/gitlab/*

Les fichiers journaux que Docker collecte à partir des flux de sortie du conteneur et conserve sur votre hôte atteignent rapidement des tailles importantes. Le pilote de stockage des fichiers journaux par défaut de Docker est inadéquat pour être utilisé avec une instance GitLab de production. Les fichiers JSON qu’il crée sont lourds, verbeux et ne sont jamais compressés ni soumis à une rotation. Passez à un autre pilote de stockage, tel que local ou journald, pour garantir la rotation régulière des journaux.

À lire également : Comment déployer PostgreSQL en tant que conteneur Docker

Configuration de GitLab

Vous pouvez fournir des extraits de fichiers de configuration GitLab lorsque vous créez votre conteneur en définissant la variable d’environnement GITLAB_OMNIBUS_CONFIG. Il doit s’agir d’une chaîne Ruby valide qui sera ajoutée au fichier /etc/gitlab/gitlab.rb à l’intérieur du conteneur :

docker run -e GITLAB_OMNIBUS_CONFIG= »gitlab_rails[‘allowed_hosts’] = [‘gitlab.example.com] ; nginx[‘redirect_http_to_https’] = true ; »

Vous pouvez également modifier le fichier /etc/gitlab/gitlab.rb depuis le conteneur une fois qu’il est en cours d’exécution. Lorsque vous avez terminé les modifications, vous devez redémarrer le conteneur pour les appliquer :

docker restart gitlab

L’image Docker GitLab exécute automatiquement le script de reconfiguration d’Omnibus à chaque démarrage. Celui-ci prend la configuration actuelle de votre gitlab.rb et l’applique à votre installation. Il est normal que GitLab soit inaccessible pendant quelques secondes après le redémarrage de votre conteneur pendant que ce processus se termine.

Application des mises à jour de GitLab

Les mises à jour de GitLab sont facilement appliquées en arrêtant votre conteneur et en en démarrant un nouveau avec la même configuration.

Tirez la nouvelle image correspondant à la version de GitLab que vous avez choisie :

docker pull gitlab/gitlab-ce:14.7.1-ce.0

Supprimez votre conteneur existant :

docker rm gitlab

Enfin, démarrez un nouveau conteneur, en répétant vos drapeaux d’origine mais en modifiant la référence de l’image :

docker run -d -p 22:22 -p 80:80 -p 443:443 \
–name gitlab \
…
gitlab/gitlab-ce:14.7.1-ce.0

Vos données seront intactes car les volumes de l’ancien conteneur seront rattachés au nouveau.

Vous pouvez éviter la répétition de vos drapeaux d’exécution de docker en encapsulant votre configuration dans un fichier docker-compose.yml :

version : « 3 »
services :
gitlab :
image : gitlab/gitlab-ce:14.7.0-ce-0
nom d’hôte : gitlab.exemple.com
ports :
– 22:22
– 80:80
– 443:443
volumes :
gitlab_config:/etc/gitlab
gitlab_logs:/var/log/gitlab
gitlab_data:/var/opt/gitlab
restart : unless-stopped
volumes :
gitlab_config :
gitlab_logs :
gitlab_data :

Lorsque vous utilisez Docker Compose, vous pouvez faire apparaître votre instance GitLab en exécutant docker-compose up -d. Pour mettre à jour une nouvelle version, modifiez le champ image en conséquence et répétez la commande. Docker Compose automatisera le processus de remplacement des conteneurs.

Indépendamment du mécanisme que vous utilisez, il est important de s’assurer que vos chemins de mise à niveau s’alignent sur les routes prises en charge par GitLab. Il se peut que vous deviez effectuer des actions manuelles après la mise à niveau pour terminer la migration.

Sauvegarde de votre installation

Des sauvegardes régulières sont essentielles pour un déploiement réussi de GitLab. Le rôle typique de GitLab en tant que source unique de vérité de votre organisation signifie que, dans le pire des cas, tout votre travail pourrait disparaître à jamais si des sauvegardes ne sont pas effectuées.

GitLab dispose d’un utilitaire de sauvegarde intégré qui peut être utilisé pour créer une archive complète de votre installation. Il est accessible dans l’image Docker via la commande gitlab-backup :

docker exec -t gitlab gitlab-backup create

Par défaut, les sauvegardes sont enregistrées dans le répertoire /var/opt/gitlab/backups. Cela signifie qu’elles seront stockées en dehors du conteneur, dans l’un de vos volumes Docker montés. Pour une meilleure sécurité, vous devriez configurer GitLab pour télécharger les sauvegardes vers un fournisseur de stockage d’objets distant en ajoutant ces lignes à votre fichier de configuration :

gitlab_rails[‘backup_upload_connection’] = {
« provider » => « AWS »,
« region » => « eu-west-1 »,
« aws_access_key_id » => « access_key »,
« aws_secret_access_key » => « secret_key »,
# « endpoint » => « https://… »
}

Maintenant, la commande gitlab-backup create téléchargera automatiquement les fichiers d’archive qu’elle génère, en les gardant séparés de votre conteneur GitLab et de votre hôte Docker. La dernière étape consiste à ajouter une tâche cron sur votre système qui exécute périodiquement le script de sauvegarde :

0 * * * * docker exec -t gitlab gitlab-backup create

Conclusion

GitLab est un logiciel complexe qui se déploie facilement avec Docker. L’exemple d’exécution de docker présenté dans ce guide convient à une utilisation en production lorsqu’il est combiné avec les modifications de configuration des meilleures pratiques expliquées ci-dessus. Vous devez également vérifier la sécurité du démon Docker et de votre hôte pour vous assurer que vos données sont correctement protégées.

Un déploiement GitLab sous Docker est un bon moyen de tester rapidement la plateforme. Il s’agit également d’une stratégie efficace pour lancer et maintenir un serveur GitLab plus petit pour une utilisation à long terme. D’autres options, telles que GitLab Omnibus sur un serveur dédié ou une installation cloud-native Kubernetes, sont généralement mieux adaptées aux besoins plus importants et à l’adoption durable par les entreprises.