Where Laravel developers feel right at home

It can sometimes feel like the documentation skips a few steps here and there. Other times, the documentation can feel overwhelming. Let’s demystify this process.

Goals to accomplish:

• Introduction to Homestead
• Setup Homestead on Windows 10 for all of your websites
• Create a Laravel 8 application
• SSH into Homestead and create a database
• Migrate database tables
• Verify that everything is working: able to type in domain.test in our browsers.

Introduction to Homestead

The first step, of course is to go to the Laravel documentation. We’ll follow it throughout this article so that if something changes in the documentation in the future, you can spot it and adapt to it. Also, if you do notice a change, let me know and I’ll update the content accordingly.

https://laravel.com/docs/8.x/homestead?source=post_page—–348062f07848——————————–

In the second paragraph, the docs state that “Laravel Homestead is an official, pre-packaged Vagrant box that provides you a wonderful development environment without requiring you to install PHP, a web server, and any other server software on your local machine.”

Ok cool. What is Vagrant?

Vagrant is just a tool that helps developers create predictable development environments for your application. If you’re familiar with Docker, it’s similar to that. While Docker uses containers, Vagrant uses Virtual Machines. The VM emulates an entire Operating System while containers rely on the host OS.

In a nutshell, Vagrant is a tool that helps to create and maintain Virtual Machines. You, as a software developer, will be required to maintain a Vagrant file. Well, in Homestead you’re not since Homestead manages the Vagrant file for you. Once the necessary properties are set in the vagrant file, you will be able to use the command vagrant up to start the virtual machine with the vagrant properties.

Alright, now that we understand what Vagrant is all about, let’s move on to Homestead. The documentation should make a little more sense now when it says that Homestead is just a “pre-packaged Vagrant box.” The pre-packaged Vagrant box comes with:

• Nginx web-server
• PHP
• MySQL
• Composer
• Node/npm

That means that you will not need software like XAMPP or WAMP to have a web-server with PHP/MySQL; you can do it all from your virtual machine. You can even create new Laravel projects inside of your Virtual Machine and have them synced to your local machine. Pretty cool stuff which we’ll explore later.

From the documentation, here’s the entire list of everything that’s installed and some optional software that can be installed.

The Setup with your Existing Projects

Now that you have the intro down, let’s move to the actual setup process.

1. Download and install the latest version of VirtualBox. Under VirtualBox 6.1.xx platform packages, click on Windows hosts to start the download. Run through the default setup and you can move on to the next step.

2. Install Vagrant. The page should automatically select your Operating System, so click the download button, run through the prompts, and vagrant should be installed.

3. Verify that vagrant is installed by opening up CMD or Git Bash and typing in:

vagrant --version

If you get a version number back, Vagrant has been installed successfully.

4. Now that you’ve verified that both VirtualBox and Vagrant have been installed, it’s time to “add the laravel/homestead box to your Vagrant installation.”

vagrant box add laravel/homestead

5. Time to install Homestead. You can do this by cloning Homestead into your home directory. You can add it anywhere, but Laravel suggests for your to add it to your home directory (C:/users/your-user-name) since it can serve as a central location for all of your Laravel projects. For this, use Git Bash since it will automatically translate ~/Homestead to your home directory. If you haven’t used Git Bash, it allows you to issue Linux commands on your Windows machine: such as ls to view the files/folders inside of your directory.

git clone https://github.com/laravel/homestead.git ~/Homestead

6. Navigate to the newly installed Homestead folder:

cd C:/Users/your-user-name/Homestead

or with Git Bash: cd ~/Homestead

7. The documentation states that you should check-out the latest release since the master branch may not always be stable.

cd ~/Homestead

git checkout release

8. It’s time to create the Homestead.yaml file that you will use to map your local files to your Virtual Machine. In the Homestead directory, and using Git Bash, run:

bash init.sh

If you’re following along with the documentation, you might have noticed that for Windows it states that you should run init.bat; since we’re using Git Bash, which emulates a Linux terminal, you need to run the bash command. For CMD, run ./init.bat.

9. Open the Homestead.yaml file with an IDE (such as VS Code).

---
ip: "192.168.10.10"
memory: 2048
cpus: 2
provider: virtualbox

authorize: ~/.ssh/id_rsa.pub

keys:
    - ~/.ssh/id_rsa

