homesteadddd
Tutorials

Getting Started with Laravel Homestead

Once you get your development environment integrated with Vagrant, development becomes easier, more efficient and even more fun. The only problem is Vagrant has a little bit of a learning curve to it. It’s one thing to get started using Vagrant, but it’s a whole different thing to start configuring and provisioning a custom server with certain requirements using Chef or Puppet.

Not all of us have the luxury of having an Ops team or the skill-set of a DevOp. If you don’t already know, Laravel has a generally more strict set of server requirements than your typical PHP frameworks and projects. This isn’t a bad thing. It just means Laravel can do more and uses tons of cool modern features. Homestead is Laravel’s answer to all this. Homestead is a pre-packaged Vagrant box that has all the necessary PHP features to use Laravel and then some additional cool features.

Heads up! Homestead requires you to have a basic understanding of Vagrant. If you read this article, it will bring fully up to speed on it.

What is Laravel Homestead?

Laravel Homestead is a pre-packaged Vagrant Box and Vagrant setup. I would say it’s a little bit different than your normal or typical Vagrant setup. There’s no provisioning using Chef or Puppet. You basically are just flashing a preconfigured server image with Vagrant. Personally, I love this. This is simple for small teams, fit for small to medium size projects, less room for Vagrant errors across versions and OSs, it boots and provisions ultra-fast, and it’s enough to get anyone started with Laravel in seconds.

No need to setup a server. No need to configure a complex Vagrant setup. It let’s you focus on the code.

One VM to Rule Them All

If you use Vagrant with multiple projects, you’ll find that your Virtual Box will start filling up with tons of VMs and taking up space on your computer like the photo below.

Before using Laravel Homestead

Before using Laravel Homestead

Homestead not only provides you with a very appealing PHP Stack for your VM, but it also is setup to so you can manage multiple sites and projects from a single VM!

After using Laravel Homestead

After using Laravel Homestead


PHP Stack and More

Laravel Homestead comes featured pack. Not only does it cover the minimum requirement to use Laravel, it also uses the latest and coolest tools that will supercharge your apps and websites. It includes:

  • Ubuntu 14.04 – Easy to use and familiar OS
  • PHP 5.5 – The latest stable build of PHP
  • Nginx – Faster, better performing, and easier to configure web server
  • MySQL
  • Postgres
  • Node (With Bower, Grunt, and Gulp) – All your Front-End tools and task runners
  • Redis – High performing Key Value Store and caching
  • Memcached – More caching tools
  • Beanstalkd – Easy to use Queue server
  • Laravel EnvoyLaravel’s Task Runner
  • Fabric + HipChat Extension
Need more help? If you haven’t used Vagrant before check out this tutorial on Vagrant. If you need help setting up SSH keys, check out this tutorial on generating SSH keys.

Adding the Laravel Box to Vagrant

Homestead is built for Vagrant. So make sure you have Vagrant installed. Then, all you have to do is download and add the box to Vagrant. You can do this in one command from the command line:


vagrant box add laravel/homestead

Clone the Repo

The next step is to clone the Official Laravel Repository onto your computer. You’re not going to want to clone this where all your projects are though. As you will find out, with Homestead you’re actually mapping all your projects to their folders on your computer. Homestead actually acts as just a manager for your all your other projects. So you’ll want to put this somewhere outside of your projects folder. For example, you could do something like this:


- projects/
- - - work/
- - - - - - work-site-1/
- - - - - - - - - public/
- - - - - - work-site-2/
- - - - - - - - - public/
- - - - - - work-site-3/
- - - - - - - - - public/
- - - personal/
- - - - - - personal-site-1/
- - - - - - - - - public/
- - - - - - personal-site-2/
- - - - - - - - - public/
- - - - - - personal-site-3/
- - - - - - - - - public/
- homestead/
- - - Clone Homestead in this folder

Assuming you’re following this setup and are inside of the Homestead directory, you can clone the rep with this command:


git clone git@github.com:laravel/homestead.git .

Configure the Homestead.yaml

The next step is to setup your Homestead.yaml file. This is really the only file that you need to go into to edit. So go ahead and open it up in your favorite editor.

IP, Memory, CPUs

The first couple of lines will look something like this:

 
---
ip: "192.168.10.10"
memory: 2048
cpus: 1

The default settings should work for most people. I would just leave this alone, but feel free to adjust it if you really feel it is necessary on your machine.

Pair Your SSH Keys

The next thing you’ll need to do is set the path to your public and private keys. In the area with authorize, you’ll reference the path to your public key on your laptop. If you’re on a Mac, there’s a good chance all you’ll have to do is replace where it says “me” with your computer’s User name. Here’s mine:

 
authorize: /Users/Nickie/.ssh/id_rsa.pub

