Configurer GitLab Pages sur une instance GitLab self-hosted avec Docker

GitLab Pages permet d’héberger des sites statiques directement depuis vos dépôts Git, de manière automatisée via CI/CD.
Sur une instance auto-hébergée de GitLab, la configuration de GitLab Pages avec Docker demande quelques étapes supplémentaires (DNS, reverse proxy, configuration du conteneur, etc.).

Dans ce tutoriel, nous allons voir comment activer et configurer GitLab Pages sur une instance GitLab self-hosted déployée avec Docker.

Objectifs :

• Activer GitLab Pages sur une instance Docker
• Configurer le DNS et le wildcard
• Configurer le reverse proxy
• Déployer un premier site Pages

J’utilise régulièrement cette solution pour publier des pages ou applications statiques, cette solution évite la mise en place d’un service web dédié et cela permet aussi de centraliser tout sur Gitlab.

Cette solution peut aussi être utilisé pour publier des sites complexes comme WordPress en statique ou des solutions comme Docusaurus pour écrire de la documentation.

Afin de rendre cet exemple concret, on va se baser sur le code de la page qui se trouve sur le dépôt : git.rdr-it.com/tuto/gitlab-page-template

Ce modèle de page permet de mettre en avant des solutions hébergés interne

Prérequis

Avant de commencer, vous devez disposer de :

• Une instance GitLab self-hosted fonctionnelle (Docker)
• Un nom de domaine (ex: pages.domain.tld)
• Un accès au DNS
• Un reverse proxy (ex: Nginx ou Traefik)
• Un runner GitLab opérationnel

Dans cet exemple :

• Domaine GitLab : git.domain.tld
• Domaine GitLab Pages : pages.domain.tld
• Wildcard : *.pages.domain.tld

Nous verrons également dans ce tutoriel, comment utiliser un domaine personnalisé

Configuration de GitLab : activation de Gitlab Page

Par défaut, la fonctionnalité Gitlab n’est pas activée, pour cela il faut modifier le fichier docker-compose.yml.

services:
  gitlab:
    image: 'gitlab/gitlab-ce:latest'
    restart: always
    ...
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.domain.tld'
        nginx['listen_port'] = 443
        nginx['listen_https'] = true
        ...
        # Gitlab page config
        pages_external_url 'http://pages.domain.tld'
        gitlab_pages['enable'] = true
        ...
    ports:
      - "80:80"
      - "443:443"
      - "222:22"  
    ...

Ajouter les lignes en surbrillance à votre configuration en adaptant à votre environnement

Par défaut Gitlab Page utilise le reverse proxy qui est intégré à Gitlab, nous reviendrons sur cette configuration quand on verra comment mettre en place un domaine personnalisé.

Maintenant, redémarrer le conteneur : sudo docker compose up -d pour appliquer les modifications.

Création d’un site sur Gitlab

On va maintenant passer à la création du site, tout se passe sur le dépôt avec le fichier .gitlab-ci.yml qui contient les instructions pour mettre en ligne des fichiers du sites.

Dans l’exemple, nous sommes sur quelques choses de très simple, où il suffit seulement de copier les fichiers et dossiers dans le dossier public.

Sur votre instance GitLab, créez un nouveau dépôt puis importez les fichiers du dépôt d’exemple que vous aurez préalablement récupérés. Une fois le push effectué, si tout est correctement configuré, un pipeline se déclenchera automatiquement afin de publier le site.

Pour accéder au information de déploiement, sur le menu dépôt aller sur Deploy -> Pages

Si tout est bien configuré, vous arrivez sur une page qui vous donne l’URL de votre site sous la forme http://<user|group>.pages.domain.tld/<projet>.

Si vous arrivez sur une page avec un assistant de configuration, c’est que le fichier .gitlab-ci.yml n’est pas reconnu par Gitlab, ensuite vous pouvez aussi arriver une page d’erreur de pipeline.

Si vous avez ce résultat, félicitation, vous avez hébergé votre premier page sur Gitlab, on est d’accord que l’URL par défaut n’est pas top, on va maintenant voir comment faire pour utiliser un domaine « personnalisé »

Configurer Gitlab Pages pour utiliser un domaine personnalisé

Pour utiliser un domaine personnalisé, il est nécessaire d’adapter la configuration de GitLab Pages au niveau du conteneur.

Par défaut, dans une configuration simple, GitLab Pages s’appuie sur le serveur Nginx intégré. Lorsque l’on souhaite utiliser un domaine personnalisé, GitLab Pages repose alors sur son propre reverse proxy, écrit en Go, distinct du Nginx embarqué.

Dans un environnement où GitLab est installé hors conteneur, il est généralement recommandé de prévoir une seconde adresse IP (ou une seconde interface réseau) dédiée à GitLab Pages.

Dans notre cas, puisque nous utilisons Docker et qu’un reverse proxy est déjà présent en amont, il n’est pas nécessaire d’ajouter une nouvelle IP. Nous allons simplement configurer GitLab Pages pour qu’il écoute sur un port différent, lequel sera ensuite exposé et proxyfié par notre reverse proxy.

Editer le fichier docker-compose.yml :

services:
  gitlab:
    image: 'gitlab/gitlab-ce:latest'
    restart: always
    ...
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.domain.tld'
        nginx['listen_port'] = 443
        nginx['listen_https'] = true
        ...
        # Gitlab page config
        pages_external_url 'http://pages.domain.tld'
        gitlab_pages['enable'] = true
        pages_nginx['enable'] = true                              # Not use Nginx
        gitlab_pages['external_http'] = ['0.0.0.0:8090']          # Port reverse proxy for Gitlab Pages
        gitlab_pages['custom_domain_mode'] = 'http'        
        ...
    ports:
      - "80:80"
      - "443:443"
      - "222:22"
      - "8090:8090"
    ...

Les modifications effectuées, appliquer la nouvelle configuration : docker compose down && docker compose up -d.

Dans le cas d’un usage interne, désactiver la vérification du propriétaire du domaine, dans l’administration de Gitlab (Admin -> Settings -> Preferences / Pages).

Ensuite aller sur le dépôt qui héberge les sources des pages dans la configuration de Gitlab Pages et dans la partie Domains & settings, vous allez pouvoir ajouter le domaine personnalisé pour l’accès au « site ».

Conclusion

La configuration de GitLab Pages sur une instance self-hosted en Docker demande quelques ajustements supplémentaires par rapport à la version SaaS, notamment au niveau du DNS, du reverse proxy et de la configuration du conteneur.

Cependant, une fois correctement mis en place, GitLab Pages devient un outil extrêmement puissant pour publier automatiquement des sites statiques, de la documentation, des dashboards ou des landing pages directement depuis vos dépôts Git.

Dans un environnement conteneurisé avec un reverse proxy en amont (Nginx ou Traefik), la configuration reste propre et flexible, sans nécessiter d’adresse IP supplémentaire. L’exposition via un port dédié simplifie l’intégration tout en conservant une architecture claire et maintenable.

Au final, vous bénéficiez :

• d’un déploiement automatisé via CI/CD
• d’un hébergement maîtrisé en interne
• d’une séparation propre entre GitLab et GitLab Pages
• d’une publication rapide et standardisée pour vos équipes

J’utilise régulièrement cette solution pour mettre en place des sites « quick-win » qui évite la multiplication de serveur Web et/ou de conteneur pour quelques pages statiques. Avec un peu de « formation » vos utilisateurs peuvent être autonomes.

FAQ – GitLab Pages en self-hosted