folders:
    - map: ~/code
      to: /home/vagrant/code

sites:
    - map: homestead.test
      to: /home/vagrant/code/public

databases:
    - homestead

features:
    - mariadb: false
    - ohmyzsh: false
    - webdriver: false

# ports:
#     - send: 50000
#       to: 5000
#     - send: 7777
#       to: 777
#       protocol: udp

Up top, the IP address is set for your Homestead Vagrant Box. If you happen to run on the same network, you can always change it. The memory allocation states how much memory you want to allow your Vagrant Box to use and the CPU’s indicate the number of CPU’s that should be allocated.

The provider should be set to virtualbox since we are using VirtualBox.

Next, the authorize and keys section is listed. These are the SSH keys to access this virtual machine. They can be commented out, or we could generate them and add them to the specified folder (~/.ssh).

10. This step is optional, but let’s do it anyway. To create the ssh keys, in Git Bash, run the following commands:

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

It will give you a prompt to specify where to generate the keys. Just press Enter to add them to your home directory (C:/Users/your-user-name/.ssh). Same goes for the passphrase. Just press Enter to leave it blank.

11. Going down the Homestead.yaml file, the next section specifies the mapping. We’re going to map the code that’s on our system to the code that’s inside the Homestead environment.

folders:
    - map: ~/code
      to: /home/vagrant/code

Let’s say that you create all of your projects inside of your Documents folder. For the sake of this example, I have a Laravel project named laravel-excel inside of my C:\Users\dinoc\Documents folder.

I will modify the Homestead file to map: C:\Users\dinoc\Documents to where I want it to appear on my Homestead environment. The property “to” shows where the code should live. So, I’ll modify that it to point to /home/vagrant/laravel-excel. The laravel-excel folder in the Homestead environment is just a folder that I’m defining right now. You can call it whatever you want; I normally stick to naming it my project name. Your folders will need to be mapped to the /home/vagrant folder on your Homestead environment.

folders:
    - map: C:\Users\dinoc\Documents\laravel-excel
      to: /home/vagrant/laravel-excel

12. Now that the mapping is complete, and Homestead knows how to access your code on your local machine, it’s time to create a test domain. This is the domain that you will be able to enter into your browser and have it run your application. You won’t have to do php artisan serve and access localhost:8080 anymore.

sites:
    - map: homestead.test
      to: /home/vagrant/code/public

So, we’ll again do some mapping. In my case I’ll map laravel-excel.test to the public folder in my code. This laravel-excel project lives in the /home/vagrant/laravel-excel directory in my Homestead environment. The public folder, the one that contains the index.php file, is just a sub-directory of that. Remember, in the previous step we mapped the local folder to the Homestead environment directory. The Homestead environment technically contains all of your files and folders for that project. One folder that it contains is /public and the laravel-excel/public folder contains index.php.

I don’t think this should be confusing, but if it is, here’s more of an explanation. If you ever ran WAMP or XAMPP on your machine, and you wanted to access your Laravel application in your browser, you could have done two different things: you could have spun up a PHP server using php artisan serve, and visited localhost: 8080, or you could have accessed it by going to the public folder http://localhost/laravel-excel/public. That’s what you’re doing here technically.

sites:
    - map: laravel-excel.test
      to: /home/vagrant/laravel-excel/public

And we’re done with the Homestead.yaml file.

13. The domain that we just created, laravel-excel.test, has to be added to the hosts file on your Windows machine. Open up Notepad as an Administrator (Right-click on Notepad and click “Run as Administrator”).

Open the hosts file: C:\Windows\System32\drivers\etc\hosts

If you haven’t modified it before, it should look something like this:

#
127.0.0.1 localhost
::1 localhost

Add a new line and add your domain. The first part is the IP address, which is listed at the top of your Homestead.yaml file (192.168.10.10), and the second part is the domain name that you just specified, laravel-excel.test.

#
127.0.0.1 localhost
::1 localhost

192.168.10.10 laravel-excel.test

Save it and exit Notepad.

14. Make sure that your Homestead.yaml file is saved. It should look something like this now:

---
ip: "192.168.10.10"
memory: 2048
cpus: 2
provider: virtualbox

authorize: ~/.ssh/id_rsa.pub

keys:
    - ~/.ssh/id_rsa