Your next step is to set the path to your machine’s private key. In most cases, it will be the exact same as above without the .pub suffix.

 
keys:
- /Users/Nickie/.ssh/id_rsa

Map Your Main Folder

Now, you’ll want to map the main folder where all your projects are going to be. If you followed the example above, it will be the projects folder. I think it goes without saying that your Homestead main folder should not be in the folder you are mapping. If it is, you’ll have to readjust how you things have arranged and setup.

The first line is the location of the folder on your local machine (your laptop). The second line is where it’s going to be on the Virtual Server. You could technically do this however you want and map these in all sorts of places. If you’re unfamiliar with this, just try and follow the example as closely as possible. So, for the “folders” section of Homestead.yaml, it should look something like this:

 
folders:
- map: /Users/Nickie/Development/projects
to: /home/vagrant/projects

Map Your First Site

The next step is to map your first site. We’ll go over adding multiple sites later. For the sites section, the “Map” Key references the hostname that you are calling your project. You can literally call this about anything, but you should stick to a convention that makes sense. For example, Homestead’s default uses .app. I personally don’t like that because .app is becoming a publicly available TLD for purchase (future potential security risks, bad convention). You should use the TLD .local as that is officially reserved for development.

The second line will be the reference to your document root or, also called, your public folder. The folder structure following projects should be identical to how you have it setup inside of the projects folder. Everything inside the projects folder is mapped and shared to the VM automatically with Vagrant, but you need to make sure the path is correct and matches up. Here’s what my setup looks like for this part:

 
sites:
- map: site1.local
to: /home/vagrant/projects/work/work-site-1/public

And Finally, All at Once


---
ip: "192.168.10.10"
memory: 2048
cpus: 1

authorize: /Users/Nickie/.ssh/id_rsa.pub

keys:
- /Users/Nickie/.ssh/id_rsa

folders:
- map: /Users/Nickie/Development/projects
to: /home/vagrant/projects

sites:
- map: site1.local
to: /home/vagrant/projects/work/work-site-1/public

Update Your Host File

Now, using the hostname that chose for your first site, we’ll need to update your computer’s local host file. Edit this file with administrative privileges. They are located:

  • Mac: /etc/hosts
  • Windows: C:\Windows\System32\drivers\etc\hosts

You’ll update this file with:


127.0.0.1 site1.local

This is telling your computer that site1.local is located at the server IP address 127.0.0.1 (which is your VM).

Run Vagrant Up and Access Your Site!

After all this is completed, from the Homestead folder, run the following command:


vagrant up

After Vagrant is finished you can now access your site by visiting the URL you setup in your host file followed by port :8000.



http://site1.local:8000


So long that you have an index.php file located in the public folder you mapped (/Users/Nickie/Development/projects/work/work-site-1/public), you’ll be able to visit that URL. That’s it! You’re now up and running with your first Homestead local development environment.

Connecting with SSH

It’s really easy to SSH into your Vagrant box. The quickest way is to run the following command when you’re in the Homestead folder from the command line.


vagrant ssh

Vagrant SSH
That’s it! The only gripe with this is you have to run the vagrant up command from within the Homestead folder, but all your project folders are mapped and located in a completely separate folder. So every single time you want to SSH into the Vagrant box you would have to navigate back to the Homestead folder in the terminal which is kind of annoying. There’s a ton of shortcuts for this though. Laravel’s official recommendation is to add this to your ~/.bash_aliases file:


alias vm='ssh vagrant@127.0.0.1 -p 2222'

Make sure you run the following to enable it:


source ~/.bash_aliases

Now you can just run the following from anywhere in the terminal to SSH into your box:


vm

That’s a pretty cool method, but I personally don’t like to create aliases for SSH since the functionality for SSH shortcuts is actually built into SSH itself. Navigate to the file ~/.ssh/config (create it if it doesn’t exist). Then add the SSH config settings:


Host homestead
HostName 127.0.0.1
User vagrant
Port 2222

Now you can SSH into your box with this command:


ssh homestead

This feels more natural to me to use. You can however use whichever method you prefer though. In reality, it really doesn’t matter and is up to you.

Connecting to the Database

When Homestead is provisioned, MySQL is already installed with a root MySQL user. This is extremely convenient for accessing and managing your databases. Using Sequel Pro (or Navicat or some other similar software), you can connect to the database with these credentials and create as many databases as you want:


Host: 127.0.0.1
User: homestead
Password: secret
Port: 33060

Homestead Database

Creating Environment Variables

With Laravel Homestead it’s actually really easy to create server environment variables. You can use this for various things such as passwords, API Keys, and other global config settings. You can add however many as you want. At the bottom of your Homestead.yaml file, just add something like this:


variables:
- key: APP_ENV
value: local
- key: API_KEY
value: 123abc
- key: API_SECRET
value: meowmeowmeow

