This post has been more than 5 years since it was last updated.
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
- 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 [email protected]: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:
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:
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:
- **Windows: **
You’ll update this file with:
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:
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!
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.
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:
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:
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:
Then, when you’re ready to use it again, just run
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:
All Rights Reserved