folders:
    - map: C:\Users\dinoc\Documents\laravel-excel
      to: /home/vagrant/laravel-excel

sites:
    - map: laravel-excel.test
      to: /home/vagrant/laravel-excel/public

databases:
    - homestead

features:
    - mariadb: false
    - ohmyzsh: false
    - webdriver: false

# ports:
#     - send: 50000
#       to: 5000
#     - send: 7777
#       to: 777
#       protocol: udp

Verify that you’re still inside of ~/Homestead directory in Git Bash. It’s time to spin up the virtual machine. From the ~/Homestead directory, run:

vagrant up

15. Once Homestead finishes doing its thing, you’ll be able to access the virtual machine by typing in:

vagrant ssh

If you see the screen above, you’re in a good place. Type in pwd and you’ll see that you’re in /home/vagrant. That’s why we had to map the the local laravel-excel folder to /home/vagrant/laravel-excel.

The laravel-excel project should be accessible inside of your Virtual Machine. Type ls to see all of your projects. You should see your laravel-excel folder.

16. You can now verify everything that came installed, such as PHP, MySQL, Node, npm, composer, etc.

17. Let’s do a few more things to make sure that you’re ready to see your application in the browser. Open your project in your IDE. It’s time to edit the .env file. Since Homestead is running on 192.168.10.10, you will have to set the DB_HOST to 192.168.10.10. Name your DB_DATABASE whatever you want; I’m naming mine laravel_excel. The DB_USERNAME is homestead and the DB_PASSWORD is secret.

DB_CONNECTION=mysql
DB_HOST=192.168.10.10
DB_PORT=3306
DB_DATABASE=laravel_excel
DB_USERNAME=homestead
DB_PASSWORD=secret

Save the file. Navigate back to your Virtual Box in Git Bash. If you closed it, open it back up: vagrant ssh. Remember, as of right now, you can only do the vagrant commands from the ~/Homestead directory.

Type in: mysql

Let’s create the database that we just specified:

mysql> create database laravel_excel;

Verify that the database exists:

mysql> show databases;
+-----------------------+
| Database              |
+-----------------------+
| information_schema    |
| homestead             |
| laravel_excel         |
| #mysql50#lost+found   |
| mysql                 |
| performance_schema    |
| sys                   |
+-----------------------+
7 rows in set (0.00 sec)

You can now exit MySQL.

mysql>exit;

To run your migrations, in your Virtual Environment, run your standard artisan command: php artisan migrate. You will need to CD into your project folder first.

You can get back into mysql to verify that the tables are in-fact there if you don’t trust the messages.

$ mysql
mysql> use laravel_excel;
mysql> show tables;

You can also run your npm commands from Homestead. Exit mysql and run npm install followed by npm run dev.

mysql> exit;
:$ npm install
:$ npm run dev

If you run into issues, delete your node_modules directory and run: npm install && npm run dev again.

18. Finally verify that your project is up and running. Visit laravel-excel.test in your browser and you should see your page.

 

Congratulations, you have your project running on Homestead.

19. To stop the Virtual Machine, first exit the Vagrant box by typing in exit;. Next, from your ~/Homestead directory, type in vagrant halt. This will stop vagrant. You can then try to go to laravel-excel.test and it will not work.

Creating New Projects

In the previous steps, we used an existing project. This means that at one point, I had the laravel installer installed on my Windows 10 machine. This time, let’s create a new project from inside Homestead.

1. Open the Homestead.yaml file in your editor. If you followed along, it should be in your C:/Users/your-user-name/Homestead directory.

2. In the steps above, we mapped one local project to one vagrant directory. We should have a place where we keep our Laravel projects on our system. On our system, let’s say that’s in:

C:/Users/your-user-name/Documents/Laravel_Projects

If you don’t have that directory created on your local machine, create it. Add that path to your folders mapping in your Homestead.yaml file.

folders:
    - map: 'C:\Users\dinoc\Documents\laravel-projects'
      to: /home/vagrant/laravel-projects

3. The new site that we’re going to want to create is called blog. I know, original. First, we’ll need to add that to our sites mapping.

- map: blog.test
  to: /home/vagrant/laravel-projects/blog/public

The blog project will live inside of our /home/vagrant/laravel-projects directory, since that’s the folder that we’re mapping inside of the folder section in the Homestead.yaml file (see step 2). The blog project will contain a public directory, so in order to access it, we have to point the blog.test domain to blog/public. Your Homestead.yaml file should look like this now:

