There are many ways to setup a local PHP development environment available to us. Traditionally there are some very common issues with each of them preventing a good generic base to teach from. Some methods are cross platform methods where others are not, some are simple to install but limited in scope, others are too difficult to grasp when you are just getting started, and you can have many issues when it is time to deploy your projects to a production environment. Laravel’s Homestead is poised to make this a thing of the past.
This tool is a very simple, yet elegant way to install a LAMP stack locally with all the packages you need to run and develop a PHP application. If you want, at any time, you can read more about this tool at laravel.com/docs/homestead I will be using this exact page as a reference throughout this process.
You will need to install the a couple of non Laravel specific packages on your system before we can really get started, but don’t worry, it is a very simple process.
The two packages, and our first steps, will be to install VirtualBox & Vagrant onto our machines. As it says on the Laravel Homestead site:
Both of these software packages provide easy-to-use visual installers for all popular operating systems.
Let’s head over to the virtualbox downloads page and get started.
The download process could take a bit of time, so perhaps its time to put the kettle on, grab a coffee, or walk the dog.
Once the download is complete you will need to follow virtual box’s package install process, leaving everything at its default.
Once you are completed with that step, it is time to move to install Vagrant.
If you are wondering about vagrant and what it does for us, their website gives a great description, simply stating it is:
an easy-to-use workflow and focus on automation
Vagrant without a doubt decreases our development environment setup time, and increases development to production similarities, making your deployment much less error prone.
Head over to the downloads page at vagrantup.com and download the vagrant install for your operating system.
Once the package is installed we can proceed to install Homestead.
Just before we jump head first into homestead let’s venture to our terminal to double check that vagrant has installed properly for us. We will do this by typing the command ‘vagrant’ at our prompt.
Your output should be similar to the following
Usage: vagrant [options] <command> [<args>] -v, --version Print the version and exit. -h, --help Print this help.
Followed by a list of common commands:
Common commands: box manages boxes: installation, removal, etc. connect connect to a remotely shared Vagrant environment destroy stops and deletes all traces of the vagrant machine halt stops the vagrant machine help shows the help for a subcommand ... etcetera
We will return eventually to some of these command and their usage, but for now this is enough validation that vagrant is installed on our system.
The next step for us will be to install the Laravel homestead vagrant image by running the following command ‘vagrant box add laravel/homestead’ – Don’t do this just yet, it is advantageous to understand what commands we are using.
In essence we are running the box command with a subcommand add, lets look at what that is doing for us by using the -h flag.
$ vagrant box add -h
Usage: vagrant box add [options] <url>
The command we are asked to run has no options and has a structured as laravel/homestead
The vagrant documentation on boxes tells us that we can discover all of the available virtual boxes at vagrantcloud.com, but to make this a bit easier to find here is a link to a search for ‘laravel’.
About mid way down the page you will see a link to ‘laravel/homestead’ which will take you to the full URL – vagrantcloud.com/laravel/homestead
This may seem like excess clicking, but my purpose here is to show you that this is where they get the term URL in the command. When you see laravel/homestead it is in relation to the ‘vagrantcloud.com/laravel/homestead’ address.
Now let’s run our box add command to add this machine to our computer.
$ vagrant box add laravel/homestead
This will take a solid amount of time as well so, time for another break!
Once this is complete you will now have the virtual machine type ready to go, next we will need to clone the homestead repository. This homestead repository is going to be the base for all of our projects during development.
When we clone the repository from github we will want to put this into a Homestead folder. I like to place my install in the home folder or user root – you can place this folder wherever you feel is best, but I will be using my home folder as a base.
Go to our user root folder
$ cd ~/
Clone the repository and give it a name of ‘Homestead’
$ git clone https://github.com/laravel/homestead.git Homestead
Change directory into the Homestead folder
$ cd ~/Homestead
Now let’s take a look around.
Looking at the Homestead.yaml specifically we will need to update the settings in this file for our vagrant box.
Here are our settings –
The ip address for our Virtual Machine, the memory the VM should use, and the number of CPUs for the VM to use are all defaulted for you. No need to change these just yet, so lets skip this and move to the next area of the configuration file.
--- ip: "192.168.10.10" memory: 2048 cpus: 1
SSH access settings to the virtual machine are set here, you will need to update the paths according to your machine’s needs.
authorize: /Users/hampton/.ssh/id_rsa.pub keys: - /Users/hampton/.ssh/id_rsa
If you don’t have a ssh key set up yet, please browse to the laravel.com homestead docs and follow the instructions under the heading “Set Your SSH Key” and enter the resulting paths like the example above.
The next section is our project folder configuration which has two sub headings of ‘map’ and ‘to’. I am going to take the description directly from the homestead docs.
The folders property of the Homestead.yaml file lists all of the folders you wish to share with your Homestead environment. As files within these folders are changed, they will be kept in sync between your local machine and the Homestead environment. You may configure as many shared folders as necessary!
The map is on your local machine, and the to is the folder on the virtual machine. Here is my configuration:
folders: - map: /Users/hampton/Homestead/Projects to: /home/vagrant/Sites
The final section is to configure your sites, or custom urls for the virtual machine, that we can use locally to access our site.
sites: - map: laravel.dev to: /home/vagrant/Sites/laravel-basics/public
Here I have mapped the domain laravel.dev to the public folder of a project; in this case I am referencing an upcoming course on the basics of the Laravel framework. You can map it to any location in your Sites folder on the virtual machine.
Now that our configuration is complete, it is time to start our new virtual machine by using the vagrant up command.
$ vagrant up
Once the machine is up after running the command you should be able to see visit the server in your browser with http://127.0.0.1
In our next post we will be discussing how to use our Homestead system. We will cover connecting to the instance through SSH, making changes to the configuration, adding new sites, connecting to databases, and general work flow concepts. If you cannot wait, I know I could not, and want to keep going, head over to the Daily Usage section of the Homestead docs to hold you over.
Until next time.
Work Hard & Have A Little Joy.