Laravel Homestead is a pre-configured Vagrant box along with some tooling to simplify administration of said box. For the uninitiated: Vagrant basically boils down to elegant tooling for virtual machines, radically reducing the effort needed to e.g. setup local testing environments like Homestead for Laravel.

Preconfiguration

To get Vagrant running, a virtual machine runner is required. I usually turn to Virtual Box for that. Thus, go ahead and grab the latest version from the downloads section now.

After having installed Virtual Box, your system is ready for Vagrant, the download page for which is here.

Actually setting up

Personally, I like to set up my test servers as projectname.dev, e.g. this website’s dev version is accessable as meanderingsoul.dev on my machine. As long as one is running the websites from OS X’s packaged Apache, everything is great and dandy but as soon as one leaves that comfort zone for something more elaborated like a vagrant box, things get a little bit messy. The above presented URL scheme requires binding a webserver to port 80 which is disallowed by operating systems for user processes. And one simply does not want to run stuff as root all the time. But there’s a fix for that, which I’ll explain in detail below. Right now, it’s time to fire up the terminal and get stuff configured.

1
2
3
4

# Add the homestead box to your vagrant repository
$ vagrant box add laravel/homestead
# Clone the Homestead configuration to a convenient place (you'll need it to start, stop and reconfigure the box)
$ git clone https://github.com/laravel/homestead.git Homestead

To configure Homestead, refer to the official documentation (linked above). What is important for setting up the environment to work with projectname.dev URLs is to adhere to the following URL scheme:

1
2
3

sites:
    - map: projectname.dev
      to: /home/vagrant/Code/ProjectName/public

The official documentation also advises you to add aliases for all mapped hosts into your /etc/hosts file. I usually go about that by typing

1

$ sudo echo "127.0.0.1 projectname.dev" >> /etc/hosts

to amend the added hostname to the list. This is not the most organized way to edit the hosts file and there are more elaborate options like nameservers if you need to manage lot’s of virtual hosts. But it should do for most cases.

At this point, you could just vagrant up the homestead box and access your projects via http://projectname.dev:8000. But nobody likes these port suffixes, right? So let’s get rid of them.

Enter Apache. OS X (even Mavericks) comes with a bundled version of the Apache Foundation’s httpd, much better known as the Apache Webserver or just Apache. Webservers, apart from serving content they have direct access to, are also usually capable of proxying requests to other hosts. This is especially handy in the current situation since the bundled apache runs as a system process and is therefore able to attach to port 80. What’s missing is a proxy configuration that transparently forwards every request to http://projectname.dev to http://projectname.dev:8000. Assuming that you did not mess with your systems’ Apache configuration before you can just paste the following into /etc/apache2/other/homestead.conf. If you messed with the config, you most certainly know how to unmess it such that this works.

1
2
3
4
5
6

<VirtualHost *:80>
    ProxyPreserveHost On
    ProxyRequests Off
    ProxyPass / http://localhost:8000/
    ProxyPassReverse / http://localhost:8000/
</VirtualHost>

Starting Apache is as simple as apachectl start. If everything went fine, you should see your Laravel site at http://projectname.dev in your browser. In a future post, I am going to explain how to automate the start-up process with launchd.

One more thing

Homestead’s machine name is homestead. If you’re using machine name based environment detection in Laravel you may want to add that hostname to the list of your local hostnames.

[Update] Yosemite

Sometimes, when updating to Yosemite, the system replaces Apache’s httpd.conf with it’s default version. You may thus need to include your homestead host config again. (Hint: This only applies to you if opening one of your .dev hosts results in the displayal of “It works!”)