---
ip: "192.168.10.10"
memory: 2048
cpus: 2
provider: virtualbox

authorize: ~/.ssh/id_rsa.pub

keys:
    - ~/.ssh/id_rsa

folders:
    - map: C:\Users\dinoc\Documents\laravel-excel
      to: /home/vagrant/laravel-excel
    - map: C:\Users\dinoc\Documents\laravel-projects
      to: /home/vagrant/laravel-projects

sites:
    - map: laravel-excel.test
      to: /home/vagrant/laravel-excel/public
    - map: blog.test
      to: /home/vagrant/laravel-projects/blog/public

databases:
    - homestead

features:
    - mariadb: false
    - ohmyzsh: false
    - webdriver: false

# ports:
#     - send: 50000
#       to: 5000
#     - send: 7777
#       to: 777
#       protocol: udp

4. Add the blog.test domain to your Windows hosts file. Again, open up Notepad as an Administrator (Right-click on Notepad and click “Run as Administrator”).

Open the hosts file: C:\Windows\System32\drivers\etc\hosts

Add the new domain at the bottom of the file.

#
127.0.0.1 localhost
::1 localhost

192.168.10.10 laravel-excel.test
192.168.10.10 blog.test

Yes, the IP address stays the same since that’s the IP address of our Homestead environment. Save the file and close it.

5. If you have your Homestead environment running, bring it down. From your ~/Homestead directory, run vagrant halt.

vagrant@homestead:~/laravel-excel$ exit;
logout
Connection to 127.0.0.1 closed.
C:\Users\dinoc\Homestead>vagrant halt
==> homestead: Attempting graceful shutdown of VM...

It’s time to re-run it and for the new changes to take effect. For the new changes to take effect, you have to pass it the provision flag:

C:\Users\dinoc\Homestead>vagrant up --provision

6. SSH into the Homestead environment and cd into your laravel-projects directory: vagrant ssh.

7. It’s time to create a new project using the laravel installer. Just run:

laravel new blog

8. On your local machine, navigate to your laravel-projects directory:

C:\Users\dinoc\Documents\laravel-projects

You will see the blog project inside of there.

That’s it. You can now work on your project. You can make changes to it in your IDE; you can use your Homestead environment to run migrations, require dependencies using composer, run npm commands, etc.

Final Touches

If you followed the steps above, the most inconvenient step is opening up your terminal and navigating to the ~/Homestead directory in order to run vagrant commands. Also, it’s Homestead. Wouldn’t it be nice to run homestead commands? Well, there’s a way, and it’s listed in the documentation.

Create a homestead.bat file and paste the following into it:

@echo off

set cwd=%cd%
set homesteadVagrant=C:\Users\dinoc\Homestead
cd /d %homesteadVagrant% && vagrant %*
cd /d %cwd%

set cwd=
set homesteadVagrant=

Make sure that you modify the location of the Homestead directory to list your username. I saved the file inside of my ~/Homestead directory for convenience:

C:\Users\dinoc\Homestead\homestead.bat

It’s time to add the homestead.bat file to the Environmental Path variable.

Search for Environmental Variables on your local machine.

 

 

Click on Edit the system environmental variables result and then click on Environment Variables…

 

 

Select the Path variable and click Edit…

 

 

Click on Browse, and navigate to your C:\Users\your-user-name\Homestead directory. Select it and press OK. You will see the Homestead directory in your list.

 

 

Click OK again and head over to a new instance of your terminal (CMD). It will not work in Git Bash. You can now substitute any vagrant command that you were running with homestead, and you don’t have to CD into the ~/Homestead directory.

C:\> homestead up
C:\> homestead ssh
C:\> homestead halt

Specifying PHP version

I know what you’re thinking: “but what if I’m running an older project that needs an older version of PHP?”

You can specify the PHP version for each project.

sites:
    - map: blog.test
      to: /home/vagrant/blog/public
      php: "7.1"

More Advanced Features

If you understand what we just did, then I suggest that you read the Laravel documentation if you have any additional questions related to more advanced features. It’s also a great source to review everything that we just did. If you had issues before, you should find the Homestead documentation pretty effortless from this point on.

https://laravel.com/docs/8.x/homestead