October 23, 2023 Full new post

Today I updated Homestead again. Since writing this post, it has had many updates and it was difficult to read. Therefore, I describe all steps I took today below and that’s all you need. I keep the original post with updates below this one for reference.

1. I checked the versions of Vagrant and VirtualBox to see if I needed to update them. I decided to update Vagrant from 2.3.4 to 2.4.0 and I left VirtualBox on 7.0.8 (latest version is 7.0.12). Updating Vagrant was done by the brew command found on Vagrant’s website: brew install hashicorp/tap/hashicorp-vagrant
2. I created a backup of my databases using command mysql -u homestead -psecret homestead-backup.sql and copied it over to my host machine.
3. I ran vagrant box update but it did not update anything to my surprise. Instead, it told me that vagrant 12.0.0 was already installed.
4. logout of vagrant and shut it down using the vagrant halt command.
5. Run vagrant destroy command
6. Run vagrant up command. No, something happened: the new laravel box was being installed. This took quite some time (± 15 minutes), because the box had to be downloaded from the Vagrant cloud.
7. In the process, I got an error (see figure 1 below). It was fixed by following the guidelines in the error. message. I had to remove the directory /homestead in my /VirtualBox VMs directory. Then I ran the command again and it worked. The /homestead directory was recreated, meaning that the move command did work. Again, this command took quite some time, mostly to install something called chromium snap. But in the end, everything was installed properly.
8. I imported my databases again, using my old database program Sequel Pro: 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.
9. I ssh-ed into the vagrant machine and I saw that Homestead was updated to v14.2.0 and Settler to 13.0.0. Together they make up the Homestead Box. It is the Settler version that is being shown in the update note by Vagrant.
10. I fixed my git config file (user and aliases)
11. I added my database routines (the backup command did not properly back them up).
12. I encountered the libpng12 issue (again). To solve it, run the three commands below

sudo add-apt-repository ppa:linuxuprising/libpng12
sudo apt update
sudo apt install libpng12-0

---

Older post with updates up to 2022

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.

Googling around I finally found the problem and a fix to it. It’s described in detail here. To install libpng12 I followed these three steps

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!

1. 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.
2. Once you start updating, think about Virtual Box also.

Original post

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@127.0.0.1:/home/vagrant/homestead-backup.sql .
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. This shows you the latest changes. Now checkout the latest tagged release using git checkout [tagname].
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
   If the file is not there, scp it from your machine using: scp -P -2222 homestead-backup.sql vagrant@127.0.0.1:/home/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 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: sudo su

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

rm /tmp/libpng12.deb

3) exit superuser modus: exit

4) compile your code again npm run dev

Conclusion

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!