Quick Tip: Get a Homestead Vagrant VM Up and Running
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.