Getting up and running with a great local environment can be challenging.
It uses Vagrant to provide:
"...a wonderful development environment without requiring you to install PHP, a web server, and any other server software on your local machine. No more worrying about messing up your operating system! Vagrant boxes are completely disposable. If something goes wrong, you can destroy and re-create the box in minutes!" - Homestead docs
I prefer the 'Per Project Installation' described in the docs rather than one global install as it allows other developers to get started with very little configuration.
I've seen many people having issues getting it set up, and have had some issues myself in the past. Hopefully this article can help.
There are a few required programs before getting started. If you are a developer, chances are you will have these already. If you do, go ahead and get the latest versions to make sure everything runs smoothly. If not, download and install these three programs:
Once these are installed (and you have restarted your machine if required), we are good to get going.
First things first, open your terminal and change directory to your sites/projects folder. In my case, that's: Next, create a new project folder using Composer. I'm naming it 'my-laravel-project':
composer create-project --prefer-dist laravel/laravel my-laravel-project
This will create a new Laravel project in the folder specified. Lets change the directory to this new folder:
Next, use Composer to pull down the Homestead files into the project. This might take a few minutes depending on your connection speed. Like most processes in this article, the files will be cached and will speed up significantly on the next project install.
composer require laravel/homestead --dev
When this has finished, use the 'make' command. This will generate a 'Vagrantfile' and 'Homestead.yaml' file in the root directory, allowing us to configure the Homestead box before running it.
# Windows vendor\\bin\\homestead make # Mac / Linux php vendor/bin/homestead make
If you want to change the local URL for development, you can change 'homestead.test' to whatever you like. When doing so, ensure your particular URL is added to your hosts file, rather than 'homestead.test' (this is explained later in the article).
After the Homestead file has been (optionally) configured, you can now spin up the Virtual Machine:
Again, this might take a while, and will likely be the longest part of this process. Once the box is downloaded to your system the first time, your machine can use it from memory so it will be much quicker in the future. Sit back, let it do its thing, or go grab a coffee ☕.
Quick side-note; if you get this error:
"Check your Homestead.yaml (or Homestead.json) file, the path to your private key does not exist."
Run the following in the terminal to create the file required (it will be empty, but just needs to exist - More info here:
When the box has downloaded and started, you will need to add a hosts entry to your machine. This tells your machine to go to the IP address you provide when the relevant URL is hit.
Open the hosts file on your machine in your text editor.
On Windows, this is usually at: 'C:/Windows/System32/drivers/etc/hosts'
On Mac/Linux, this is at: '/etc/hosts'
Add a new entry at the bottom of this file. This will contain both the IP Address and URL, both of which were set in the Homestead file. It's very important that these match exactly what was added previously.
You may need to open your text-editor as an admin/superuser to save this file, depending on your setup.
After saving, open your browser and go to 'http://homestead.test' (or the URL you have set in your Homestead and hosts files) and you will see the Laravel welcome page! 🎉
Please note: if making any changes to the 'Homestead.yaml' or 'Vagrantfile' after this point, the changes won't be reflected unless you provision the box. This command will reload the box and apply any changes made:
vagrant reload --provision
You are now good to go!
To get access to the box and the features provided by Homestead, SSH into it, then change to the 'code' directory:
vagrant ssh cd code
From here, you can run NPM, composer, git and more. You can also run Laravel commands with:
Now is a perfect point to initialise the project as a git repository. Everything is set up, ready to go and untouched.
First, the '.env' file should be copied to '.env.example' for use by the other developers.
While we are at it, also add the '.vagrant' folder and 'Vagrantfile' to the '.gitignore' file as this shouldn't be added to the repository:
cp .env .env.example git init echo '.vagrant' >> .gitignore echo 'Vagrantfile' >> .gitignore git add . git commit -m "Initial commit"
At some point, you will need to connect to the database. Use your MySQL program of choice with these credentials: Connect via SSH
Once the initial commit has been pushed to a repository, it's very easy for other developers to get working locally on the project.
After cloning the project, you may notice that there is no '.env' file as it has been gitignored. There is however a '.env.example' file, which serves as a blueprint for the project's config. This should be renamed to '.env':
mv .env.example .env
They must then install vendor files and run the relevant 'make' command for the system being used. This will share and map the correct folders for Homestead to work. After that, run 'vagrant up' to start the VM:
composer install # Windows vendor\\bin\\homestead make # Mac / Linux php vendor/bin/homestead make vagrant up
The final steps are to generate a unique 'APP_KEY' in the '.env' file and run database migrations. Laravel can help with this as usual: