Laravel Homestead Setup Guide

Setting up a development environment shouldn't take hours. Laravel Homestead is an official, pre-packaged Vagrant box that provides a perfect development environment without requiring you to install PHP, web server, or database on your local machine. At ZIRA Software, Homestead is our standard for Laravel development.

What is Homestead?

Homestead is a pre-built Vagrant box (virtual machine) that includes:

Ubuntu 14.04
PHP 5.6
HHVM
Nginx
MySQL
PostgreSQL
Redis
Memcached
Beanstalkd
Node.js
Composer

Benefits:

Consistent environment across team
No local software installation needed
Switch between projects easily
Production-ready stack
Works on Windows, Mac, Linux

Prerequisites

Install these on your host machine:

# 1. VirtualBox
https://www.virtualbox.org/wiki/Downloads

# 2. Vagrant
https://www.vagrantup.com/downloads.html

# Verify installation
vagrant --version

Installing Homestead

Method 1: Per-Project Installation (Recommended)

Add Homestead to your Laravel project:

composer require laravel/homestead --dev

Generate Homestead configuration:

# Mac / Linux
php vendor/bin/homestead make

# Windows
vendor\\bin\\homestead make

This creates Homestead.yaml in your project root.

Method 2: Global Installation

# Clone Homestead repository
git clone https://github.com/laravel/homestead.git ~/Homestead
cd ~/Homestead

# Checkout latest stable release
git checkout v2.2.1

# Initialize Homestead
bash init.sh

This creates ~/.homestead/Homestead.yaml

Configuration

Homestead.yaml

---
ip: "192.168.10.10"
memory: 2048
cpus: 1
provider: virtualbox

authorize: ~/.ssh/id_rsa.pub

keys:
    - ~/.ssh/id_rsa

folders:
    - map: ~/Code
      to: /home/vagrant/Code

sites:
    - map: homestead.app
      to: /home/vagrant/Code/Laravel/public

databases:
    - homestead

variables:
    - key: APP_ENV
      value: local

Configuration options:

ip: IP address of VM
memory: RAM allocated to VM
cpus: Number of CPUs
folders: Shared folders between host and VM
sites: Nginx site configurations
databases: Databases to create
variables: Environment variables

Adding Multiple Sites

sites:
    - map: project1.app
      to: /home/vagrant/Code/project1/public

    - map: project2.app
      to: /home/vagrant/Code/project2/public

    - map: api.app
      to: /home/vagrant/Code/api/public

databases:
    - project1
    - project2
    - api

Hosts File

Add sites to your hosts file:

# Mac/Linux
sudo nano /etc/hosts

# Windows
C:\Windows\System32\drivers\etc\hosts

Add:

192.168.10.10  homestead.app
192.168.10.10  project1.app
192.168.10.10  project2.app
192.168.10.10  api.app

Launching Homestead

# Start VM
vagrant up

# SSH into VM
vagrant ssh

# Stop VM
vagrant halt

# Restart VM
vagrant reload

# Destroy VM
vagrant destroy

Working with Homestead

Accessing Your Site

After vagrant up, visit:

http://homestead.app
http://project1.app

SSH Access

vagrant ssh

# You're now in the VM
cd ~/Code/Laravel
php artisan migrate

Running Commands

From host machine:

vagrant ssh -c "cd /home/vagrant/Code/Laravel && php artisan migrate"

Inside VM:

vagrant ssh

# Navigate to project
cd ~/Code/Laravel

# Run artisan commands
php artisan migrate
php artisan db:seed
php artisan queue:work

# Run Composer
composer install
composer update

# Run npm
npm install
gulp

Database Configuration

MySQL

From host:

Host: 127.0.0.1
Port: 33060
Username: homestead
Password: secret

From VM:

Host: localhost
Port: 3306
Username: homestead
Password: secret

Laravel .env:

DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret

Connect with Sequel Pro / MySQL Workbench:

Host: 127.0.0.1
Port: 33060
Username: homestead
Password: secret

PostgreSQL

DB_CONNECTION=pgsql
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret

External connection:

Host: 127.0.0.1
Port: 54320

Port Forwarding

Default ports:

| Service | Host Port | VM Port | |---------|-----------|---------| | HTTP | 8000 | 80 | | MySQL | 33060 | 3306 | | PostgreSQL | 54320 | 5432 | | Mailhog | 8025 | 8025 |

Custom ports:

ports:
    - send: 8080
      to: 80
    - send: 3307
      to: 3306

Site Types

Laravel Application

sites:
    - map: laravel.app
      to: /home/vagrant/Code/laravel/public

Symfony Application

sites:
    - map: symfony.app
      to: /home/vagrant/Code/symfony/web
      type: symfony2

