Dans ce tutoriel, nous verrons comment nous pouvons exécuter Drupal 8 ou 9 en utilisant Docker sur notre machine locale, ce qui nous permettra d'aborder les sujets suivants :

  • Installer Drupal en utilisant composer
  • Config Docker
  • Variable d'environnement
  • Configuration de la base de données
  • Gestion de la configuration
  • Les meilleures pratiques .gitignore
  • Fichier settings.php

Objectif

Installez Drupal en utilisant le compositeur et exécutez le sur Docker.

Conditions préalables

Pour compléter ce tutoriel, nous devons avoir Docker, Docker Compose et Composer installés sur notre machine locale.

Installation de Docker

Installation de composer

Git (facultatif)

Docker Compose (Un outil pour gérer plusieurs conteneurs)

Le code intégral de ce tutoriel est disponible sur Github

Répertoire du projet

Notre répertoire de projets comprendra tous les fichiers liés à Drupal et non liés à Drupal.

/chemin/vers/répertoire_du_projet

Structure du répertoire
Structure du répertoire
  • Dockerfile : Ceci est votre fichier image Docker pour apache+php
  • README.md : Fichier Readme du projet
  • config : Ce répertoire est utilisé pour stocker les fichiers de configuration de Drupal
  • db-backups : Un volume monté sur un conteneur MySQL pour faire de l'import/export de bases de données
  • db-data : Monter l'ensemble du répertoire de données MySQL pour s'assurer que toutes les modifications de la base de données sont persistantes même lorsque le conteneur n'est pas en cours d'exécution
  • docker-compose.yml : Docker compose un fichier pour gérer plusieurs conteneurs
  • docroot : Répertoire du projet Drupal
  • etc : répertoire optionnel au cas où l'on voudrait modifier la configuration sous les fichiers de configuration des conteneurs sous /etc comme php.ini
  • .env : Un fichier dans lequel nous stockons des variables environnementales (notez le point au début du nom de fichier)

Installation pas à pas

Je suppose que vous avez maintenant installé Docker, Composer & Docker compose sur votre machine locale si ce n'est pas le cas, veuillez vous rendre à la section Conditions préalables de ce tutoriel pour effectuer cette tâche. Nous allons maintenant voir un guide étape par étape pour mettre notre projet en route sur une machine locale.

Etape 1

