Homestead Laravel Package

Getting Started

Minimal Setup

1. Install Vagrant & VirtualBox Ensure Vagrant and VirtualBox are installed. Verify via CLI:

   vagrant --version
   VBoxManage --version
   

2. Clone Homestead

   git clone https://github.com/laravel/homestead.git Homestead
   cd Homestead
   

3. Install Homestead Box Run the installer (creates Homestead.json and after.sh):

   bash init.sh
   

4. Configure Homestead.json Edit the file to define sites, folders, and services (e.g., databases, queues). Example:

   {
     "sites": [
       {
         "map": "myapp.test",
         "to": "/home/vagrant/code/myapp/public"
       }
     ],
     "folders": [
       {
         "map": "~/code/myapp",
         "to": "/home/vagrant/code/myapp"
       }
     ]
   }
   

5. Start the VM

   vagrant up
   vagrant ssh
   

6. First Use Case: Local Development

   • Sync your Laravel project to the VM via folders mapping.
   • Access the site at http://myapp.test (add to /etc/hosts if needed).
   • Run migrations, queues, or artisan commands inside the VM:

     php artisan migrate
     

Implementation Patterns

Workflow Integration

1. Project Bootstrapping

   • Use Homestead as a consistent local environment for all team members.
   • Example: Add a vagrant directory to your project repo with a custom Homestead.json:

     myproject/
     ├── vagrant/
     │   ├── Homestead.json
     │   └── after.sh
     └── ...
     

   • Run vagrant up --provision to initialize the VM with project-specific configs.

2. Environment Synchronization

   • Shared Services: Define databases, Redis, and queues in Homestead.json to match production:

     "databases": [
       { "name": "homestead", "driver": "mysql" }
     ],
     "variables": [
       { "key": "APP_ENV", "value": "local" }
     ]
     

   • Seeding: Use after.sh to run custom setup scripts:

     php artisan db:seed --class=UsersTableSeeder
     

3. CI/CD Previews

   • Spin up Homestead VMs in CI pipelines (e.g., GitHub Actions) for pre-deployment testing:

     - name: Test in Homestead
       run: |
         vagrant up --provision
         vagrant ssh -c "php artisan test"
     

4. Multi-Project Management

   • Use multiple VMs for isolated projects:

     vagrant up project1
     vagrant up project2
     

   • Define separate Homestead.json files per project and switch contexts with vagrant global-status.

5. Database Management

   • Reset Databases: Add a script to after.sh to wipe and recreate databases:

     mysql -e "DROP DATABASE homestead; CREATE DATABASE homestead;"
     php artisan migrate:fresh --seed
     

   • Backup/Restore: Use mysqldump inside the VM for local backups:

     vagrant ssh -c "mysqldump -u homestead -p homestead > backup.sql"
     

6. Queue Workers

   • Run queue workers persistently in the VM:

     vagrant ssh -c "php artisan queue:work --daemon"
     

   • Use tmux or screen to manage long-running processes.

Gotchas and Tips

Common Pitfalls

1. Hosts File Configuration

   • Issue: myapp.test fails to resolve.
   • Fix: Add 192.168.10.10 myapp.test to /etc/hosts (Linux/macOS) or C:\Windows\System32\drivers\etc\hosts (Windows).
   • Pro Tip: Use a script to auto-update hosts on VM start (add to after.sh):

     echo "192.168.10.10 $(grep 'map.*test' Homestead.json | awk '{print $2}' | sed 's/"//g')" | sudo tee -a /etc/hosts
     

2. Folder Permissions

   • Issue: "Permission denied" when writing to synced folders.
   • Fix: Ensure folders are shared in Vagrantfile:

     config.vm.synced_folder "~/code/myapp", "/home/vagrant/code/myapp", type: "rsync", rsync__args: ["--verbose", "--archive", "--delete", "-z"]
     

   • Fix: Set correct permissions inside the VM:

     sudo chown -R vagrant:vagrant /home/vagrant/code/myapp
     

3. Port Conflicts

   • Issue: Port 80/443 already in use.
   • Fix: Change ports in Homestead.json:

     "ports": [
       { "send": 8000, "to": 80 },
       { "send": 44300, "to": 443 }
     ]
     

   • Access: Use http://myapp.test:8000.

4. PHP/Composer Updates

   • Issue: Outdated PHP version in the box.
   • Fix: Update PHP via after.sh:

     sudo add-apt-repository ppa:ondrej/php
     sudo apt-get update
     sudo apt-get install php8.2
     

   • Pro Tip: Pin PHP version in Homestead.json:

     "php": "8.2"
     

5. Slow Performance

   • Issue: VM feels sluggish.
   • Fix: Allocate more CPU/RAM in Vagrantfile:

     config.vm.provider "virtualbox" do |vb|
       vb.customize ["setextradata", :id, "VBoxInternal/Devices/efi/0/Config/DmiSystemProduct", "Homestead"]
       vb.memory = "4096"
       vb.cpus = 2
     end
     

6. Database Connection Errors

   • Issue: Laravel can't connect to MySQL.
   • Fix: Verify database.php bindings:

     'mysql' => [
       'driver' => 'mysql',
       'host' => env('DB_HOST', '192.168.10.10'),
     ],
     

   • Debug: Test connection inside the VM:

     mysql -u homestead -p -h 192.168.10.10
     

Debugging Tips

1. SSH Debugging

   • Access the VM directly for logs:

     vagrant ssh -c "tail -f /var/log/nginx/error.log"
     

2. Network Issues

   • Check VM IP:

     vagrant ssh -c "ip addr show eth1"
     

   • Verify port forwarding:

     vagrant ssh -c "netstat -tulnp | grep 80"
     

3. Custom Scripts

   • Use after.sh for one-time setup:

     #!/usr/bin/env bash
     composer install --prefer-dist --no-interaction
     php artisan key:generate
     

Extension Points

1. Custom Provisioning

   • Extend after.sh to install additional tools (e.g., Node.js, Docker):

     curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
     nvm install --lts
     

2. Docker Integration

   • Run Docker inside Homestead for microservices:

     sudo apt-get install docker.io
     sudo service docker start
     docker run -d --name redis redis
     

3. Laravel Valet Alternative

   • Use Homestead for shared hosting-like environments (e.g., PHP-FPM, Nginx tuning):

     "nginx": {
       "server": {
         "root": "/home/vagrant/code/myapp/public",
         "index": "index.php",
         "server_name": "myapp.test"
       }
     }
     

4. Multi-Tenancy

   • Spin up multiple Homestead VMs for isolated tenant testing:

     vagrant up tenant1
     vagrant up