Web Foundations

Quick Tip: Get a Homestead Vagrant VM Up and Running

    Bruno Skvorc
    Share

    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:

    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.

    CSS Master, 3rd Edition