Static Site

sites:
    - map: static.app
      to: /home/vagrant/Code/static
      type: apache

Environment Variables

sites:
    - map: myapp.app
      to: /home/vagrant/Code/myapp/public
      variables:
          - key: APP_ENV
            value: local
          - key: APP_DEBUG
            value: true

Queue Workers

Start queue workers in VM:

vagrant ssh

# Start worker
php artisan queue:work --daemon

# With Supervisor (recommended)
sudo supervisorctl start laravel-worker:*

Supervisor configuration:

# In VM
sudo nano /etc/supervisor/conf.d/laravel-worker.conf

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /home/vagrant/Code/Laravel/artisan queue:work --sleep=3 --tries=3
autostart=true
autorestart=true
user=vagrant
numprocs=2
redirect_stderr=true
stdout_logfile=/home/vagrant/Code/Laravel/storage/logs/worker.log

Reload Supervisor:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-worker:*

Cron Scheduling

Laravel's scheduler requires a cron entry:

# In VM
crontab -e

# Add this line
* * * * * php /home/vagrant/Code/Laravel/artisan schedule:run >> /dev/null 2>&1

Mailhog

View sent emails in development:

APP_MAIL_HOST=localhost
APP_MAIL_PORT=1025

Access Mailhog: http://homestead.app:8025

Blackfire Profiler

Profile PHP application performance:

blackfire:
    - id: your-server-id
      token: your-server-token
      client-id: your-client-id
      client-token: your-client-token

Updating Homestead

# Update Vagrant box
vagrant box update

# Update Homestead code (global installation)
cd ~/Homestead
git pull origin master

Troubleshooting

VM Won't Boot

# Check VirtualBox
vboxmanage list vms

# Restart VirtualBox service (Mac)
sudo /Library/Application\ Support/VirtualBox/LaunchDaemons/VirtualBoxStartup.sh restart

# Destroy and recreate
vagrant destroy
vagrant up

Sites Not Accessible

# Check Nginx configuration in VM
vagrant ssh
sudo nginx -t
sudo service nginx restart

# Verify hosts file
cat /etc/hosts

Permission Issues

# In Homestead.yaml
folders:
    - map: ~/Code
      to: /home/vagrant/Code
      type: "nfs"  # Better performance on Mac

Slow Performance (Windows)

Use NFS or SMB:

folders:
    - map: ~/Code
      to: /home/vagrant/Code
      type: "smb"

Best Practices

Use per-project Homestead - Easier version control
Commit Homestead.yaml - Share configuration with team
Don't commit .vagrant/ - Add to .gitignore
Keep Homestead updated - New features and security patches
Use SSH keys - Don't use passwords
Customize VM resources - Adjust memory/CPU as needed
Backup databases - Export before destroying VM

Alternative: Valet (Mac Only)

For simpler Mac-only setup:

composer global require laravel/valet
valet install

# In project directory
valet link myapp

# Access at: http://myapp.dev

Homestead vs Docker

| Feature | Homestead | Docker | |---------|-----------|--------| | Learning curve | Easy | Moderate | | Setup time | Medium | Fast | | Resource usage | Heavy | Light | | Cross-platform | Yes | Yes | | Production use | No | Yes | | Multiple versions | No | Yes |

Daily Workflow

# Morning
vagrant up
vagrant ssh
cd ~/Code/Laravel

# Development
php artisan migrate
php artisan db:seed
gulp watch

# Evening
exit  # Leave VM
vagrant halt

Team Setup

1. Share configuration:

Commit these files:

Homestead.yaml
after.sh (custom provisioning)
.env.example

2. Team member setup:

git clone repo
composer install
cp .env.example .env
vagrant up
vagrant ssh
php artisan key:generate
php artisan migrate

Conclusion

Homestead eliminates environment inconsistencies and setup headaches. At ZIRA Software, new developers are productive within 30 minutes of cloning a repository. The time saved on environment issues alone justifies using Homestead.

Whether you're a solo developer or part of a team, Homestead provides a solid, consistent foundation for Laravel development.

Need help setting up development environments for your team? Contact ZIRA Software to discuss Homestead, Docker, or custom development environment solutions.

What is Homestead?

Homestead is a pre-built Vagrant box (virtual machine) that includes:

Ubuntu 14.04
PHP 5.6
HHVM
Nginx
MySQL
PostgreSQL
Redis
Memcached
Beanstalkd
Node.js
Composer

Benefits:

Consistent environment across team
No local software installation needed
Switch between projects easily
Production-ready stack
Works on Windows, Mac, Linux

Prerequisites

Install these on your host machine:

# 1. VirtualBox
https://www.virtualbox.org/wiki/Downloads

