..
  Copyright (C)  2023  Jeremie Salvi.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.3
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
  A copy of the license is included in the section entitled "GNU
  Free Documentation License".

Installation de GitList
=======================

GitList est une interface web simple et légère écrite en PHP qui permet
de visionner l'ensemble de nos dépots git sur un serveur.

.. warning:: la version 2.0.0 contient un bug qui empèche de
  parcourir les différents dépots, nous installeront donc la
  version 1.1.1

.. note:: J'ai installé GitList sous Debian 11, pour d'autres distributions il
  faudra adapter quelques paramètres, comme par exemple sous ArchLinux :
  
  - l'utilisateur apache est ``http`` et non ``www-data``,
  - le home directory de l'utilisateur apache est ``/srv/http`` et non ``/var/www``.

configuration d'apache
----------------------

On va configurer un simple vhost, en suivant les `recommendations
fournies par le développeur <https://github.com/klaussilveira/gitlist/wiki/Configuring-Gitlist-in-CENTOS7>`_.

On créer le vhost ``/etc/apache2/sites-available/gitlist.conf`` :

.. code-block:: apache

  <IfModule mod_ssl.c>
    <VirtualHost *:443>
      ServerAdmin webmaster@yourdomain.domain
      ServerName gitlist.yourdomain.domain
      DocumentRoot /var/www/gitlist

      <Directory /var/www/gitlist/>
        Options FollowSymLinks
        AllowOverride All
        Require all granted
      </Directory>

      ErrorLog ${APACHE_LOG_DIR}/gitlist-error.log
      CustomLog ${APACHE_LOG_DIR}/access.log combined

      # enable HTTP/2, if available
      Protocols h2 http/1.1

      SSLEngine on
      SSLCertificateFile /etc/letsencrypt/live/gitlist.yourdomain.domain/cert.pem
      SSLCertificateKeyFile /etc/letsencrypt/live/gitlist.yourdomain.domain/privkey.pem
      SSLCertificateChainFile /etc/letsencrypt/live/gitlist.yourdomain.domain/chain.pem
    </VirtualHost>
  </IfModule>

Installation de gitlist
-----------------------

On se place dans notre repertoire root, on télécharge le zip, on l'extrait :

.. code-block:: bash

  cd /var/www/gitlist
  wget https://github.com/klaussilveira/gitlist/releases/download/1.1.1/gitlist-1.1.1.zip
  unzip gitlist-1.1.1.zip

Configuration
-------------

Quand on ouvre notre navigateur, on fait face a plusieurs messages d'erreur.
Configurons notre serveur pour que tout fonctionne correctement :

on créer un dossier ``cache`` et on attribue les droits du répertoire racine à l'utilisateur 
apache (``www-data``).

.. code-block:: bash

  mkdir cache
  chown -R www-data:www-data ./

On créer ensuite le fichier ``config.ini`` à partir du fichier ``config.ini-example`` fourni :

.. code-block:: bash

  cp config.ini-example config.ini
  vi config.ini

On modifie la ligne suivante pour indiquer le chemin des dépots :

.. code-block:: php

  repositories[] = '/home/git/repositories/'

Et voilà, on à la liste de nos dépots. Il reste une erreur quand on essaye de 
parcourir un dépot. cela est du au fait que l'utilisateur ``www-data`` qui utilise la
commande git n'as pas les droits sur le dossier du dépot. Git renvoie l'erreur suivante :
``fatal: detected dubious ownership in repository at '/home/git/repositories/doc.git' To add an exception for this directory, call: git config --global --add safe.directory /home/git/repositories/doc.git``.
La solution est dans le message, on execute la commande suivante pour chaque dépot :

.. code-block:: bash

  sudo -u www-data git config --global --add safe.directory /home/git/repositories/doc.git

.. warning:: git créer un fichier .gitconfig dans le home directory pour stocker ces paramètres.
  il faut s'assurer que l'utilisateur apache à bien accès en écriture à son home directory.


Sous debian, ``www-data`` utilise ``/var/www`` comme home directory. on le rend accessible en
écriture :

.. code-block:: bash

  chown www-data:www-data /var/www

Rendre les dépots clonable par https (en téléchargement uniquement)
-------------------------------------------------------------------

Pour que git puisse cloner un dépot, il  besoin de traitements spéciaux côté serveur.
Heureusement, git est foutni avec un binaire ``git-http-backend``, qui fait ce traitement.
Il suffit de le passer comme script cgi à apache.


On commence à activer les mods nécessaires pour apache :

.. code-block:: bash

  a2enmod cgi alias env

On ajoute ensuite la configuration suivante à notre vhost :

.. code-block:: apache

  SetEnv GIT_PROJECT_ROOT /data/git
  SetEnv GIT_HTTP_EXPORT_ALL

  ScriptAlias /git /usr/lib/git-core/git-http-backend

  <Directory "/usr/lib/git-core/">
      Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
      Require all granted
  </Directory>

  Alias /git /data/git

Pour terminer, on ajouste le config.ini de notre site, notament le http_url_subdir.

.. code-block:: php

  ; http remote
  show_http_remote = true ; display remote URL for HTTP
  http_host = '' ; host to use for cloning via HTTP (default: none => uses gitlist web host)
  use_https = true ; generate URL with https://
  http_url_subdir = 'git/' ; if cloning via HTTP is triggered using virtual dir (e.g. https://example.com/git/repo.git)
                      ; has to end with trailing slash
  http_user = '' ; user to use for cloning via HTTP (default: none)
  http_user_dynamic = false ; when enabled, http_user is set to $_SERVER['PHP_AUTH_USER']