homestead-virtual-box

How to install the Laravel Homestead virtual machine

Starting our Laravel learning journey we will see how to install the Laravel Homestead virtual machine.

Thus we will have a suitable development environment with a web server and PHP in addition to some of its extensions. Also Composer and other software such as Node that will be needed as the learning advances.

Environment preps

The task of preparing a computer so that it becomes a Laravel development environment can be done in several ways.

One of these would be to use a LAMP, WAMP, XAMPP package, or a virtual machine with only the operating system and install everything else (PHP, web server, Composer, Node etc.) on your own.

However, this option is laborious and can be quite time consuming, because, depending on your environment, it may require a few hours of research on the internet to adjust settings and obtain the necessary software.

The creators of Laravel aiming to streamline the task of setting up an environment in order to make the development as pleasant as possible provide a virtual machine that comes with everything you will need to start developing using this framework.



The Homestead virtual machine

I believe that virtual machines are nothing new for you, most developers already use them on a daily basis for various tasks, including system testing.

Laravel Homestead is framework’s official box and it is in the Vagrant format providing a pre-installed and configured package with everything you will need to start with Laravel. Thus eliminating the need for PHP, web server, and other software to be installed on your local machine.

It is possible to make use of this virtual machine on Windows, Mac and Linux systems. However, in this text we will assume that you are installing on a Windows system.

Installing required software

Before installing the Laravel Homestead virtual machine it will be necessary to have in your system Virtual Box 6.x and the latest version of Vagrant.

It is also highly recommended that you install GIT to clone the Homestead machine’s GitHub project.

It is possible to download directly from the repository without the need to install GIT, but nowadays it is difficult to imagine a software developer who does not use GIT, so the sooner you start using it the better.

Let’s start by installing these three softwares, for that download and install them using the links below:

Installing Homestead box

After installing the programs open up your favorite cli (command line interface, i.e. command prompt, terminal etc.) and run the following command:

vagrant box add laravel/Homestead

Select virtualbox as the provider, which in this case is option 3, see the screen below:

Instalação da Laravel Hometead
Running the command: vagrant box add laravel/homestead

Note: if occurs the error:

URL: ["https://vagrantcloud.com/laravel/homestead"]  Error: SSL certificate problem: self signed certificate in certificate chain 

It is likely due to a known incompatibility with some antivirus, especially Kaspersky. So to continue installing Homestead try temporarily pausing the antivirus and reactivating it after completing this operation.

But if even deactivating the anti-virus, the problem persists then you will have to add the –insecure parameter, according to the command line below:

vagrant box add --insecure laravel/Homestead

Be warned that downloading Laravel Homestead can take a while, so it’s time to have a little patience and take the time to relax.

When the process is complete (maybe a cup of coffee or two after) and the prompt is available again, type the following commands in sequence:

git clone https://github.com/laravel/homestead.git Homestead
cd Homestead
init.bat
mkdir C:\Homestead\project01

At the end of this step, if everything went well, you will have a Laravel Homestead machine almost ready to run. It is lacking only a few configurations that we will do in the next topic.

In addition, we created the folder C:\Homestead\project01 which will be the location where the files of our first Laravel project will be stored.




Configuring the Laravel Homestead virtual machine

After installation it will be necessary to configure some operating parameters of Laravel Homestead, all settings will be made by changing fields in the file Homestead.yaml.

Once again we are assuming that you are in a Windows system, then now in your user profile there must be folder named Homestead and within it the file Homestead.yaml.

Note: The init.bat command performs the initial configurations of the Homestead machine; it creates the file Homestead.yaml that we will edit in this section.

If this yaml file does not exist, you can make a copy of the example file using the command below

copy Homestead.yaml.example Homestead.yaml

Use your preferred text editor to change the file Homestead.yaml (%USERPROFILE%\Homestead\Homestead.yaml) making the following changes:

ip: "192.168.0.10"

 folders: 
  - map: C:\Homestead\project01 
  to: /home/vagrant/mysite

 sites:  
    - map: "192.168.0.10"
 to: /home/vagrant/mysite/public

Note: On some systems may occur an address conflict that will cause the virtual machine to not run or become inaccessible on your network. If it is your case try to use an IP address different from the one informed above.

Starting up the Homestead machine

Having made the change to the Laravel Homestead configuration file, just start the box using the command below:

vagrant up

Note: to start a box that is in another folder you will need to know its ID, using the vagrant global-status command and then run vagrant up by passing the ID as a parameter. See the screen below:

Iniciando a máquina Homestead
Starting up a Homestead machine located in another folder

Troubleshooting – generating SSH key

In case it is not possible to start up the Homestead machine due to the error below:

Check your Homestead.yaml (or Homestead.json) file, the path to your private key does not exist. 

You will need to generate an SSH key using the following command: 

ssh-keygen -t rsa -C "yourname@homestead"

This command does not exist natively on Windows command prompt; so, to run it you must install GIT for Windows and use the Git bash application which supports the ssh-keygen command.

After generating the keys, verify in Homestead.yaml file if the authorize and keys properties are indicating the correct path for the newly created ssh keys.

New Laravel project

Finally, we will create a new Laravel project using the commands below:

vagrant ssh
laravel new mysite

The first command will open a shell inside the Homestead machine, so don’t be surprised by the change in the command line interface.
The second one will be responsible for the creation of the new Laravel project.

Then to test the installation just point the browser to the url:

http://192.168.0.10

Tela inicial do site padrão após instalação do Laravel Homestead
Home screen of the standard Laravel website

The image above is the home screen of the Laravel’s scaffold application, it is from there that we will start the development of our own web site.

To access the application, we must type in the browser the IP address of the virtual machine that was defined in the configuration file Homestead.yaml.



Vagrant commands

To conclude this posts below are some Vagrant commands that will be useful during the development of our applications:

Command Variation Function
vagrant -v   shows the Vagrant’s version
vagrant halt   shuts down the virtual machine
vagrant up   starts up the virtual machine
  vagrant up <id> turns on a machine located in another folder
vagrant status   displays the virtual machine status
  vagrant global-status displays the status and id of all available machines in the system
vagrant ssh   opens up a secure shell section that allows you to execute commands inside the virtual machine
  vagrant ssh
sudo shutdown now
as a example, another way to turn off Homestead would be to run these commands
vagrant reload –provision   used to reload the virtual machine after changes to its configuration files

To know more

To learn more about the subjects we cover here you can consult the links below:
https://www.vagrantup.com/docs/cli
https://laravel.com/docs/7.x/homestead

That’s it, see you in another post. If you want to give me some feedback, feel free to write down there. Thank you.

See also:
eBook chatbot with Laravel Botman Studio and Dialogflow