homesteadddd
PHP

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.

Like Homestead? Check out our own Vagrant LAMP Box, Scotch Box

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
  <div class="tile">
    <div class="tile-full">
      <div class="alert alert-warning">
        <i class="fa fa-bolt"></i> <strong>Need more help?</strong> If you haven't used Vagrant before check out this <a href="http://scotch.io/tutorials/get-vagrant-up-and-running-in-no-time">tutorial on Vagrant</a>. If you need help setting up SSH keys, check out this <a href="http://scotch.io/tutorials/how-to-setup-ssh-public-key-authentication">tutorial on generating SSH keys</a>.
      </div>
    </div>
  </div>

  <div class="tile">
    <div class="tile-content">
      <h2>
        Adding the Laravel Box to Vagrant
      </h2>

      <p>
        Homestead is built for Vagrant. So make sure you have <a href="http://scotch.io/tutorials/get-vagrant-up-and-running-in-no-time">Vagrant installed</a>. 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:
      </p>

      <pre>


vagrant box add laravel/homestead

  <div class="tile">
    <div class="tile-content">
      <h2>
        Clone the Repo
      </h2>

      <p>
        The next step is to clone the <a href="https://github.com/laravel/homestead">Official Laravel Repository</a> onto your computer. <strong>You're not going to want to clone this where all your projects are though</strong>. 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:
      </p>

      <pre>


- 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

      <p>
        Assuming you're following this setup and are inside of the Homestead directory, you can clone the rep with this command:
      </p>

      <pre>


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

  <div class="tile">
    <div class="tile-content">
      <h2>
        Configure the Homestead.yaml
      </h2>

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

      <h3>
        IP, Memory, CPUs
      </h3>

      <p>
        The first couple of lines will look something like this:
      </p>

      <pre>

ip: "192.168.10.10"
memory: 2048
cpus: 1

      <p>
        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.
      </p>

      <h3>
        Pair Your SSH Keys
      </h3>

      <p>
        The next thing you'll need to do is set the path to your public and private keys. In the area with <code>authorize</code>, 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:
      </p>

      <pre>


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

      <p>
        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 <code>.pub</code> suffix.
      </p>

      <pre>


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

      <h3>
        Map Your Main Folder
      </h3>

      <p>
        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 <code>projects</code> 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.
      </p>

      <p>
        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 <code>Homestead.yaml</code>, it should look something like this:
      </p>

      <pre>


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

      <h3>
        Map Your First Site
      </h3>

      <p>
        The next step is to map your first site. We'll go over adding multiple sites later. For the <strong>sites</strong> 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 <code>.app</code>. I personally don't like that because <code>.app</code> is becoming a publicly available TLD for purchase (future potential security risks, bad convention). You should use the TLD <code>.local</code> as that is officially reserved for <a href="http://security.stackexchange.com/questions/14802/if-someone-bought-the-local-tld-could-that-be-a-security-risk">development</a>.
      </p>

      <p>
        The second line will be the reference to your document root or, also called, your public folder. The folder structure following <code>projects</code> 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:
      </p>

      <pre>


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

      <h3>
        And Finally, All at Once
      </h3>

      <pre>

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

  <div class="tile">
    <div class="tile-content">
      <h2>
        Update Your Host File
      </h2>

      <p>
        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:
      </p>

      <ul>
        <li>
          <strong>Mac:</strong> /etc/hosts
        </li>
        <li>
          <strong>Windows: </strong> C:\Windows\System32\drivers\etc\hosts
        </li>
      </ul>

      <p>
        You'll update this file with:
      </p>

      <pre>


127.0.0.1 site1.local

      <p>
        This is telling your computer that <a href="http://site1.local">site1.local</a> is located at the server IP address 127.0.0.1 (which is your VM).
      </p>
    </div>
  </div>

  <div class="tile">
    <div class="tile-content">
      <h2>
        Run Vagrant Up and Access Your Site!
      </h2>

      <p>
        After all this is completed, from the Homestead folder, run the following command:
      </p>

      <pre>


vagrant up

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

      <pre>

http://site1.local:8000

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

  <div class="tile">
    <div class="tile-content">
      <h2>
        Connecting with SSH
      </h2>

      <p>
        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.
      </p>

      <pre>


vagrant ssh

      <img src="http://scotch.io/wp-content/uploads/2014/07/Screen-Shot-2014-07-15-at-1.55.39-PM.png" alt="Vagrant SSH" class="img-thumbnail img-responsive" /> <p>
        That's it! The only gripe with this is you have to run the <code>vagrant up</code> 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 <code>~/.bash_aliases</code> file:
      </p>

      <pre>


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

      <p>
        Make sure you run the following to enable it:
      </p>

      <pre>


source ~/.bash_aliases

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

      <pre>