Then, with PHP you can simply call the value of any of those by doing:


$app_env = getenv('APP_ENV'); // returns "local"
$api_key = getenv('API_KEY'); // returns "123abc"
$api_secret = getenv('API_SECRET'); // returns "meowmeowmeow"

Each time you add a new variable, you’ll have to provision the server again. You’ll learn how to do that in the section about Adding New Sites.

Creating Aliases

Earlier we created an alias on our laptop to be able to SSH into Homestead by just running vm. Aliases come in real handy when running command line tasks. You can literally create a shortcut for just about anything.

When you first clone Homestead, it comes with an aliases file. You can use this file to add, edit, and remove command line aliases on the fly. This is nifty if you want to save a long command to use that you know you’ll have to use once you SSH into the VM. Homestead by default comes with the following aliases:


alias ..="cd .."
alias ...="cd ../.."

alias h='cd ~'
alias c='clear'

function serve() {
if [[ "$1" && "$2" ]]
then
sudo dos2unix /vagrant/scripts/serve.sh
sudo bash /vagrant/scripts/serve.sh "$1" "$2"
else
echo "Error: missing required parameters."
echo "Usage: "
echo "  serve domain path"
fi
}

So, if you SSH into your Homestead VM using one of the many methods we learned and navigate to ~/.bash_profile, you’ll see all these aliases were copied here. Anytime you want to add an alias, just add it to that file, and then provision the server.

Now, you might have noticed the serve() function above. We’ll talk about that very shortly in one of the next sections.

Adding New Sites

Homestead is really one VM to rule them all. So let me show you how you can map and add additional sites and projects. Go back into your Homestead.yaml file and navigate to the section with sites:. From here, all you have to do is map new folders to your Vagrant box. Here’s what adding a site from the personal folder would look like :


sites:
- map: site1.local
to: /home/vagrant/projects/work/work-site-1/public
- map: personal1.local
to: /home/vagrant/projects/personal/personal-site-1/public

After you add that, you’ll have to run the following command to provision your server again and map the new locations:


vagrant provision

This command doesn’t always work though. It doesn’t always work for me, so I would bet it wouldn’t work for some others as well. I always run this command instead:


vagrant reload --provision

The cool thing about this is all your settings are saved. You don’t have to worry about losing your databases, files, or anything. After the box is done “rebooting” with the new settings, make sure you add the site to your host file with the new reference:


127.0.0.1 personal1.local

Now if you navigate to personal1.local:8000, you should see your second site is now added! There’s really not much to to it once you get setup.

The Serve Command

If you’re really daring, you can use the Laravel Homestead Serve command to add additional sites. This is probably for more experienced ops people, but it’s actually not too bad to use. You probably noticed from the Creating Aliases section, that Homestead came with a server() alias. This alias references a shell script that basically adds a new site and reboots NGINX.

You can use this to create new sites without having to deal with Homestead.yaml or running vagrant reload --provision. To use it, all you have to do is SSH into your Homestead vm and run the following command:


serve personal2.local /home/vagrant/projects/personal/personal-site-2/public

After that’s done running you must edit your hosts file yet again to point personal2.local 127.0.0.1. Now if you visit that URL at personal2.local:8000, you’ll see your site.

This method is a lot quicker than the typical Vagrant and Homestead.yaml way. I kind of like using Homestead.yaml because it keeps track of all the sites and mapped folders outside of the VM. It’s a great reference to use, but it’s up to you on how comfortable you feel using this.

Suspending your machine

Lastly, I wanted to quickly touch base on suspending your VM. You should do this before you power your computer off. Most people with some Vagrant experience know this, but to do this, just navigate to the Homestead folder and run the following command:


vagrant suspend

Then, when you’re ready to use it again, just run vagrant up.

Conclusion

This is pretty much all you need to know to get started with Homestead. Homestead provides the perfect tool to start developing with Laravel. It lets you focus on the code and not the server, but at the same time, it eases you into getting more familiar with the server environment.

If it wasn’t already obvious, you can use this for all sorts of projects such as WordPress or other PHP frameworks. At the end of the day, Homestead might be supercharged for Laravel, but it’s still just a really awesome and easy to use PHP virtual machine.

If you need help getting your site from your local Homestead environment up to a production server, I recommend checking out Laravel Forge. They provide easy tools to deploy with the click of a button from GitHub or BitBucket to an Amazon or Digital Ocean server. It takes all the pain out of managing a server for you. The only thing is it doesn’t support GitLab yet.

Thanks for reading this article and I hope it helped some people get started. If you need to check some additional resources, visit the links below:

Stay Connected With Us
hover these for magic

Get valuable tips, articles, and resources straight to your inbox. Every Tuesday.