# 2. Vagrant
https://www.vagrantup.com/downloads.html

# Verify installation
vagrant --version

Installing Homestead

Method 1: Per-Project Installation (Recommended)

Add Homestead to your Laravel project:

composer require laravel/homestead --dev

Generate Homestead configuration:

# Mac / Linux
php vendor/bin/homestead make

# Windows
vendor\\bin\\homestead make

This creates Homestead.yaml in your project root.

Method 2: Global Installation

# Clone Homestead repository
git clone https://github.com/laravel/homestead.git ~/Homestead
cd ~/Homestead

# Checkout latest stable release
git checkout v2.2.1

# Initialize Homestead
bash init.sh

This creates ~/.homestead/Homestead.yaml

Configuration

Homestead.yaml

---
ip: "192.168.10.10"
memory: 2048
cpus: 1
provider: virtualbox

authorize: ~/.ssh/id_rsa.pub

keys:
    - ~/.ssh/id_rsa

folders:
    - map: ~/Code
      to: /home/vagrant/Code

sites:
    - map: homestead.app
      to: /home/vagrant/Code/Laravel/public

databases:
    - homestead

variables:
    - key: APP_ENV
      value: local

Configuration options:

ip: IP address of VM
memory: RAM allocated to VM
cpus: Number of CPUs
folders: Shared folders between host and VM
sites: Nginx site configurations
databases: Databases to create
variables: Environment variables

Adding Multiple Sites

sites:
    - map: project1.app
      to: /home/vagrant/Code/project1/public

    - map: project2.app
      to: /home/vagrant/Code/project2/public

    - map: api.app
      to: /home/vagrant/Code/api/public

databases:
    - project1
    - project2
    - api

Hosts File

Add sites to your hosts file:

# Mac/Linux
sudo nano /etc/hosts

# Windows
C:\Windows\System32\drivers\etc\hosts

Add:

192.168.10.10  homestead.app
192.168.10.10  project1.app
192.168.10.10  project2.app
192.168.10.10  api.app

Launching Homestead

# Start VM
vagrant up

# SSH into VM
vagrant ssh

# Stop VM
vagrant halt

# Restart VM
vagrant reload

# Destroy VM
vagrant destroy

Working with Homestead

Accessing Your Site

After vagrant up, visit:

http://homestead.app
http://project1.app

SSH Access

vagrant ssh

# You're now in the VM
cd ~/Code/Laravel
php artisan migrate

Running Commands

From host machine:

vagrant ssh -c "cd /home/vagrant/Code/Laravel && php artisan migrate"

Inside VM:

vagrant ssh

# Navigate to project
cd ~/Code/Laravel

# Run artisan commands
php artisan migrate
php artisan db:seed
php artisan queue:work

# Run Composer
composer install
composer update

# Run npm
npm install
gulp

Database Configuration

MySQL

From host:

Host: 127.0.0.1
Port: 33060
Username: homestead
Password: secret

From VM:

Host: localhost
Port: 3306
Username: homestead
Password: secret

Laravel .env:

DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret

Connect with Sequel Pro / MySQL Workbench:

Host: 127.0.0.1
Port: 33060
Username: homestead
Password: secret

PostgreSQL

DB_CONNECTION=pgsql
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret

External connection:

Host: 127.0.0.1
Port: 54320

Port Forwarding

Default ports:

| Service | Host Port | VM Port | |---------|-----------|---------| | HTTP | 8000 | 80 | | MySQL | 33060 | 3306 | | PostgreSQL | 54320 | 5432 | | Mailhog | 8025 | 8025 |

Custom ports:

ports:
    - send: 8080
      to: 80
    - send: 3307
      to: 3306

Site Types

Laravel Application

sites:
    - map: laravel.app
      to: /home/vagrant/Code/laravel/public

Symfony Application

sites:
    - map: symfony.app
      to: /home/vagrant/Code/symfony/web
      type: symfony2

Static Site

sites:
    - map: static.app
      to: /home/vagrant/Code/static
      type: apache

Environment Variables

sites:
    - map: myapp.app
      to: /home/vagrant/Code/myapp/public
      variables:
          - key: APP_ENV
            value: local
          - key: APP_DEBUG
            value: true

Queue Workers

Start queue workers in VM:

vagrant ssh

# Start worker
php artisan queue:work --daemon

# With Supervisor (recommended)
sudo supervisorctl start laravel-worker:*

Supervisor configuration:

# In VM
sudo nano /etc/supervisor/conf.d/laravel-worker.conf

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /home/vagrant/Code/Laravel/artisan queue:work --sleep=3 --tries=3
autostart=true
autorestart=true
user=vagrant
numprocs=2
redirect_stderr=true
stdout_logfile=/home/vagrant/Code/Laravel/storage/logs/worker.log

