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.

Before launching your Homestead environment, you must install VirtualBox or VMWare as well as Vagrant. All of these software packages provide easy-to-use visual installers for all popular operating systems.

To use the VMware provider, you will need to purchase both VMware Fusion / Workstation and the VMware Vagrant plug-in. VMware provides much faster shared folder performance out of the box.

PHP Stack and More

The Homestead included software

• Ubuntu 14.04 – Easy to use and familiar OS
• PHP 5.6 – The latest stable build of PHP
• HHVM - to achieve superior performance while maintaining the development flexibility that PHP provides.
• Nginx – Faster, better performing, and easier to configure web server
• MySQL
• Postgres
• Node (With PM2, 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 Envoy – Laravel’s Task Runner
• Blackfire Profiler

Installation & Setup

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

If this command fails, you may have an old version of Vagrant that requires the full URL:

vagrant box add laravel/homestead https://atlas.hashicorp.com/laravel/boxes/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/
--site-1/
-----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.

Setting Your Provider

The provider key in your Homestead.yaml file indicates which Vagrant provider should be used: virtualbox, vmware_fusion, or vmware_workstation. You may set this to whichever provider you prefer:

provider: virtualbox

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: ~/home/mon/.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:
- ~/home/mon/.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/pc). 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: /www/projects
to: /home/vagrant/projects

Map Your First Site

The sites property allows you to easily map a "domain" to a folder on your Homestead environment. A sample site configuration is included in the Homestead.yaml file. Again, you may add as many sites to your Homestead environment as necessary. Homestead can serve as a convenient, virtualized environment for every Laravel project you are working on:

sites:
- map: laravelsite.local
  to: /home/vagrant/projects/laravel-site/public

You can make any Homestead site use HHVM by setting the hhvm option to true:

sites:
- map: laravelsite.local
  to: /home/vagrant/projects/laravel-site/public
  hhvm: true

And Finally, All at Once

provider: virtualbox
ip: "192.168.10.10"
memory: 2048
cpus: 1

authorize: ~/home/mon/.ssh/id_rsa.pub

keys:
- ~/home/mon/.ssh/id_rsa

folders:
- map: ~/www/projects
to: /home/vagrant/projects

sites:
- map: laravelsite.local
  to: /home/vagrant/projects/laravel-site/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/Linux: /etc/hosts
• **Windows: ** C:\Windows\System32\drivers\etc\hosts

You’ll update this file with:

192.168.10.10 laravelsite.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

Make sure the IP address listed is the one you set in your Homestead.yaml file. Once you have added the domain to your hosts file, you can access the site via your web browser!

http://laravelsite.local

So long that you have an index.php file located in the public folder you mapped (/www/projects/laravelsite/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

To access Ubuntu on VM

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: thanhmeoow
- 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 "thanhmeoow"
$api_secret = getenv('API_SECRET'); // returns "meowmeowmeow"

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/site-1/public
- map: site2.local
to: /home/vagrant/projects/site-2/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 site1.local

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

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

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:

• Official Laravel Forge Docs
• Vagrant Docs
• Vagrant Tutorial
• SSH Tutorial