Set up your development environment

With Vagrant installed, you are ready to create your first development environment.

In this tutorial, you will create a Vagrantfile, set up your first Vagrant environment, and explore the Vagrant lifecycle.

Prerequisites

To follow this tutorial, you need:

• the Vagrant CLI installed locally on your machine
• VirtualBox 7.1.4 installed as your virtualization provider

If you are using MacOS with Apple Silicon, you also may need to unset the following Virtualbox global setting. This may cause issues with spinning up a virtual machine on Apple Silicon.

$ VBoxManage setextradata global "VBoxInternal/Devices/pcbios/0/Config/DebugLevel"

Create a directory for your Vagrant project.

$ mkdir learn-vagrant-get-started

Change into the directory.

$ cd learn-vagrant-get-started

Initialize a new Vagrant environment

Vagrant has a built-in command for initializing a project, vagrant init, which can take a box name and URL as arguments. Initialize the directory and specify the hashicorp-education/ubuntu-24-04 box.

$ vagrant init hashicorp-education/ubuntu-24-04 --box-version 0.1.0
A `Vagrantfile` has been placed in this directory. You are now
ready to `vagrant up` your first virtual environment! Please read
the comments in the Vagrantfile as well as documentation on
`vagrantup.com` for more information on using Vagrant.

This command fetches the specified box from the HCP Vagrant Registry and generates a Vagrantfile in your directory. The Vagrantfile describes the kind of machine and resources you need to run your project, as well as what software to install and how you want to access it. It also marks the root directory of your project. Many of the configuration options in Vagrant are relative to this root directory.

You should commit your Vagrantfile to version control, this will allow every person on the project to benefit from Vagrant without any upfront configuration work.

The generated Vagrantfile contains the following configuration.

Vagrant.configure("2") do |config|
  config.vm.box = "hashicorp-education/ubuntu-24-04"
  config.vm.box_version = "0.1.0"
end

Vagrant boxes

Instead of building a virtual machine from scratch, which would be a slow and tedious process, Vagrant uses a base image to quickly clone a virtual machine. These base images are known as "boxes" in Vagrant, and specifying the box to use for your Vagrant environment is always the first step after creating a new Vagrantfile. In this tutorial collection, you will customize the Vagrantfile to include provisioning scripts, networking configurations, shared folder settings, and multi-machine configuration.

When you initialize a Vagrant project, it also installs the box under a specific name so that multiple Vagrant environments can re-use it. Vagrant stores the current user's boxes globally. Each project uses a box as an initial image to clone from, and never modifies the actual base image. This means that if you have two projects both using the hashicorp-education/ubuntu-24-04 box you just added, adding files in one guest machine will have no effect on the other machine.

Vagrant box names are a combination of the username and box name with a slash. However, box names do not guarantee canonical boxes - anyone can publish boxes on the registry. HashiCorp's support team won't assist with boxes published by third parties.

For the remainder of these tutorials, you will only use the hashicorp-education/ubuntu-24-04 box you added. Once you are ready to start using Vagrant in your development workflow, you will need to know how to discover other boxes.

The best place to find more boxes is HCP Vagrant Registry. HCP Vagrant Registry has a public directory of freely available boxes that run various platforms and technologies. You can search HCP Vagrant Registry to find the box you care about.

Start the environment

Start your virtual machine with the vagrant up command:

$ vagrant up
==> default: Box 'hashicorp-education/ubuntu-24-04' could not be found. Attempting to find and install...
    default: Box Provider: virtualbox
    default: Box Version: 0.1.0
==> default: Loading metadata for box 'hashicorp-education/ubuntu-24-04'
    default: URL: https://vagrantcloud.com/api/v2/vagrant/hashicorp-education/ubuntu-24-04
==> default: Adding box 'hashicorp-education/ubuntu-24-04' (v0.1.0) for provider: virtualbox (arm64)
    default: Downloading: https://vagrantcloud.com/hashicorp-education/boxes/ubuntu-24-04/versions/0.1.0/providers/virtualbox/arm64/vagrant.box
## ...
Bringing machine 'default' up with 'virtualbox' provider...
==> default: Importing base box hashicorp-education/ubuntu-24-04'...
==> default: Machine booted and ready!

During this process, Vagrant performs the following actions:

1. Retrieves the box from the HCP Vagrant Registry if it is not already available locally.
2. Configures the virtual machine provider (for example, VirtualBox, VMware, etc.) based on the Vagrantfile.
3. Applies the configurations defined in the Vagrantfile to set up your virtual machine.

The hashicorp-education/ubuntu-24-04 box uses the VirtualBox provider. If Vagrant defaults to a different provider, specify the VirtualBox provider explicitly.

$ vagrant up --provider=virtualbox

Access the virtual machine

Once the environment is running, connect to the virtual machine using SSH.

$ vagrant ssh
Welcome to Ubuntu 24.04.1 LTS (GNU/Linux 6.8.0-51-generic aarch64)

The vagrant ssh command establishes a secure connection between your host machine and the virtual machine. It uses the SSH key Vagrant automatically generates during setup, eliminating the need to configure SSH credentials manually.

Inside the guest machine, verify the operating system and version to confirm your environment is set up correctly.

$ lsb_release -a
Distributor ID: Ubuntu
Description:    Ubuntu 24.04.1 LTS
Release:        24.04
Codename:       focal

Inside the virtual machine, you can install software, test applications, and develop your project. Exit the guest machine.

$ logout

Manage the environment lifecycle

You can manage your virtual machine's lifecycle to optimize resources and streamline workflows. Use the following commands on your host machine.

Suspend the machine to temporarily pause your work. This saves the current memory state and stops the machine without shutting it down completely.

$ vagrant suspend
==> default: Saving VM state and suspending execution...

When you are ready to resume, use vagrant resume to restore the environment to its previous state.

$ vagrant resume
==> default: Resuming suspended VM...
==> default: Booting VM...
==> default: Waiting for machine to boot. This may take a few minutes...
    default: SSH address: 127.0.0.1:2200
    default: SSH username: vagrant
    default: SSH auth method: password
==> default: Machine booted and ready!
==> default: Machine already provisioned. Run `vagrant provision` or use the `--provision`
==> default: flag to force provisioning. Provisioners marked to run always will still run.

Halt the environment to shut down the machine gracefully. The next time you start your environment with vagrant up, Vagrant will start the machine in a clean, powered-off state. This is useful for conserving resources when you are not actively using the environment.

$ vagrant halt
==> default: Attempting graceful shutdown of VM...

Destroy the machine to delete the virtual machine entirely, along with its data. Use this command cautiously when you no longer need the environment. Confirm the destroy by entering y when prompted.

$ vagrant destroy
    default: Are you sure you want to destroy the 'default' VM? [y/N] y
==> default: Destroying VM and associated drives...

Note that destroying the machine does not remove the downloaded box file. This is because multiple projects can reference the same box. You can remove the box file with the remove subcommand, providing the name of your box.

$ vagrant box remove hashicorp-education/ubuntu-24-04
Removing box 'hashicorp-education/ubuntu-24-04' (v0.1.0) with provider 'virtualbox'...

Next steps

You have created your first Vagrant environment, explored the Vagrantfile and learned how to manage the virtual machine lifecycle. Continue to the next tutorial to learn how to provision your environment to automatically install software and configure your machine.

For more information on topics covered in this tutorial, refer to the following documentation:

• Vagrantfile
• Vagrant box
• Vagrant provider