Vagrant

Vagrant is a command-line utility used to manage the lifecycle of virtual machines.

PhpStorm provides full integration with Vagrant allowing you to configure the Vagrant virtual environment, control the behavior of virtual machines, and execute Vagrant commands from within your project.

In the context of working with Vagrant, you will meet the following definitions:

Vagrantfile: the main configuration file that defines the Vagrant environment, stores all the configuration for the virtual boxes and tells Vagrant how to work with virtual machines.
Virtual box: a virtual sandbox that contains a preconfigured virtual machine. Vagrant works with different providers of virtual boxes, such as Oracle's VirtualBox, VMWare or AWS.
Instance: a virtual machine.

Prerequisites

Install and enable Vagrant plugin as described in Installing plugins from JetBrains Marketplace.
Install Vagrant and Oracle's VirtualBox applications.
Make sure virtualization is enabled on your computer.

Initialize the Vagrantfile

To start working with Vagrant, you need to initialize the Vagrantfile.

Do one of the following:

Open the embedded Terminal (Alt+F12) and run the following command: vagrant init
This will initialize the Vagrantfile and put it into your project root folder by default.
In the main menu, go to Tools | Vagrant | Init in Project Root and select the target root folder from the opened window.

In the Project tool window Alt+1, switch to the Project files view and double-click the Vagrantfile to open it in the embedded editor.

You will see that Vagrantfile already has a predefined configuration. The config.vm.box = "..." line specifies the virtual box that will be used in a project.

Specify the virtual box

As an example, we will specify the ubuntu/trusty64 box. It contains a basic Ubuntu virtual machine. You can specify any other virtual box based on your needs. To find a list of available virtual boxes, refer to Discovering Vagrant Boxes.

Do one of the following:

Open the Vagrantfile and change config.vm.box = "base" line to the following: config.vm.box = "ubuntu/trusty64".
In the Settings dialog (Ctrl+Alt+S), select Tools | Vagrant. In the Boxes window click the button and specify the following:
- Box name: ubuntu/trusty64
- Box URL: https://app.vagrantup.com/ubuntu/boxes/trusty64

Once the Vagrantfile initialization is completed, and virtual box is specified, you are ready to deploy and run the virtual machine.

Launch an instance

Do one of the following:

Open the embedded Terminal (Alt+F12) and run the following command: vagrant up.
In the main menu, go to Tools | Vagrant | Up.

SSH into a running machine

When the virtual machine is launched, it runs on a backend. To SSH into a running machine:

Open the embedded Terminal (Alt+F12) and run the following command: vagrant ssh

Vagrant commands to control an instance

To control an instance, use Vagrant commands. They can be run either from Terminal (Alt+F12) or from the main menu.

In this article, we show only the most important commands to work with the virtual machine. To find a full list of available Vagrant commands, refer to Command-Line-Interface.

Suspend: suspending an instance pauses all the processes and saves the current state of a virtual machine.
Run vagrant suspend in Terminal or select Tools | Vagrant | Suspend from the main menu.
Resume: resuming an instance brings up a previously suspended virtual machine.
Run vagrant resume in Terminal or select Tools | Vagrant | Resume from the main menu.
Reload: reloading an instance is required when you've made changes to the Vagrantfile and need Vagrant to reload the current virtual environment and its configuration.
Run vagrant reload in Terminal or select Tools | Vagrant | Reload from the main menu.
Shut down: shutting down an instance stops the running virtual machine.
Run vagrant halt in Terminal or select Tools | Vagrant | Halt from the main menu.
Destroy: destroying a virtual machine is important when you need to remove everything related to the previously created environment. All the resources provisioned during the creation of an instance are removed.
Run vagrant destroy in Terminal or select Tools | Vagrant | Destroy from the main menu.

Last modified: 21 August 2024