Reload Supervisor:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-worker:*

Cron Scheduling

Laravel's scheduler requires a cron entry:

# In VM
crontab -e

# Add this line
* * * * * php /home/vagrant/Code/Laravel/artisan schedule:run >> /dev/null 2>&1

Mailhog

View sent emails in development:

APP_MAIL_HOST=localhost
APP_MAIL_PORT=1025

Access Mailhog: http://homestead.app:8025

Blackfire Profiler

Profile PHP application performance:

blackfire:
    - id: your-server-id
      token: your-server-token
      client-id: your-client-id
      client-token: your-client-token

Updating Homestead

# Update Vagrant box
vagrant box update

# Update Homestead code (global installation)
cd ~/Homestead
git pull origin master

Troubleshooting

VM Won't Boot

# Check VirtualBox
vboxmanage list vms

# Restart VirtualBox service (Mac)
sudo /Library/Application\ Support/VirtualBox/LaunchDaemons/VirtualBoxStartup.sh restart

# Destroy and recreate
vagrant destroy
vagrant up

Sites Not Accessible

# Check Nginx configuration in VM
vagrant ssh
sudo nginx -t
sudo service nginx restart

# Verify hosts file
cat /etc/hosts

Permission Issues

# In Homestead.yaml
folders:
    - map: ~/Code
      to: /home/vagrant/Code
      type: "nfs"  # Better performance on Mac

Slow Performance (Windows)

Use NFS or SMB:

folders:
    - map: ~/Code
      to: /home/vagrant/Code
      type: "smb"

Best Practices

Use per-project Homestead - Easier version control
Commit Homestead.yaml - Share configuration with team
Don't commit .vagrant/ - Add to .gitignore
Keep Homestead updated - New features and security patches
Use SSH keys - Don't use passwords
Customize VM resources - Adjust memory/CPU as needed
Backup databases - Export before destroying VM

Alternative: Valet (Mac Only)

For simpler Mac-only setup:

composer global require laravel/valet
valet install

# In project directory
valet link myapp

# Access at: http://myapp.dev

Homestead vs Docker

Daily Workflow

# Morning
vagrant up
vagrant ssh
cd ~/Code/Laravel

# Development
php artisan migrate
php artisan db:seed
gulp watch

# Evening
exit  # Leave VM
vagrant halt

Team Setup

1. Share configuration:

Commit these files:

Homestead.yaml
after.sh (custom provisioning)
.env.example

2. Team member setup:

git clone repo
composer install
cp .env.example .env
vagrant up
vagrant ssh
php artisan key:generate
php artisan migrate

Conclusion

Whether you're a solo developer or part of a team, Homestead provides a solid, consistent foundation for Laravel development.

Need help setting up development environments for your team? Contact ZIRA Software to discuss Homestead, Docker, or custom development environment solutions.

Table of Contents

What is Homestead?

Prerequisites

Installing Homestead

Method 1: Per-Project Installation (Recommended)

Method 2: Global Installation

Configuration

Homestead.yaml

Adding Multiple Sites

Hosts File

Launching Homestead

Working with Homestead

Accessing Your Site

SSH Access

Running Commands

Database Configuration

MySQL

PostgreSQL

Port Forwarding

Site Types

Laravel Application

Symfony Application

Static Site

Environment Variables

Queue Workers

Cron Scheduling

Mailhog

Blackfire Profiler

Updating Homestead

Troubleshooting

VM Won't Boot

Sites Not Accessible

Permission Issues

Slow Performance (Windows)

Best Practices

Alternative: Valet (Mac Only)

Homestead vs Docker

Daily Workflow

Team Setup

Conclusion

You Might Also Like

Mobile Backend & APIs

RESTful API Development

Custom CMS Development

Clinical Trial Software in Houston

Key Takeaways

Understand the Basics

Practice Regularly

Customize Your Setup

Learn from Community

Written by ZIRA Software Team

Related Articles

Laravel Sail Development Guide

Laravel 12 Preview Features

Laravel vs Django 2025 Guide

Never Miss an Update

Want to read moreinsights like this?

Laravel Homestead Setup Guide

Table of Contents

What is Homestead?

Prerequisites

Installing Homestead

Method 1: Per-Project Installation (Recommended)

Method 2: Global Installation

Configuration

Homestead.yaml

Adding Multiple Sites

Hosts File

Launching Homestead

Working with Homestead

Accessing Your Site

SSH Access

Running Commands

Database Configuration

MySQL

PostgreSQL

Port Forwarding

Site Types

Laravel Application

Want to read more
insights like this?

Want to read more
insights like this?