Recently I’ve been trying to port a custom-made PHP application to the Laravel framework. I’ve been a fan of the Laravel framework for some time now, and with the recent release of Laravel 5, there are a lot of new features that really improve upon the development pipeline, from Laravel Elixir, to full PSR-4 support.
While porting this custom made application I’ve made use of Bower to include the relevant front-end bits, and Laravel Elixir to manage them into the application. This has produced a certain number of headaches being that my production server has stringent security policies involved so near every command has included one following to change permissions. This gets old after a while.
Then I thought, “Why am I developing an application on my production server?”
Yeah, the current software I’m porting is on my production server which makes it easy to copy code over in a quick manner. Yeah, with just a small bit of configuration I setup a development sub-domain that worked on the same server. Yeah, it’s a central source. Yeah, it can become a headache still.
So I set my sights on Laravel Homestead, which is a helpful wrapper for Vagrant which will let you easily launch a virtual machine configured for Laravel development with all the necessary bits already installed. The Homestead development environment is quite a bit different from my production environment, but I’ll be able to tackle the porting of the code base later with considerable easy especially compared to what I’m dealing with in having to develop on my production server.
I currently have a few machines, but the one I do most of my work on is a Lenovo laptop running Windows 7. Most of the guides and documentation online are geared towards users who are already running *nix environments such as Mac OS X or Ubuntu, so I came across some larger learning curves which I’ll document below hopefully helping out anyone else avoid the issues I encountered.
First off, a quick break down of what Homestead is.
The underlying technology is simple VM tech. I like many are using VirtualBox, though VMWare is also supported. If you have had any VM experience, you’ll know that setting up a Virtual Machine can be tedious, configuring the resources, installing the guest operating system, installing necessary software, configuring the software, and then you’re ready to begin work, hopefully.
This is where Vagrant comes into play. Much like any entity setting up similar VMs over and over again with similar software stacks, Vagrant makes deploying VMs easy comprising of local/remote repositories of VMs to download and spin up with just a few commands.
Homestead is a set of scripts and a VM defined by Vagrant configurations that sets up a Virtual Machine that already houses most everything you would need for Laravel development with just a few simple commands.
To get started you’ll need to install a few bits of software, in the following order…
- VirtualBox – Download the latest installer for your host, in this case probably Windows, and install
- VirtualBox Extension Pack – From the same VirtualBox download page, download the extension pack and install as well
- Vagrant – Download Vagrant, install. It’ll ask you to reboot. Go ahead and do so before proceeding.
- Git – Download the Git CLI tool, this will become important because the Windows terminal is rather lacking.
Once you have all the necessary packages installed, we can go ahead and start setting up the development environment.
- Now that we have Git installed, open the “Git Bash” application. This will be the terminal interface we’ll use to perform our tasks and has many features you’d be used to in a *nix environment such as “ls” and being able to run bash scripts.
- With the “Git Bash” terminal open, it’ll default to your user directory. I took this time to create a subfolder in my user directory called “Development” which will house all of my developmental files that will be shared between the virtual machine and my Windows host machine
- Next, run the command to download the Homestead Vagrant box
vagrant box add laravel/homesteadThis will download the Homestead configured Vagrant box. It will probably take a good while to download, so grab a cup of coffee or a goblet of geuze.
- Next, we’ll clone the Homestead repository. On *nix machines you would just use Composer to download Homestead, but with the Git Bash terminal, we can clone the same scripts and execute them locally without the need for Composer/PHP installed on our host machine.
git clone https://github.com/laravel/homestead.git Homestead
- With the Homestead repository cloned, we’ll enter it. In the previous versions of Homestead the homestead.yaml file was already generated, but now that’s a manual task so we’ll have to run an additional command that will generate the homestead.yaml
- Now that we’ve generated the homestead.yaml file and the various other files needed, if you do an “ls” on the local Homestead repository directory, you’ll notice that those files are not located there. This is because it’s generated inside your user home directory in a hidden directory .homestead
- Next we’ll open our text editor or IDE and browse to that generated homestead.yaml file to configure our environment. Note that it is important to configure everything correctly before spinning up the Vagrant box or else some of the configuration files in the VM will not match and can produce errors. I’ll get into the possible errors here later down the page…
- Like I mentioned as to where the homestead.yaml file is generated, in C:\Users\Ken\.homestead\, I opened Notepad++ and edited it to look like this:
- map: ~/Development/Shared
- map: saltsmarts.app
- key: APP_ENV
- The IP address is a suggested address for your VM virtual NIC to bind to. If your local network runs on the 192.168.10.xxx network, you’ll want to change this to something else, such as 192.168.100.10
- memory can be variable, the default is 2048, I set mine to 1024 since I only have 8gb of RAM on my host machine, being that this is a very simple development VM and that I normally have a few dozen tabs open in Chrome/FF, iTunes, and a host of other resource guzzling applications.
- authorize and keys can be left set at the default as we’ll generate new SSH keys here soon in those default locations
- folders is where you’ll want to link your local host folder to the guest VM folder. This is where I linked the Development directory I created earlier.
- sites is where you’ll setup the nginx site linking. This is important to setup before spinning up the Vagrant box because if you alter it later you’ll need to reprovision the Vagrant box or manually reconfigure the nginx configuration. Here I have the domain “saltsmarts.app” mapped to the “/home/vagrant/Code/SaltSmarts/public” folder, with the thought in mind that I’ll be creating a new Laravel project by the name SaltSmarts and of course we’ll want the server to load the public directory like in any other Laravel deployment.
- databases is where you’ll setup whatever database you’d like to use, for my purposes I called it “saltSmarts”
- variables you can leave as default
- Next we’ll setup SSH keys to connect to the Vagrant box by passing the following command, substituting your email address.
ssh-keygen -t rsa -C "firstname.lastname@example.org"Make sure to not use a passphrase on the SSH key as that will hang the box on start up
- Next we’ll want to map the “saltsmarts.app” domain to the VM. To this we’ll need to open Notepad as Administrator (search the Start Menu for “Notepad” and right click to “Run as Administrator”). From there, we’ll use the menu “File > Open” and browse to “C:\Windows\system32\drivers\etc” and at the bottom next to “File name” there’s a drop down box listing “Text documents (.txt)” click on that and select “All Files (*.*)” to list all the files in the directory and open “hosts”
- With the “hosts” file open in Notepad, at the bottom of the file add the IP address listed in your homestead.yaml file linking to the saltsmarts.app domain. At the bottom of my hosts file I added the following line
192.168.10.10 saltsmarts.appSave and exit Notepad.
That’s it! Now we’re ready to bring our Vagrant box up. Switch back to the Git Bash terminal and run the following command from the ~/.homestead directory
This will provide a few lines of output, hopefully it will successfully boot the VM. If it gives you a few Warnings about the connection timing out, no worries this just means the VM hasn’t booted to a state ready enough to connect to, just let it run the reconnect attempts.
If it gives you an error about the VM entering “gurumeditation” status, just run the following command
vagrant haltThen load the VirtualBox GUI, and manually boot the VM watching for error messages. Send the GUI loaded VM the ACPI shutdown signal, and try booting via “vagrant up” again.
Next we’ll connect to the VM via SSH to install Laravel. To do this, you run the simple command
vagrant sshFrom there you’ll be connected to the VM via SSH and can install Laravel via Composer like you normally would do. To make everything link nicely, I installed the new Laravel project to “/home/vagrant/Code/SaltSmarts”
That’s the bulk of it, most everything else is ready to rock and roll from here. The documentation is handy for general operation and administration of the box, but ideally you won’t need much other configuration or doctoring.
Errors and Caveats
- If you didn’t setup the folders and sites initially before the box was brought up and provisioned you might run into the “No input file specified” error when you browse to your VM. This is an issue with nginx not knowing where to load the Laravel project from. You can reconfigure the directory paths by editing the file found in “/etc/nginx/sites-enabled/” to reflect those path changes and restart the nginx service to reload the configuration.
- If there is an error generated while spinning up the VM regarding improper SSH keys, don’t fret it’ll automatically generate new keys but you might have to bring the VM up and down a few times for it to properly generate.
- Be wary of using tabs in your homestead.yaml file, evidently it does not process tabs correctly so make sure to only use spaces. There are no real errors generated when it can not parse the homestead.yaml file, it just fails softly.