Hello fellow developers who have not yet migrated their Vagrant/Homestead local development environment from VirtualBox to Parallels! Welcome in. This step-by-step tutorial is for you.
Why upgrade?
This is not an origination article - it’s not about installing from Parallels newly, so any of the following circumstances is likely to apply:
- You need to move over to new technology - M1 Macs, Mac OS Mavericks, and need your Virtual Machine to work on the other side of that process. Since VirtualBox is not going to work on newer macs and does not work on Mavericks or newer system software, it’s only a matter of time before an upgrade becomes necessary.
- You may need access to later versions of PHP (PHP 8.1 for us as of today, June 1, 2022) or any number of new additional configuration options that make your life easier or help you more closely conform to your production tech stack.
- So that you can take a good look at your homestead.yaml file and maintain it. You can delete old projects, review current ones, and perform software updates from as far back as PHP 5.6 in incremental, controlled processes.
- So that you can kick the Docker can down the road again.
If you are:
- Anyone with a working, even if slightly-behind vagrant/homestead local web development environment.
- Shopping around for a reliable local development virtual machine that isn’t subject to abandonment by developers
- Interested in CMS development on PHP platforms or adjacent topics
- Wondering what to do with your existing Parallels professional account
..you’re likely to find some value here. Please read through once to get a sense of task length (especially configuration tasks, that are linked off-site) if you’ve never upgraded a working vagrant/homestead install.
You will need:
- A working vagrant/homestead virtual machine for a local development environment on VirtualBox run by Vagrant. Fix any errors or broken VMS before continuing.
- Backups of all your databases. Production copies of Craft CMS or ExpressionEngine databases need no editing, but some values in WordPress production copies need to be adjusted to work locally. You likely know the ins and outs of your specific platform - if grabbing a production copy is too much work, back up your local databases before continuing.
- A Parallels Professional account on your Mac. Did I say Mac? Yes! This tutorial is specific to Mac.
- Your local computer freshly restarted, with your current VirtualBox vagrant/homestead suspended.
Part 1 - Delete and Replace
Create a homestead_copy.yaml - a copy of your current homestead.yaml that will remain safe while the namespaced file may experience some changes.
Update Vagrant - if you use homebrew that's an option here on the command line- otherwise it's navigate and download. Complete instructions.
Install the vagrant parallels plugin - see step 1 only here.
Destroy your old VM - you don't need it
Hit vagrant destroy
This will destroy your virtual machine, but not your website code or your database backups. You will be destroying the virtual machine you have and replacing it with the updated one.
- In the terminal in the directory where Homestead is installed (probably
~/Homestead
) usevagrant destroy
to destroy your old virtual machine. - If this is too permanent and makes you nervous, make a duplicate of your current
~/Homestead
folder and rename it, then complete this step.
Re-set-up homestead.yaml
- Open up homestead.yaml
- Add a name in the top block of critical parameters, avoiding collision with records with your old VM.
- It’s easier to avoid this by renaming the VM than fully clearing up the record causing the issue. Check out these instructions to see if you’re up for it.
- If your provider doesn’t say
parallels
, change it to that. Unfortunately you need a Parallels Professional account forvagrant up
to work with this provider. - Change the third digit of your IP address to avoid this issue (non-hostonly network). You can also change the fourth digit.
- Add SSL if you don’t already have it. This makes SSL possible but won’t force it.
- After completely installing, ours looks like:
ip: "192.168.56.56"
memory: 2048
cpus: 2
provider: parallels
name: aquarian_vm_05_2022
ssl: true
authorize: ~/.ssh/id_rsa.pub
- Leave all provisioning in place on homestead.yaml. If you end up erasing your homestead.yaml, grab this content from homestead_copy.yaml (you did save that, right?) and paste it into this file below the
authorize
line. This includes your folders, sites, and databases, as well as features and services if you have them. If you’re new to services and features, you may want to review the cool new stuff available in these areas. - Navigate into /etc/hosts (we use
sudo vim /etc/hosts
in the terminal) and replace your old local IP address on each domain with the one contained at the top of homestead.yaml, if it has changed. Here’s a refresher on vim if you need it.
Part 2 - Configure
Now it’s time to vagrant up
This step will create your virtual machine. It will add any sites and databases specified in the homestead.yaml file and use the provider specified. If you have skipped any steps above, you won't make it past this point.
- If your VM is already running from the install process you need to
vagrant suspend
and thenvagrant up
SSH in
Once the virtual machine is up and running, enter vagrant ssh
in the terminal from the ~/Homestead
directory, or from the custom directory where Homestead resides.
- Tip: Use the
exit
command to get out.
While SSH'd in as the vagrant user in your new vagrant/homestead local development virtual machine, you may want to complete any or all of the following objectives:
MySQL - Turn off only_full_group_by - use these instructions.
- Do you need to take this step? Only if your app or CMS tells you to.
- There are two approaches to solving this, and we're sharing the one that worked for us. We tried both approaches to this and had the best luck with removing only_full_group_by from the sql_mode variable, stored in mysql.
Enable SSL on MySQL - use these instructions.
- Do you need to take this step? MySQL wouldn’t work for us without it.
- Skip the part about creating a user with SSL Privilege - vagrant/homestead takes care of this.
Recommended: Enable SSH
- Do you need to take this step? Yes! It’s quick and easy and will enable HTTPS locally. no-brainer.
- We used this per-website approach.
- We didn’t know about this one-effort approach or this one and haven’t tested either - but I would suppose this could save some time assuming it worked.
We hope this was helpful! We try to be as helpful as possible. For more information about our ExpressionEngine and Craft CMS expertise and how to work with us, check us out here at aquarianwebdesign.com Any feedback? Let us know in the comments -