Installer Laravel Homestead sous Hyper-v (Windows 10)

Laravel Homestead est un conteneur pré-packagé sous Vagrant pour faire tourner les projets Laravel (et également Symphony…) sur une machine de développement dans un environnement virtuel disposant de tous les composants pré-installés: PHP (multi-versions), serveur web Nginx ou Apache, bases de données (MySQL et PostgreSQL par défaut), etc…

Il s’agit d’un conteneur Linux (Ubuntu), ce qui est un avantage si le site tourne sous une distribution Linux en production, et enfin cela permet à chaque développeur de disposer facilement d’un environnement identique quelque soit la machine utilisée (y compris avec un parcs de machines sous OS hétérogènes: Linux, Mac, Windows…).

Nous présentons ici l’installation de Homestead sous Windows 10 (qui présente quelques subtilités par rapport à une installation sous Mac ou Linux).

Pré-requis: vérification de l’activation de la virtualisation sur la machine Windows 10

Cf pré-requis n°2 dans l’article de Microtuto: « Docker Desktop: installation d’un environnement de développement PHP/MySQL« .

Installation de Vagrant

Installer Vagrant depuis l’espace de téléchargement du site officiel.
Le répertoire d’installation par défaut: C:\Program Files\HashiCorps\Vagrant.
L’installation nécessite un redémarrage du PC.

Par la suite, installer le plugin vagrant-hostmanager qui s’assurera de mettre à jour dynamiquement le fichier hosts du PC en fonction du domaine de la machine virtuelle qui sera déclaré dans le fichier de configuration Homestead.yaml. Pour cela, taper la commande ci-dessous dans une invite de commande (ou sous Powershell):

vagrant plugin install vagrant-hostmanager

Remarques: pour que le plugin puisse éditer le fichier hosts du poste, il est nécessaire que Vagrant soit lancé en tant qu’administrateur. Par ailleurs le fichier hosts est mis à jour à chaque lancement de Vagrant (vagrant up), et uniquement sur cette commande. Pour forcer la mise à jour du fichier hosts, utiliser les commandes suivantes:

vagrant halt
vagrant up

Configuration de Hyper-v: création d’un switch virtuel

Cette étape est nécessaire pour que la machine virtuelle puisse communiquer avec internet en plus d’avoir accès au poste local (voir: limitations de Vagrant dans la prise en charge de Hyper-V).

Pour créer ce « virtual switch » ou « commutateur virtuel » en vf, il faut ouvrir le Gestionnaire Hyper-V, sélectionner le poste et cliquer sur « Gestionnaire de commutateur virtuel… » dans le menu Action.

Nouveau commutateur virtuel Hyper-V

Installation de Homestead

Récupérer la dernière release du conteneur Homestead sur Github dans un répertoire du PC (ce conteneur peut être utilisé par tous les projets Laravel) à l’aide des commandes git suivantes:

git clone https://github.com/laravel/homestead.git D:\Users\[mon_user_Windows]\dev\workspace\undergit\Homestead
cd D:\Users\[mon_user_Windows]\dev\workspace\undergit\Homestead
git checkout release

Depuis le répertoire Homestead, double-cliquer sur le fichier de commande:
init.bat. Ce script va créer plusieurs fichiers parmi lesquels se trouve le fichier de configuration Homestead.yaml à la racine du répertoire.

Éditer ce fichier Homestead.yaml et positionner le provider sur Hyper-V:

provider hyperv

Toujours dans le même fichier Homestead.yaml, configurer le mapping du répertoire source du projet sur un répertoire dédié du conteneur (sous Windows il est obligatoire d’utiliser le chemin complet du répertoire source du projet):

folders:
    - map: D:\Users\[mon_user_Windows]\dev\workspace\undergit\warinkeleril\src
      to: /home/vagrant/warinkeleril

Enfin, associer pour Nginx le nom de domaine du site sur un répertoire du conteneur:

sites:
    - map: warinkeleril.test
      to: /home/vagrant/warinkeleril/public

(une fois le conteneur lancé et pour la configuration ci-dessus, le site pourra être accédé avec l’URL http://warinkeleril.test).

Lancement de l’environnement Vagrant

Le lancement de l’environnement Vagrant doit impérativement être effectué avec les privilèges administrateur pouvoir utiliser le provider hyperv. Pour cela, lancer l’invite de commande ou Powershell en tant qu’admin.
Puis depuis le répertoire ~/Homestead, lancer l’environnement Vagrant:

vagrant up

Lors du premier lancement, l’invite demande quel « virtual switch » (commutateur virtuel) doit utiliser Vagrant. Sélectionner le commutateur Hyper-v créé précédemment.

Une seconde invite demande de renseigner l’utilisateur et le mot de passe pour monter les répertoires partagés Samba (SMB). Il faut renseigner les accréditations Windows d’un compte Administrateur du PC (compte Microsoft ou compte local).

Par la suite le lancement de la machine virtuelle doit se terminer avec une ligne ressemblant à celle-ci:

homestead: Running: C:/Users/jbh/AppData/Local/Temp/vagrant-shell20201002-22352-nsigo9.sh

A titre de test, on peut se connecter au conteneur en ssh à l’aide de la commande suivante lancée depuis le répertoire ~/Homestead:

vagrant ssh
En principe la commande « vagrant ssh » permet d’accéder au conteneur virtuel

Lancer les commandes Vagrant depuis n’importe quel emplacement du PC

la rubrique « Accessing Homestead Globally » de la documentation Homestead décrit une procédure permettant de ne plus devoir lancer les commandes « vagrant » uniquement depuis le répertoire d’installation du conteneur Homestead:

Création d’un fichier ...\dev\scripts\homestead.bat quelque part sur le PC contenant:

@echo off
set cwd=%cd%
set homesteadVagrant=D:\Users\[mon_user_Windows]\Documents\dev\workspace\undergit\Homestead
cd /d %homesteadVagrant% && vagrant %*
cd /d %cwd%
set cwd=
set homesteadVagrant=

Ajout du répertoire contenant le script ci-dessus dans la variable PATH du poste Windows (en passant par « Modifier les variables d’environnement système » puis le bouton « Variables d’environnement »).

Modification de la variable d’environnement PATH (au niveau utilisateur ou bien système)

Suite à la modification de la variable PATH, on peut tester l’installation du script en ouvrant une nouvelle invite de commande ou bien Powershell, en tant qu’administrateur, puis en saisissant simplement la commande:

homestead

Logiquement, le manuel d’aide à l’utilisation de la commande vagrant doit s’afficher.

Configurer l’application Laravel

Les paramètres du site Laravel sont regroupés dans le fichiers .env du projet et doivent être adaptés pour que ce dernier fonctionne correctement sur l’environnement Homestead: url du site, accès à la base de données, cookies…

Les paramètres d’accès à la base de données sont fournis dans la documentation Homestead. Pour mysql les valeurs attendues sont les suivantes:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret

Concernant l’URL du site, monsite.test dans notre exemple, elle doit être configurée sur les paramètres suivants (le gestionnaire d’authentification Sanctum étant utilisé dans ce projet):

APP_URL=http://monsite.test
...
SANCTUM_STATEFUL_DOMAINS="localhost,127.0.0.1,monsite.test"
SESSION_DOMAIN = "monsite.test"

Références

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *