How to update your Laravel Homestead Box

Consider the following situation.

In the morning you turn on your computer, login and spin up your vagrant virtual box. A message in your terminal reads ‘there is an update for the laravel/homestead box. Run vagrant box update to update your box’.

If you are like me and happy that everything is working great without the update, you probably leave this for a couple of days.

Today however, I had some time to take care of this update, and I wrote down the various steps for future reference. Below are the steps to update the vagrant box. Additional  explanation on some of the points can be found at the bottom of this post. Most of the items in this list come either from the official documentation or this post.

  1. Backup databases: ssh into the vagrant machine and run this command: mysqldump -u homestead -psecret --all-databases > homestead-backup.sql
  2. Log out of the vagrant machine. I copied the backup to my machine (just to be sure it is not gone after the destroy in step 4): scp -P 2222 vagrant@ .
  3. From the directory where Homestead is installed, run the update command: vagrant box update (this may take a while, because a large file download takes place)
  4. From the same directory: vagrant destroy
  5. Again in this directory (assuming you have cloned the homestead repo when you installed this the first time), fetch the repo, checkout the master branch, pull it and check if this is also a stable (tagged) version. Otherwise, checkout the latest tagged release.
  6. Start vagrant: vagrant up
  7. ssh into the vagrant machine. If your backup file is still there, run: mysql -u homestead -psecret < homestead-backup.sql
    1. if the file is not there, scp it from your machine using: scp -2222 homestead-backup.sql vagrant@
  8. Log out of the vagrant machine again and list the installed boxes: vagrant box list (I had two boxes installed, 7.0.0 and 7.1.0. The former may be removed).
  9. Remove box 7.0.0: vagrant box remove laravel/homestead --box-version=7.0.0
  10. If you modified the vagrant host file before the update, fix the hostfile on the vagrant machine. Ssh into the machine and open up file /etc/hosts. I had to add the IPs and urls for the applications I use as an API. The IP address and the urls can be found in the Homestead.yaml file.
  11. Add git user info and aliases (if you had them before). Somehow they got lost as well in the update.
  12. The problem with libpng also returned 😡. This happend when compiling my Vue based JS code with webpack.

Notes on this recipe

Backups (step 1)
As always when updating something, you should be either very certain nothing goes wrong, or make some backups.

In the past I learned that making a backup of my homestead databases was very important, since they are deleted when we run the vagrant destroy command. However, today I found out how to make this backup with a single command!

Scp (step 2)
The secure copy command has an extra argument -P which is short for the port. Without the port, copying does not work. You can list the available ports with command: vagrant port. Typically, port 22/ 2222 is associated with ssh. You can read more on ports here.

known_hosts (Step 2)
When copying the database backup file from the vagrant machine to my computer, the client checks that the server is known (in the file .ssh/known_hosts) or a message pops up for you to acknowledge this server. When clicking yes, the server key is added to this known_hosts file.

After destroying the vagrant box and up-ing it again, we did another copy (from my machine to the vagrant box). Since the machine is rebooted, its keys were changed and the one stored in my known_hosts file was no longer valid. I just opened the known_hosts file and removed the line for the vagrant server (the one with the IP). Thereafter I was able to do the copy (again I had to acknowledge the server and the new key was added to known_hosts once more).

fetching homestead’s repo (Step 5)
During the initial install of the laravel homestead box, I cloned the homestead repository, followed by a checkout of a specific tag (8.0.0). So I was in detached HEAD mode. Nothing to be afraid of by the way…

Today I started with a fetch on the repository (git fetch), and I confirmed that there were updates. Then I switched to the master branch (git checkout master) and pulled it (git pull origin master). After this, I wondered if the current master was a stable release. Using git log I confirmed that this was the case. If not, it is advised to checkout the latest tagged commit as this will be the stable one (git checkout <tagname>).

vagrant destroy and your backup file (Step 4-5)
After creating the database backup (in the root of the vagrant machine /home/vagrant) on the vagrant machine (before destroying it), I thought to be smart and moved it (with sudo mv) to the directory where my code is mapped (/home/vagrant/Code). However, after destroying and up-ing the machine again, the file was lost.

I am not sure whether it would have stayed at /home/vagrant if I had not moved it. But anyways, with the secure copy commands I supplied, you are better safe than sorry!

libjpg issue (Step 12)
This problem appears when we compile our JS source code using Webpack. Somehow, my mac does not have specific libraries installed to deal with jpg/png images. The following steps solved the problem for me

1) act as superuser: sudo su

2) run the command below to install libpng package

wget -q -O /tmp/libpng12.deb \ && dpkg -i /tmp/libpng12.deb \ && rm /tmp/libpng12.deb

3) exit superuser modus: exit

4) compile your code again npm run dev


With these steps as a reference I hope that the next time the update message for the laravel/homestead box appears, we will no longer be afraid. If you come up with additional steps for specific situations, let me know in the comments!

Mijn Twitter profiel Mijn Facebook profiel
Pim Hooghiemstra Webdeveloper and founder of PLint-sites. Loves to build complex webapplications using Vue and Laravel! Latest post
How to update your Laravel Homestead Box

Leave a Reply

Your email address will not be published. Required fields are marked *