vm

      <p>
        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 <code>~/.ssh/config</code> (create it if it doesn't exist). Then add the SSH config settings:
      </p>

      <pre>


Host homestead
HostName 127.0.0.1
User vagrant
Port 2222

      <p>
        Now you can SSH into your box with this command:
      </p>

      <pre>


ssh homestead

      <p>
        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.
      </p>
    </div>
  </div>

  <div class="tile">
    <div class="tile-content">
      <h2>
        Connecting to the Database
      </h2>

      <p>
        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:
      </p>

      <pre>


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

      <img src="http://scotch.io/wp-content/uploads/2014/07/Screen-Shot-2014-07-15-at-9.47.37-PM.png" alt="Homestead Database" class="img-responsive img-thumbnail" />
    </div>
  </div>

  <div class="tile">
    <div class="tile-content">
      <h2>
        Creating Environment Variables
      </h2>

      <p>
        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 <code>Homestead.yaml</code> file, just add something like this:
      </p>

      <pre>


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

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

      <pre>


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

      <p>
        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 <a href="#adding-new-sites">Adding New Sites</a>.
      </p>
    </div>
  </div>

  <div class="tile">
    <div class="tile-content">
      <h2>
        Creating Aliases
      </h2>

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

      <p>
        When you first clone Homestead, it comes with an <code>aliases</code> 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:
      </p>

      <pre>


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
}

      <p>
        So, if you SSH into your Homestead VM using one of the many methods we learned and navigate to <code>~/.bash_profile</code>, 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.
      </p>

      <p>
        Now, you might have noticed the <code>serve()</code> function above. We'll talk about <a href="#the-serve-command">that</a> very shortly in one of the next sections.
      </p>
    </div>
  </div>

  <div class="tile">
    <div class="tile-content">
      <h2>
        Adding New Sites
      </h2>

      <p>
        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 <code>Homestead.yaml</code> file and navigate to the section with <code>sites:</code>. From here, all you have to do is map new folders to your Vagrant box. Here's what adding a site from the <code>personal</code> folder would look like :
      </p>

      <pre>


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

      <p>
        After you add that, you'll have to run the following command to provision your server again and map the new locations:
      </p>

      <pre>


vagrant provision

      <p>
        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:
      </p>

      <pre>


vagrant reload --provision

      <p>
        The cool thing about this is <strong>all your settings are saved</strong>. 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:
      </p>

      <pre>


127.0.0.1 personal1.local

      <p>
        Now if you navigate to <a href="http://personal1.local:8000">personal1.local:8000</a>, you should see your second site is now added! There's really not much to to it once you get setup.
      </p>
    </div>
  </div>

  <div class="tile">
    <div class="tile-content">
      <h2>
        The Serve Command
      </h2>

      <p>
        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 <a href="#creating-aliases">Creating Aliases</a> section, that Homestead came with a <code>server()</code> alias. This alias references a shell script that basically adds a new site and reboots NGINX.
      </p>

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

      <pre>


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

      <p>
        After that's done running you must edit your <code>hosts</code> file yet again to point <code>personal2.local 127.0.0.1</code>. Now if you visit that URL at <a href="http://personal2.local:8000">personal2.local:8000</a>, you'll see your site.
      </p>

      <p>
        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.
      </p>
    </div>
  </div>

  <div class="tile">
    <div class="tile-content">
      <h2>
        Suspending your machine
      </h2>

      <p>
        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:
      </p>

      <pre>


vagrant suspend

      <p>
        Then, when you're ready to use it again, just run <code>vagrant up</code>.
      </p>
    </div>
  </div>

  <div class="tile">
    <div class="tile-content">
      <h2>
        Conclusion
      </h2>

      <p>
        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.
      </p>

      <p>
        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.
      </p>

      <p>
        If you need help getting your site from your local Homestead environment up to a production server, I recommend checking out <a href="http://forge.laravel.com">Laravel Forge</a>. 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. <strong>The only thing is it doesn't support GitLab yet.</strong>
      </p>

      <p>
        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:
      </p>

      <ul>
        <li>
          <a href="http://laravel.com/docs/homestead">Official Laravel Forge Docs</a>
        </li>
        <li>
          <a href="https://docs.vagrantup.com/v2/">Vagrant Docs</a>
        </li>
        <li>
          <a href="http://scotch.io/tutorials/get-vagrant-up-and-running-in-no-time">Vagrant Tutorial</a>
        </li>
        <li>
          <a href="http://scotch.io/tutorials/how-to-setup-ssh-public-key-authentication">SSH Tutorial</a>
        </li>
      </ul>
    </div>
  </div>

Nicholas Cerminara

Only you can prevent forest fires.

View My Articles

Stay Connected With Us
hover these for magic

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

Yippee Ki-Yay MF

homesteadddd

Getting Started with Laravel Homestead

css-selectors

CSS Selectors You Might Not Know About

plugins2

The Complete Visual Guide to Sublime Text 3: Plugins Part 2

rotating-social-icons-page-scroll

Rotating Social Icons on Page Scroll

Sponsor: Hack Reactor Remote (beta)

scotch-panels-cover

scotchPanels.js – Dead simple Off Canvas jQuery Plugin