January 21, 2022, update
Today I updated to Homestead version 13.0.1 and in the process, I updated both Vagrant (2.2.19) and Virtual box (6.1.32). I did some steps a bit different then before. Let me summarise below:
- Step 5: I checked out the release branch of laravel/homestead as described in the Laravel docs. I think this is better than finding a specific tag: the docs state that the release branch is always stable.
- Step 6: Running vagrant up returned an error about the Virtual Box and the IP address we are using. I always used the 192.168.10.10 IP but the new Virtual Box requires that IP in this range: 192.168.56.0/21 (meaning 192.168.56.0 up to 192.168.56.21). To overcome this error, change the IP to somewhere in this range in your Homestead.yaml file. Additionally, change the IP also in your hostfile (/etc/hosts) in order to get a correct mapping between your folders on the host computer and the Virtual Box.
- Step 7: After the destroy command, the databases were gone again. But the scp command also failed (wrong port) so I had to something else. I opened Sequel Pro and imported the whole file homestead-backup.sql in one go. This took some time as the file was rather big but in the end it worked. Please note: I first tried to do this in my current database program of choice: TablePlus, but it did not want to import all the databases in a single go.
August 17, 2020, update
Today I updated to Homestead version 11.0.2 and in the process, I updated both Vagrant (2.2.9) and Virtual box (6.1.12). I followed the steps in this post (see below) and got stuck with the libpng12 issue in step 12. After updating, I was running Ubuntu 20.04 and the fix for the libpng12 package as I describe below didn’t work anymore.
sudo add-apt-repository ppa:linuxuprising/libpng12 sudo apt update sudo apt install libpng12-0
April 8, 2020, Update
I just updated my homestead box again by following the steps below. But before you continue, read this first!
- Check your Vagrant version (vagrant -v from the terminal) and consider updating to 2.2.7 (at the time of writing). This new version comes with a new checksum type ‘sha512’. My version of Vagrant did not support this checksum type and failed comparing the checksums after the large download of the new box finished. To spare time, consider updating Vagrant.
- Once you start updating, think about Virtual Box also.
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.
- Backup databases: ssh into the vagrant machine and run this command:
mysqldump -u homestead -psecret --all-databases > homestead-backup.sql
- 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 email@example.com:/home/vagrant/homestead-backup.sql .
- 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)
- From the same directory:
- Again in this directory (assuming you have cloned the homestead repo when you installed this the first time), fetch the repo. This shows you the latest changes. Now checkout the latest tagged release using
git checkout [tagname].
- Start vagrant:
- ssh into the vagrant machine. If your backup file is still there, run:
mysql -u homestead -psecret < homestead-backup.sql
If the file is not there, scp it from your machine using:
scp -P -2222 homestead-backup.sql firstname.lastname@example.org:/home/vagrant
- 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).
- Remove box 7.0.0:
vagrant box remove laravel/homestead --box-version=7.0.0
- 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.
- Add git user info and aliases (if you had them before). Somehow they got lost as well in the update.
- 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 127.0.0.1 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:
2) run the following 3 commands to install libpng package
wget -q -O /tmp/libpng12.deb http://mirrors.kernel.org/ubuntu/pool/main/libp/libpng/libpng12-0_1.2.54-1ubuntu1_amd64.deb
dpkg -i /tmp/libpng12.deb
3) exit superuser modus:
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!