Créons notre répertoire principal de projet et la structure de dossier requise. Ouvrez votre terminal/CMD et lancez la commande ci-dessous (Si vous avez décidé de cloner le répertoire de ce tutoriel, vous n'avez pas à effectuer les étapes 1 et 2 manuellement, vous pouvez simplement cloner le repo à partir du Repo) :

mkdir DP-Template # créer un répertoire de projets
cd DP-Template # Vous déplacer dedans

Etape 2

Une fois que nous sommes sous le répertoire de notre projet nouvellement créé, nous pouvons installer Drupal en utilisant Composer. Pour télécharger la dernière version de Drupal, veuillez utiliser "drupal/recommended-project". La commande ci-dessous téléchargera la dernière version de Drupal dans votre dossier de projet sous le répertoire docroot :


composer create-project drupal/recommended-project docroot --no-interaction 

Si vous préférez spécifier une version, vous le pouvez aussi (exemple pour Drupal 8 :


composer create-project drupal/recommended-project:^8.9 docroot --no-interaction 

Etape 3

Passons maintenant aux dossiers relatifs à Docker et Docker-Compose.

La première chose que nous devons définir est le fichier .env qui sera utilisé pour stocker les variables d'environnement. Sous le répertoire de votre projet, créez un fichier avec un nom de fichier .env et ouvrez-le dans votre éditeur de texte préféré et ajoutez le contenu ci-dessous.


DB_NAME=mydrupal_db
DB_USER=user 
DB_PASSWORD=password
DB_ROOT_PASSWORD=password
DB_DRIVER=mysql
MYSQL_VERSION=5.7
HOST_MYSQL_PORT=3306
HOST_APACHE_PORT=80
MYSQL_NAME=mydrupal_mysql
WEB_NAME=mydrupal_site

Explication du fichier .env

  • DB_NAME= #Nom de la base de données
  • DB_USER= #Nom d'utilisateur de la base de données
  • DB_PASSWORD= #Mot de passe de la base de données pour $DB_USER
  • DB_ROOT_PASSWORD= #Mysql Root Password
  • MYSQL_VERSION=#Mysql Version à utiliser
  • HOST_MYSQL_PORT= #Docker container Mapping port for MySQL (assurez-vous que ce port n'est pas utilisé par une autre application, au cas où il le serait, n'hésitez pas à le changer)
  • HOST_APACHE_PORT= #Docker container Mapping port for apache, c'est sur ce port que nous allons accéder à notre site (assurez-vous que ce port n'est pas utilisé par une autre application, au cas où il serait utilisé, n'hésitez pas à le modifier)
  • MYSQL_NAME= #Nom du conteneur de MySQL
  • WEB_NAME= #Nom de notre conteneur web

Une fois la mise à jour des variables d'environnement terminée, nous allons maintenant travailler sur notre image de docker php+apache. Nous pouvons facilement utiliser une image php+apache existante mais, afin de comprendre ce qui se passe en arrière plan, nous utiliserons Dockerfile pour créer notre conteneur pour PHP+Apache. Créez un fichier avec un nom de fichier Dockerfile (sensible à la casse) dans le répertoire de votre projet et copiez le contenu ci-dessous dans ce fichier.


FROM php:7.3-apache

USER root


RUN buildDeps=" \
        default-libmysqlclient-dev \
        libbz2-dev \
        libmemcached-dev \
        libsasl2-dev \
    " \
    runtimeDeps=" \
        curl \
        git \
        libfreetype6-dev \
        libicu-dev \
        libjpeg-dev \
        libldap2-dev \
        libmemcachedutil2 \
        libpng-dev \
        libpq-dev \
        libxml2-dev \
        libzip-dev \
    " \
    && apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y $buildDeps $runtimeDeps \
    && docker-php-ext-install bcmath bz2 calendar iconv intl mbstring mysqli opcache pdo_mysql pdo_pgsql pgsql soap zip \
    && docker-php-ext-configure gd --with-freetype-dir=/usr/include/ --with-jpeg-dir=/usr/include/ \
    && docker-php-ext-install gd \
    && docker-php-ext-configure ldap --with-libdir=lib/x86_64-linux-gnu/ \
    && docker-php-ext-install ldap \
    && docker-php-ext-install exif \
    && pecl install memcached redis \
    && docker-php-ext-enable memcached.so redis.so \
    && apt-get purge -y --auto-remove $buildDeps \
    && rm -r /var/lib/apt/lists/*


ENV APACHE_DOCUMENT_ROOT=/var/www/html/web
RUN sed -ri -e 's!/var/www/html!${APACHE_DOCUMENT_ROOT}!g' /etc/apache2/sites-available/*.conf
RUN sed -ri -e 's!/var/www/!${APACHE_DOCUMENT_ROOT}!g' /etc/apache2/apache2.conf /etc/apache2/conf-available/*.conf


RUN a2enmod rewrite

RUN curl -sS https://getcomposer.org/installer | php --install-dir=/usr/bin --filename=composer


COPY docroot/ /var/www/html

COPY config/ /home/config


RUN curl -OL https://github.com/drush-ops/drush-launcher/releases/download/0.6.0/drush.phar \ 
&& chmod +x drush.phar \
&& mv drush.phar /usr/local/bin/drush


RUN cd /tmp && curl -sS https://getcomposer.org/installer | php && mv composer.phar /usr/local/bin/composer

RUN cd  /var/www/html/ && composer install

 
WORKDIR /var/www/html

Nous allons utiliser un conteneur séparé pour faire tourner MySQL et lorsque nous avons affaire à plusieurs containers devant travailler ensemble, docker-compose est l'outil à utiliser. Docker-compose est un outil permettant de définir et d'exécuter des applications Docker multi-conteneurs. Avec Docker-compose, vous utilisez un fichier YAML pour configurer les services de votre application. Maintenant, créons le fichier de configuration YAML pour l'utiliser avec Docker-compose.

Toujours sous notre répertoire de projet, créez un fichier nommé docker-compose.yml et ajoutez-y le contenu ci-dessous.


version: "3"

services:
  mydrupal_mysql:
    image: mysql:$MYSQL_VERSION
    container_name: $MYSQL_NAME
    ports:
      - "${HOST_MYSQL_PORT}:3306"
    volumes:
      - ./db-backups:/var/mysql/backups
      - ./db-data:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: $DB_ROOT_PASSWORD
      MYSQL_DATABASE: $DB_NAME
      MYSQL_USER: $DB_USER
      MYSQL_PASSWORD: $DB_PASSWORD
    restart: always
    command: "--default-authentication-plugin=mysql_native_password"
  mydrupal_site:
    build: . #thi is telling docker-composer to use Dockerfile from the main directory
    container_name: $WEB_NAME
    volumes:
      - ./docroot:/var/www/html
      - ./config:/home/config
    ports:
      - "${HOST_APACHE_PORT}:80"
volumes:
  db-data:

Notre fichier de composition définit deux conteneurs

  1. mydrupal_mysql : Il s'agit d'un conteneur pour le serveur de base de données MySQL qui sera construit à partir d'une image officielle de Docker MySQL et obtiendra toutes les variables environnementales à partir du fichier .env. Une autre chose à noter ici : les volumes. Toutes les données créées pendant la durée de vie du conteneur ne seront pas disponibles une fois que le conteneur sera arrêté, donc, pour résoudre ce problème, nous utilisons des volumes pour stocker toutes les données persistantes du conteneur.

    Les deux volumes que nous avons définis ici sont utilisés pour faire exactement cela :

    a) db-data : celui-ci monte le répertoire mysql entier du conteneur sur notre machine locale.

    b) db-data : C'est un répertoire vide créé pour servir de lieu de partage de fichiers entre le conteneur et notre machine locale (comme le fichier de sauvegarde mysql)
     
  2. mydrupal_site : Il s'agit d'un conteneur pour notre site Drupal qui va être construit à partir du Dockerfile que nous avons créé (le "." indique à docker-compose , la racine de notre projet)

Configurations spécifiques à Drupal

Gestion de la configuration

Par défaut, Drupal enregistre le répertoire de synchronisation de la configuration dans le répertoire des fichiers du site (sites/default/files), en utilisant un hachage dans le nom du répertoire, donc sites/default/files/config_HASH. Le HASH est une assez longue chaîne de caractères aléatoires. Mais, parce que nous voulons gérer nos fichiers de configuration dans notre dépôt, nous devons changer cet emplacement.

Vous pouvez définir plusieurs environnements pour votre configuration mais, pour ce tutoriel, je vais me concentrer sur le répertoire config sync.

Pour modifier le répertoire de configuration par défaut, supprimez "$settings[‘config_sync_directory’]" et remplacez-le par la ligne suivante dans votre fichier "settings.php :


$settings['config_sync_directory'] = '/home/config/sync';

Si vous utilisez une ancienne version de Drupal < 8.8.0, il faut utiliser le tableau $config_directories dans les paramètres. Pour une version < 8.8.0 de Drupal, utilisez le tableau ci-dessous :


$config_directories = array(
 sync => '/home/config/sync',
);

Git Ignore

Comme nous gérons notre installation Drupal à l'aide de composer, il nous suffit de suivre les modifications sur notre fichier composer.json et composer.lock pour gérer le noyau et les modules contribués. Vous trouverez ci-dessous le fichier .gitignore de ce tutoriel :


/docroot/drush/contrib/
/docroot/vendor/
/docroot/web/core/
/docroot/web/modules/contrib/
/docroot/web/themes/contrib/
/docroot/web/profiles/contrib/
# Ignore sensitive information
/docroot/web/sites/*/settings.local.php
# Ignore Drupal's file directory
/docroot/web/sites/*/files/
# Ignore SimpleTest multi-site environment.
/docroot/web/sites/simpletest
# Ignore files generated by PhpStorm
/docroot/.idea/
# Ignore .env files as they are personal
/.env
# Ignore DOCKER Related files multi-site environment.
db-backups/*
db-data/*
# Ignore old .build directory since it is autogenerated now
.build/

Construire et Exécuter

Enfin, nous avons maintenant tous les fichiers et outils nécessaires en place ; il est temps de mettre en place votre site Drupal. Changez votre répertoire pour celui de votre projet et lancez la commande ci-dessous.


docker-compose up -d --build

Une fois la construction terminée, changez votre répertoire en docroot et exécutez la commande ci-dessous (Il s'agit d'une commande unique pour créer un répertoire vendor)


composer update

Une fois les commandes ci-dessus exécutées, ouvrez votre site Drupal sur http://localhost:HOST_APACHE_PORT (le numéro de port apache du fichier .env). Cela ouvrira une page d'installation de Drupal, veuillez suivre la méthode typique d'installation de Drupal (à l'exception de la configuration de la base de données). Sur la page de configuration de la base de données.

Installation de Drupal
Installation de Drupal

 

Configuration de la base de données

Dans la fenêtre de configuration de la base de données, après avoir fourni le nom de la base de données, le nom d'utilisateur et le mot de passe, cliquez sur l'option avancée pour changer l'hôte de la base de données de "localhost" au nom du conteneur MySQL.

Database configuration
Database configuration

 

Configuration des paramètres locaux

La plupart des tutoriels Drupal recommandent d'ajouter le fichier settings.php au .gitignore mais, je pense que cela rend la gestion du site Drupal à travers différents environnements un peu plus compliquée qu'elle ne devrait l'être. Je suggère donc d'inclure setting.php dans votre dépôt et d'utiliser settings.local.php pour stocker les informations d'identification locales (utiliser les variables d'environnement pour les autres environnements).

N.B Veuillez ne pas ajouter d'informations d'identification dans votre fichier settings.php et utilisez plutôt des variables environnementales. (Presque tous les outils de construction de CI/CD permettent de transmettre des variables environnementales à votre conteneur)

Créons 'settings.local.php' et incluons-le dans notre fichier settings.php.


cd path/to_project_directory
cd docroot/web/sites/default/
nano settings.local.php # créer le fichier settings.local.php avec le contenu ci-dessous. Veuillez mettre à jour les valeurs en fonction des valeurs du fichier .env

<?php
  
$databases['default']['default'] = array (
  'database' => 'database name',
  'username' => 'database user',
  'password' => 'database password',
  'prefix' => '',
  'host' => 'mysql container name',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
);

Remarque : vous pouvez obtenir la valeur de la variable environnementale, mais il est possible d'avoir la valeur en texte brut dans votre fichier local (celui-ci ne fera pas partie de votre dépôt).

Une fois que nous avons créé settings.local.php, il est temps d'inclure le fichier dans notre fichier settings.php. Ouvrez settings.php et supprimez la configuration par défaut de la base de données "$databases['default']['default']" et ajoutez la ligne ci-dessous à la place :


if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
   include $app_root . '/' . $site_path . '/settings.local.php';
}

Vous pouvez ajouter une condition "if-else" ou "else" pour vous assurer que ce fichier settings.php fonctionne dans différents environnements.