wiki/HowtoAegir.md

---
categories: web
title: Howto Aegir
...

* Documentation : <https://docs.aegirproject.org/>

[Aegir](https://www.aegirproject.org/) est un système de gestion et de déploiement de sites web [Drupal](HowtoDrupal) en mode [multisites](https://www.drupal.org/docs/multisite-drupal).
On peut par exemple déployer du Drupal 8 ou 9 en local ou sur des serveurs distants.

Code source : <https://github.com/aegir-project>

Aegir est composé des éléménts suivants :

* [hostmaster](https://www.drupal.org/project/hostmaster) : interface web en Drupal 7 : <https://www.drupal.org/project/hostmaster>
* [provision](https://www.drupal.org/project/Provision) : suite de commandes [drush](HowtoDrupal#drush) pour installer des sites Drupal (cf `/usr/share/drush/commands/provision/`
* [hosting](https://www.drupal.org/project/hosting) : modules Drupal pour permettre l'UI de l'interface web d'Aegir
* [eldir](https://www.drupal.org/project/eldir) : thème Drupal pour Aegir

## Installation

Pré-requis : Debian 10 avec PHP 7.3 (par défaut sous Debian 10)

Préparer un service [MySQL](HowtoMySQL) local avec un identifiant "admin" afin de permettre au paquet Debian `aegir3` de créer une base et des utilisateurs MySQL (il va notamment créer `aegir_root`) :

~~~
# echo "deb [ allow-insecure=yes ] https://debian.aegirproject.org stable main" > /etc/apt/sources.list.d/aegir.list
# wget http://debian.aegirproject.org/key.asc -O /etc/apt/trusted.gpg.d/aegir.asc
# chmod 644 /etc/apt/trusted.gpg.d/aegir.asc

# screen -S aegir-dpkg-workaround -dm bash -c "while true; do systemctl daemon-reload; done"
# apt update && apt install aegir3 composer

Unpacking aegir3 (3.192) ...
...
Adding user aegir to group www-data
Creating config file /etc/sudoers.d/aegir with new version
Setting up aegir3-hostmaster (3.192) ...
'drush' cache was cleared.                                           [success]
...
Adding hosting-dispatch cron entry to run every minute               [ok]
The command did not complete successfully, please fix the issues and [error]
re-run this script
Aegir 7.x-3.192 automated install script

Enabling hosting-queued daemon
The following extensions will be enabled: hosting_queued
Do you really want to continue? (y/n): y
hosting_queued was enabled successfully.                             [ok]
Enabling Hosting queue daemon feature.                               [status]
Synchronizing state of hosting-queued.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable hosting-queued
...
Use this URL to login on your new site:
http://aegir.example.comr/user/reset/1/1664384789/BPynMpO0tjjTOlvr8aOW4z7g0rNGsfKgGEFOuUr8oVU/login

# pkill -9 screen && screen -wipe

# mv /usr/local/bin/drush /usr/local/bin/drush.bak
# su - aegir
$ composer global require drush/drush:8.4.8
# ln -s /var/aegir/.composer/vendor/bin/drush /usr/local/bin/drush


# ls -d /var/aegir/hostmaster-*
/var/aegir/hostmaster-7.x-3.192

# /usr/local/bin/drush.bak version
 Drush Version   :  8.1.16
# /usr/local/bin/drush version
 Drush Version   :  8.4.8 
~~~

> Note : après installation, désactiver le dépôt APT Aegir vu que la clé GPG est expirée depuis le 3 octobre 2022 :(


On peut ensuite activer différents modules via l'interface web d'Aegir : options pour Git, Let's Encrypt, etc.

Si l'on utilise pas "Composer" pour déployer, nous conseillons de désactiver le module "Aegir Platform Composer" (sans cela on constate que le code Drupal n'était pas déployer sur les infra multi-serveurs).

## Utilisation

Le principe d'Aegir est de définir des plateformes associés à un serveur web (ou plusieurs, cf plus bas le [mode multi-serveurs](HowtoAegir#multi-serveurs)).
Un usage typique est de définir une plateforme de "PROD" et une plateforme de "PREPROD" associés à des serveurs web différents.
Une plateforme déploie le code Drupal sur le serveur associé, cela peut par exemple être un Drupal 8.8.5 ou en Drupal 9.4.5.
On peut ensuite créer des sites associé à une plateforme, cela s'appuye sur la fonctionnalité [multisites](https://www.drupal.org/docs/multisite-drupal) de Drupal.

### Servers

Par défaut il y a le serveur web local (type `Apache`) et un serveur de base de données local (type `MySQL`).

### Platforms

Ajouter une plateforme est l'étape la plus critique, car c'est là qu'Aegir va déployer le code source de Drupal.
Plusieurs [stratégies de déploiement](https://docs.aegirproject.org/usage/advanced/deployment/) sont possibles : récupérer le code de Drupal via Git, déploiement via Drush, etc.
Attention, à cette étape Aegir va scanner la présence d'un fichier `composer.lock` et lancera un `composer install` si il est présent… et ne se déploiera pas en cas d'erreur !

### Sites

Il faut définir un nom de domaine et l'associer à une plateforme.
On peut aussi : choisir un language pour le site, un profil (minimal, standard, personnalisé, etc.) et serveur de base de données.


## Plomberie

L'installation initiale d'Aegir se fait via un `drush hostmaster-install`.

Lorsque que l'on définit des serveurs, plateformes, sites, cela va créer des fichiers de configuration stockés dans `/var/aegir/.drush/` :

~~~
# ls /var/aegir/.drush/

hm.alias.drushrc.php
hostmaster.alias.drushrc.php
server_localhost.alias.drushrc.php
server_master.alias.drushrc.php
platform_hostmaster.alias.drushrc.php
platform_PROD.alias.drushrc.php
platform_PREPROD.alias.drushrc.php
FQDN1.alias.drushrc.php
FQDN2.alias.drushrc.php
FQDN3.alias.drushrc.php
...
~~~

Cela va également écrire dans la base de données MySQL propre à Aegir.

Par exemple pour lister les serveurs :

~~~
MariaDB> select title,service,hosting_service.type,restart_cmd,port,uid,hosting_server.status,created,changed from hosting_server,hosting_service,node where hosting_server.vid=hosting_service.vid and hosting_server.nid=node.nid;
+-------------+---------+---------+------------------------------------+------+-----+--------+------------+------------+
| title       | service | type    | restart_cmd                        | port | uid | status | created    | changed    |
+-------------+---------+---------+------------------------------------+------+-----+--------+------------+------------+
| foo1        | http    | apache  | sudo /usr/sbin/apache2ctl graceful |   80 |   1 |      1 | 1663071992 | 1663072005 |
| foo2        | http    | apache  | sudo /usr/sbin/apache2ctl graceful |   80 |   1 |      1 | 1663175297 | 1663175299 |
| foo3        | http    | apache  | sudo /usr/sbin/apache2ctl graceful |   80 |   1 |      1 | 1663175326 | 1663175327 |
| 127.0.0.1   | db      | mysql   |                                    | 3306 |   1 |      1 | 1663071992 | 1663230576 |
| webcluster  | http    | cluster |                                    |    0 |   1 |      1 | 1663175362 | 1663230664 |
~~~

Au sein d'un site Drupal, on peut collecter différentes informations via [Drush](HowtoDrupal#drush) :

~~~
$ cd $ROOT
$ drush sql-connect
$ drush status
~~~

## Ligne de commande

Grâce aux fichiers de configuration stockés dans `/var/aegir/.drush/` on peut ainsi lancer plein de commandes Drush du type :

~~~
# su - aegir

$ drush @hostmaster provision-verify
$ drush @platform_PREPROD provision-verify --debug
$ drush @platform_PREPROD provision-delete --debug --force
$ drush @FQDN1 --backend=2 provision-install
$ drush @FQDN1 provision-verify --debug
~~~


## Gestion des Tasks

Aegir lance des Tasks pour toutes les actions : installation, suppression, vérification, etc.

Pour cela, Aegir s'appuie sur un service `hosting-queued` :

~~~
systemctl status hosting-queued.service
● hosting-queued.service - Hosting queue daemon
   Loaded: loaded (/lib/systemd/system/hosting-queued.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2022-09-13 14:28:45 CEST; 5s ago
 Main PID: 1704 (php)
    Tasks: 3 (limit: 4701)
   Memory: 67.6M
   CGroup: /system.slice/hosting-queued.service
           ├─1704 php /usr/local/bin/drush --quiet @hostmaster hosting-queued
           ├─1815 sh -c /usr/local/bin/drush  --strict= --uri=aegir.example.com --root=/var/aegir/hostmaster-7.x-3.192  hosting-task 13 2>&1
           └─1816 php /usr/local/bin/drush --strict= --uri=aegir.example.com --root=/var/aegir/hostmaster-7.x-3.192 hosting-task 13
~~~

et un cron lancé chaque minute :

~~~
# crontab -u aegir -l
* * * * * /usr/bin/env php /usr/local/bin/drush '@hostmaster' hosting-dispatch 
~~~

qui lancera ensuite des commandes du type `drush --php=/usr/bin/php --php-options= --quiet @hostmaster hosting-queued`

En cas de soucis, blocage des Tasks par exemple, on peut déboguer la tâche en récupérant son n° (visible sur l'interface web) :

~~~
# su - aegir
$ drush @hostmaster hosting-task 42 --debug
~~~

Parfois, lancer une vérification en ligne de commande peut débloquer :

~~~
# su - aegir
$ drush @FQDN1 provision-verify --debug
~~~

On peut aussi modifier le Cron et ajouter l'option `--debug`.

Ou alors vider le cache Drush :

~~~
# su - aegir
$ drush cache-clear drush
~~~

Par l'interface web on peut accéder à la liste des Tasks via <http://aegir.example.com/admin/content/node/overview> et supprimer une Task (à utiliser avec précaution).

Pour d'autres infos, voir <https://community.aegirproject.org/content/administrator/troubleshooting-aegir/>

## Multi-serveurs

<https://docs.aegirproject.org/usage/servers/clustering/>

Nous préconisons d'utiliser la méthode "Web Cluster".

Il faut activer le module Aegir "Web Cluster" :

~~~
Enabling Web clusters feature.
The configuration options have been saved.
~~~

Sur les « noeuds » web :

Pré-requis :

* Debian 11 avec PHP 7.4 (par défaut sous Debian 11)
* créer un utilisateur "aegir" ainsi : `adduser --home /var/aegir --uid 513 --gid 513 --disabled-password aegir` (même UID/GID que sur le serveur Aegir)

Puis il faut installer le paquet `aegir3-cluster-slave` :
 
~~~
# echo "deb [ allow-insecure=yes ] https://debian.aegirproject.org stable main" > /etc/apt/sources.list.d/aegir.list
# wget http://debian.aegirproject.org/key.asc -O /etc/apt/trusted.gpg.d/aegir.asc
# chmod 644 /etc/apt/trusted.gpg.d/aegir.asc

# wget https://pub.evolix.org/evolix/pool/main/m/mysql-client/mysql-client_8.0_all.deb
# dpkg -i mysql-client_8.0_all.deb

# apt update && apt install aegir3-cluster-slave
# chown aegir: /var/aegir/platforms
~~~

L'installation du paquet `aegir3-cluster-slave` va :

* valider la connexion SSH entre l'utilisateur "aegir" depuis le serveur Aegir vers l'utilisateur "aegir" du noeud (avec une clé SSH sans mot de passe)
* /etc/sudoers.d/aegir
* Installer Apache / PHP
* (ignorer la demande pour NFS)

On peut ensuite ajouter des "serveurs" pour chacun des noeuds, puis ajouter un serveur "Web cluster" qui rassemble les noeuds.
Il faut ensuite ajouter une plateforme associée à ce noeud. Puis l'on devrait pouvoir créer des sites sur cette plateforme « clusterisée ».


## FAQ

### Troubleshooting

En cas de soucis, on peut tester différentes astuces.

Vider le cache Drush :

~~~
# su - aegir
$ drush cache-clear drush
~~~

Vérifier que les configurations dans `/var/aegir/.drush/` sont conformes à ce que l'on a mis via l'interface web (cela semble parfois boguer).

Lancer des commandes à la main, cf [Ligne de commande](HowtoAegir#ligne-de-commande)

Voir <https://community.aegirproject.org/content/administrator/troubleshooting-aegir/>


### Skipping unset context property: git_repository_path

Cela signifie qu'il manque cette option dans le fichier associé `/var/aegir/.drush/XXX.drushrc.php`.
Un contournement est d'ajouter cette option à la main :

~~~
./platform_PREPROD42.alias.drushrc.php:  'git_repository_path' => NULL,
./platform_PREPROD43.alias.drushrc.php:  'git_repository_path' => '/var/aegir/platforms/platform_PREPROD43',
~~~

Si cette option est manquante, vous aurez peut-être l'erreur :

~~~
Cloning `GIT_REPO:REPO.git` to ``
Running `git clone --recursive --depth 1 --no-progress --quiet --branch 'dev' 'GIT_REPO:REPO.git' ''`
Command failed. The specific errors follow:
fatal: could not create work tree dir '': No such file or directory
~~~

### Données non présentes dans `/var/aegir/plateforms/PREPROD/`

Vérifier que les chemins sont corrects dans le fichier associé `/var/aegir/.drush/XXX.drushrc.php`

### Erreurs composer

Supprimer les fichiers `composer.lock` et `composer.json` dans `/var/aegir/plateforms/PREPROD/`

### Erreur "Unable to find a matching SQL Class"

Si vous avez une erreur du type :

~~~
Drush\Sql\SqlException: Unable to find a matching SQL Class. Drush cannot find your database connection details.
~~~~

Soit vous n'êtes pas dans le bon répertoire pour lancer Drush (on peut aussi utiliser l'option `--root=`),
soit vous devez utiliser une version de Drush plus récente : on a par exemple rencontré cette erreur
avec Drush 8.1.16 et c'était OK avec Drush 8.4.8

### PROVISION_DB_CONNECT_FAIL : Dummy connection failed to fail...Can't connect to MySQL server...(115)

Si vous utilisez un proxy pour accéder à MySQL, vous pouvez avoir une erreur de ce type lors de l'installation d'un site :

~~~
PROVISION_DB_CONNECT_FAIL : Dummy connection failed to fail. Either your MySQL permissions are too lax, or the response was not understood. See http://is.gd/Y6i4FO for more information. ERROR 2002 (HY000): Can't connect to MySQL server on 'proxy-mysql' (115)
~~~

Il s'agit d'un code de retour système 115 `Operation now in progress` (cf commande `perror 115`) qui devrait être ignoré par Aegir.

Nous [proposons le patch](https://github.com/aegir-project/provision/issues/41) suivant à intégrer au fichier `/usr/share/drush/commands/provision/db/Provision/Service/db/mysql.php` :

~~~
146a147,149
>     elseif (preg_match("/Can't connect to MySQL server on.*\(115\)/", $output, $match)) {
>       return $match[1];
>     }
~~~