First make sure you have all the necessary software installed for VVV to run:

Vagrant Git

You will also need to install/use one of these vagrant providers:

• Windows
• MacOS (Intel)
• MacOS (Arm/M1)
• Linux
• Docker (v3.13+)

• VirtualBox Hyper-V Docker (see docker tab)

  Windows users with Docker installed or Hyper-V turned on should avoid VirtualBox. VirtualBox can be unreliable when Hyper-V is turned on.

• VirtualBox Parallels Business/Pro* Docker (see docker tab)

  For Parallels you will also need to install the vagrant-parallels plugin.

• Parallels Business/Pro* Docker (see docker tab) ❕ VirtualBox

  For Parallels you will also need to install the vagrant-parallels plugin. For docker see the docker tab.

  Why Can’t I Use VirtualBox on Apple Silicon?

  While there is a technical preview it does not work with vagrant, and cannot run modern operating systems. Please check back in 5 years ( eta 2028/2032, total guess ).

• VirtualBox Docker (see docker tab)

• We have experimental docker support on the develop branch/v3.13+. You will need docker desktop if your platform doesn’t have docker already installed:

  Docker Desktop

  Note that Docker support is work in progress, and there is still a lot of work to do, but it does provide options for those on Arm devices and can be useful.

  To use the docker provider, pass --provider="docker" when provisioning VVV, and set docker as the provider in config/config.yml. Note that there is no migration path from non-docker to docker, so if you plan to switch you will need to export your database, destroy the VM, then recreate it with the docker provider.

  Important Notes For Docker Users

  There are some caveats to using docker with VVV:

  • You may see additional warnings in the provisioner output, such as not being able to synchronise clocks. While we’d like help resolving these, they should only concern you if VVV does not work after provisioning completes.
  • You cannot use VVV at the same time as competing docker based local dev servers due to how port mapping works.
    • This is a docker limitation not a VVV limitation and affects other docker dev environments too.
    • If this happens, halt the other dev environment then start VVV. Importantly make sure to stop the proxy container that has the ports mapped, some dev environments shutdown the other containers but keep the Traefik based proxy alive with the ports mapped.
  • VVV is currently a monolithic container solution. While it would be great to give each site its own container this is planned for a future major version of VVV e.g. VVV 4 or 5 as it would be a major breaking change.
  • We’re actively seeking assistance in improving our docker setup, it is by no means final.

Reboot your computer after installing the above software.

Installing VVV

We’re going to install VVV to a vvv-local folder in your home directory. First, grab a copy of VVV using git. Open a terminal or a command prompt, and enter the following command:

• MacOS/Linux
• Windows

• In a terminal:

  git clone -b stable https://github.com/Varying-Vagrant-Vagrants/VVV.git ~/vvv-local
  cd ~/vvv-local
  vagrant plugin install --local
  

• In an elevated/admin command prompt:

  git clone -b stable https://github.com/Varying-Vagrant-Vagrants/VVV.git %systemdrive%%homepath%/vvv-local
  cd %systemdrive%%homepath%/vvv-local
  vagrant plugin install --local
  

  This should have created a vvv-local folder in your users main folder, e.g. C:\Users\myusername\ alongside the documents/pictures/videos/etc folders.

Alternatively you can download a zip file from github but we strongly recommend against this though, as it makes updating VVV much harder. If you did this, skip the first commmand.

At this point you might want to adjust the config/config.yml file before VVV creates the local developer environment. This is your opportunity to do so. You might do this in order to change the provider vagrant uses to Hyper-V instead of VirtualBox, or to provision additional sites the first time the VM is created to save time.

Starting VVV

Start VVV by opening a terminal, changing to the VVV folder, and running vagrant up. For example:

• MacOS/Linux
• Windows

• cd ~/vvv-local
  vagrant up
  

• cd %systemdrive%%homepath%/vvv-local
  vagrant up
  

The first time you run vagrant up may take longer while it installs PHP and other tools. When finished it will show a teddy bear and a VVV logo that look like this:

    default:
    default:   ✧ ▄▀▀▀▄▄▄▄▄▄▄▀▀▀▄ ✧  Thanks for  __ __ __ __
    default:    ✧█▒▒░░░░░░░░░▒▒█    using       \ V\ V\ V /
    default:  ✧   █░░█░░░░░█░░█ ✧                \_/\_/\_/
    default:   ▄▄  █░░░▀█▀░░░█  ▄▄✧
    default:  █░░█ ▀▄░░░░░░░▄▀ █░░█ Vagrant Up has finished! Visit http://vvv.test
    default: ──────────────────────────────────────────────────────────────────────

You will find a dashboard at http://vvv.test, and your websites will be in the www subfolder.

Edit this page