Logo MicroTUTO.fr textuel
Installer Laravel Homestead sous Hyper-v (Windows 10)

2 octobre 2020

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

Attention l’installation de Hyper-v nécessite en principe de faire tourner Windows 10 professionnel (il est possible d’installer Hyper-v sur Windows 10 Home, mais c’est un peu plus compliqué).

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

Hyper-v: configuration 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).

Remarque importante: j’ai rencontré des difficultés avec la configuration de ce switch virtuel (nécessaire uniquement lorsqu’on utilise Vagrant sous Hyper-v), dont la création affectait la connexion internet de mon PC. J’ai fini par ne plus l’utiliser, pour le moment sans difficultés (et de manière surprenante, la machine virtuel associée au switch par défaut sur le réseau interne dispose cependant de l’accès à internet).

Pour créer ce « virtual switch » ou « commutateur virtuel » en version française, il faut ouvrir l’utilitaire « Gestionnaire Hyper-V » sous Windows 10, 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: monsite.test
      to: /home/vagrant/monsite/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.

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 Microsoft 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

Complément: Vagrant crée le fichier de la clé privée (Homestead\.vagrant\machines\homestead\hyperv\private_key) en lui conférant des droti d’accès uniquement pour l’utilisateur renseigné sur la console. Ceci m’a posé des problèmes sur mon poste car l’application en charge du backup des fichier ne parvenait pas à accéder à ce fichier particulier – j’ai du ajouter manuellement des droit au ‘groupe Administrateur’ de mon poste.

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=monsite.test
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"

Homestead / Vagrant: commandes utiles

Les commandes homestead ci-dessous nécessitent l’installation du script « homestead.bat » décrite plus haut. Elles peuvent être remplacées par les même commandes vagrant lancées depuis le répertoire d’installation du conteneur Homestead.

Statut des machines virtuelles vagrant:

homestead global-status

Lancement de la machine vituelle:

homestead up

Accèder à la machine virtuelle en ssh:

homestead ssh

Références

0 commentaires

Soumettre un commentaire

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

Related Articles

Raspberry Pi 4 : installer un serveur Minecraft sous Raspbian

Un proche souhaite installer et administrer un serveur Minecraft. Faute de le faire sur le PC familial qui n'a pas vocation à rester allumé en permanence, le Raspberry Pi est un candidat idéal pour ce type de besoin. J'ai utilisé un Raspberry Pi 4 avec 2 Go de RAM, ce...

Laravel 7: authentification d’une application SPA avec Sanctum

Cet article présente l'installation du package Sanctum (ex-Airlock) sur une application Laravel SPA (Single Page Application) afin de protéger une partie des ressources exposées dans l'API Laravel par une authentification classique (login / mot de passe). Il s'agit...

Laravel 7: une application SPA avec Vue.js

Cet article décrit les premières étapes pour afficher des ressources protégées dans une page Vue.JS, dans le cadre de la mise en place d'une application avec une seule page Web (SPA ou Single Page Application). Le point de départ de l'article est un projet Laravel 7...