Quick Tip: Get a Homestead Vagrant VM Up and Running

Key Takeaways

• Homestead Improved, a version of Homestead, is recommended for setting up a new Homestead Vagrant VM for every new project due to its user-friendly features such as not requiring SSH keys, not needing global installation, being more cross-platform friendly and having a helper script for auto-configuring shared folders.
• Setting up a new site in a Homestead VM involves two steps: configuring the etc/hosts file with the desired domain name and adding a sites mapping in the Homestead.yaml file. This allows for the creation of multiple domains accessible via the browser.
• Homestead comes with pre-installed MySQL and Blackfire, a profiler for PHP apps. To connect to MySQL from the outside operating system, use a tool like Sequel Pro or the MySQL Workbench and specify the given parameters.

This quick tip will help you get up and running with a brand new Homestead Improved Vagrant VM.

• to find out about Vagrant and why you should use it, see this post.
• Homestead Improved is based on Homestead, but has the added benefit of not forcing you to deal with SSH keys, doesn’t get installed globally, is more cross-platform friendly, and comes with a helper script to auto-configure the shared folders.
• I recommend creating a new Homestead Improved VM for every new project, and this tutorial will follow such a practice.

---

Prerequisites

You need:

• Virtualbox
• Vagrant
• Git Tools if on Windows, Git otherwise (download)

The tutorial assumes you’ll be using a bash-like terminal; Git Bash if on Windows (comes with Git Tools).

Getting Started

The following 3 commands are all that’s necessary for starting a new Homestead Improved VM instance on any operating system (obviously, replace my_project with your desired folder name):

git clone https://github.com/swader/homestead_improved my_project
cd my_project; mkdir -p Project/public
bin/folderfix.sh # this is optional!

The first two clone the project and enter the newly created folder.

The third one executes the folderfix script which shares the project’s folder with the Code folder inside the VM. That means you can edit files inside the project folder (my_project) and they’ll be reflected inside the VM, and vice versa. This allows you to use your main computer’s text editor / IDE to edit the files of a project inside the VM. You can also do this manually by editing the folders field in Homestead.yaml.

Add New Sites

There are two steps to adding every new site into a Homestead VM.

Step 1: Set up etc/hosts

etc/hosts is a file present on every operating system. On Windows, it’s in C:/Windows/System32/drivers/etc/, on OS X and Linux it’s in /etc/hosts. Edit it as an administrator (one easy way to do this is to run a text editor like Sublime Text as Administrator) and add in an entry like this for every application you intend to develop:

192.168.10.10 homestead.app

Replace homestead.app with your desired domain name, or just add in multiple domain names. For example, I have this in my own hosts file:

192.168.10.10 homestead.app
192.168.10.10 test1.app
192.168.10.10 test2.app
192.168.10.10 test3.app

This means I can access each of these domains in the browser via http://homestead.app, or http://test1.app, etc.

Step 2:

For every domain you defined in the above step, you need to add a sites mapping. Open the file Homestead.yaml in the cloned copy of the Homestead Improved repo, and add a pair for each. The default is:

sites:
    - map: homestead.app
      to: /home/vagrant/Code/Project/public

This means http://homestead.app (if you added it to etc/hosts in the step above) will look for index.php in the folder /home/vagrant/Code/Project/public inside the VM. You can add this file while outside the VM, too, by simply creating a Project/public folder in the root of the cloned Homestead Improved VM, and adding index.php in there – this is the same as adding it inside the VM into the aforementioned location, because the folders are shared.

You add new sites by adding new map/to pairs (as many as you wish):

sites:
    - map: homestead.app
      to: /home/vagrant/Code/Project/public
    - map: test.app
      to: /home/vagrant/Code/test

Booting Up and SSHing

Once all the sites have been added, boot the VM with:

vagrant up

Go inside the VM with:

vagrant ssh

Once inside, you can use the VM as if it were a regular production or development linux server.

Ports and Blackfire

Homestead comes with Blackfire pre-installed. It’s a very powerful profiler for PHP apps which inspects code into great detail and draws complexity graphs which help you speed up your apps. If you have an account, uncomment the blackfire lines in Homestead.yaml and put your data in there.

If you want to open additional ports, like for example port 5000 for Heroku, uncomment the ports part of Homestead.yaml and add in the values, like so:

ports:
    - send: 5000
      to: 5000

Database Access

Homestead comes with MySQL pre-installed. Its user is homestead and its password is secret. To connect to it from the outside operating system (Homestead does not have PhpMyAdmin installed), use a tool like Sequel Pro or the MySQL Workbench and specify the following parameters:

• server / port: 192.168.10.10 / 3306 or 127.0.0.1 / 33060
• user: homestead
• pass: secret

The default homestead database should show up when you connect.

Conclusion

You should now be able to quickly set up a new VM instance for every new app you intend to build. This will allow you to seamlessly follow along with all our tutorials. Please let me know in the comments below if any of the above steps are unclear or could/should be simplified.

Common Problems

No input file specified

This means that the server in the VM cannot find the index.php file in the folder you specified under the sites block in the Homestead.yaml file. Often, this is because you added a new site when the VM was already provisioned. To fix this, exit the VM if you’re inside it, and run vagrant provision.

If this doesn’t help, it means you have a wrong mapping in the sites block, so double check to make sure there are no typos and that the folder inside the VM really exists.

Alternatively, if you’re working on a Symfony2 app, Symfony2 by default uses the web folder instead of public to host index.php. That’s why Nginx cannot find the file inside the VM. To automatically get around this problem, in Homestead.yaml under sites specify an additional value: type, like so:

sites:
    - map: homestead.app
      to: /home/vagrant/Code/Project/public
      type: symfony

This will automatically use a different serving script.

Frequently Asked Questions about Laravel Homestead Setup