Getting Started

The Vagrant getting started tutorials will walk you through creating your first development environment with Vagrant. This quick start guide will give you a brief overview of the tutorial prerequisites and get you up and running.

Quick Start

Install Vagrant by visiting the Vagrant downloads page and downloading the appropriate installer or package for your platform. Packages are available for Mac, Windows, and distributions of Linux.

Install Vagrant

Set up your first Vagrant project by creating a project directory with a Vagrantfile at its root. Initialize the project to create this file.

Initialize a Project Directory

Vagrant uses a base image to quickly clone a virtual machine. In this tutorial specify a base image.

Install and Specify a Box

Bring up your first Vagrant environment, and SSH into the machine. Then destroy the virtual machine and remove the stored box.

Boot an Environment

Share files and folders between your local machine and the guest virtual machine to develop in your Vagrant environment while using your own text editor and other tools. 

Synchronize Local and Guest Files

Automatically provision Vagrant environments. Serve synced files using a web server provisioned on your guest machine.

Provision a Virtual Machine

At this point you have a web server running on a Virtual Machine in your Vagrant environment. In this tutorial, use Vagrant's
networking features to access the guest
machine from your host machine.

Configure the Network

Now that you have a web server running and accessible from your machine, share
and collaborate on the environment using the Vagrant Share plugin.

Share an Environment

Suspend, halt, or destroy your Vagrant development environment. 

Teardown an Environment

When you are ready to come back to your project, whether it is tomorrow,
a week from now, or a year from now, getting it up and running is easy.

Rebuild an Environment

In these tutorials your project was backed with VirtualBox. But Vagrant can work with a wide variety of backend providers, such as VMware, Hyper-V, and others.

Explore other Providers

Learn to create development environments with Vagrant

Installing

Command Line

Boxes

Networking

Synced Folders

Providers

Intro

Docs

Book

VMware

Community

Privacy

Security

Press Kit


Packer also has the ability to take the results of a builder (such as an AMI or
plain VMware image) and turn it into a [Vagrant][vagrant] box.

This is done using [post-processors][post processors].
These take an artifact created by a previous builder or post-processor and
transforms it into a new one. In the case of the Vagrant post-processor, it
takes an artifact from a builder and transforms it into a Vagrant box file.

Post-processors are a generally very useful concept. While the example on this
getting-started page will be creating Vagrant images, post-processors have many
interesting use cases. For example, you can write a post-processor to compress
artifacts, upload them, test them, etc.

Let's modify our template to use the Vagrant post-processor to turn our AWS AMI
into a Vagrant box usable with the [vagrant-aws
plugin][vagrant aws plugin].

## Enabling the Post-Processor

Post-processors are added as their own block inside of a `build` block. Modify
your `example.pkr.hcl` template and add a post-processor block at the end of
your build block. Your `build` block in your template should now look like:

```hcl
build {
  sources = ["source.amazon-ebs.parallel-AWS", "source.digitalocean.parallel-DO"]

  provisioner "shell" {
    inline = [
      "sleep 30",
      "sudo apt-get update",
      "sudo apt-get install -y redis-server"
    ]
  }

  post-processor "vagrant" {}
}

```

In this case, we're enabling a single post-processor named "vagrant". This
post-processor is built-in to Packer and will create Vagrant boxes. You can
always create [new post-processors][custom post processors], however.
The details on configuring post-processors is covered in the
[post-processors][post processors] documentation.

Validate the configuration using `packer validate`.

## Using the Post-Processor

Run a normal `packer build` and it will now use the post-processor. If
you followed along in the previous page and setup a DigitalOcean builder, we
recommend passing the `--only=amazon-ebs.example` flag to `packer build` so it
only builds the AMI. The command should look like the following:

```shell-session
$ packer build --only=amazon-ebs.example example.pkr.hcl
```

As you watch the output, you'll notice at the end in the artifact listing that a
Vagrant box was made (by default at `packer_aws.box` in the current directory).
Success!

But where did the Amazon EBS builder artifact go? When using post-processors,
Vagrant removes intermediary artifacts since they're usually not wanted. Only
the final artifact is preserved. This behavior can be changed, of course.
Changing this behavior is covered [in the
documentation][post processors].

Typically when removing intermediary artifacts, the actual underlying files or
resources of the artifact are also removed. For example, when building a VMware
image, if you turn it into a Vagrant box, the files of the VMware image will be
deleted since they were compressed into the Vagrant box. With creating AWS
images, however, the AMI is kept around, since Vagrant needs it to function.

[post processors]: https://packer.io/docs/templates/post-processors.html
[custom post processors]: https://packer.io/docs/extending/custom-post-processors.html
[vagrant]: https://www.vagrantup.com
[vagrant aws plugin]: https://github.com/mitchellh/vagrant-aws


Packer also has the ability to take the results of a builder (such as an AMI
or plain VMware image) and turn it into a Vagrant box.

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.

## Install a Box (Optional)

If you ran the commands in the last tutorial you do not need to add a box; Vagrant installed one when you initialized your project. Sometimes you may want to install a box without creating a new Vagrantfile. For  this you would use the `box add` subcommand.

You can add a box to Vagrant with `vagrant box add`. This stores the box
under a specific name so that multiple Vagrant environments can re-use it.
If you have not added a box yet, do so now. Vagrant will prompt you to select a provider. Type `2` and press `Enter` to select Virtualbox. 

```shell-session
$ vagrant box add hashicorp/bionic64
```

This will download the box named `hashicorp/bionic64` from
[HashiCorp's Vagrant Cloud box catalog](https://vagrantcloud.com/boxes/search), where you can find
and host boxes.

Boxes are globally stored for the current user. 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/bionic64`
box you just added, adding files in one guest machine will have no effect
on the other machine.

In the above command, you will notice that boxes are namespaced. Boxes are
broken down into two parts—the username and the box name—separated by a
slash. In the example above, the username is `hashicorp`, and the box is
`bionic64`. You can also specify boxes via URLs or local file paths, but that
will not be covered in the getting started guide.

!> **Warning:** Namespaces do not guarantee canonical boxes, and anyone can publish boxes on Vagrant Cloud. HashiCorp's support team does not assist
with third-party published boxes.

## Use a Box

Now you've added a box to Vagrant either by initializing or adding it explicitly, you need to configure your
project to use it as a base. Open the `Vagrantfile` and replace the
contents with the following.

```ruby
Vagrant.configure("2") do |config|
  config.vm.box = "hashicorp/bionic64"
end
```

The `hashicorp/bionic64` in this case must match the name you used to add
the box above. This is how Vagrant knows what box to use. If the box was not
added before, Vagrant will automatically download and add the box when it is
run.

You may specify an explicit version of a box by specifying `config.vm.box_version`
for example:

```ruby
Vagrant.configure("2") do |config|
  config.vm.box = "hashicorp/bionic64"
  config.vm.box_version = "1.0.282"
end
```

You may also specify the URL to a box directly using `config.vm.box_url`:

```ruby
Vagrant.configure("2") do |config|
  config.vm.box = "hashicorp/bionic64"
  config.vm.box_url = "https://vagrantcloud.com/hashicorp/bionic64"
end
```

In the next tutorial, we will bring up the Vagrant environment and interact
with it.

## Find More Boxes

For the remainder of these tutorials, you will only use the
`hashicorp/bionic64` box you added. Once you're 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 [HashiCorp's Vagrant Cloud box catalog](https://vagrantcloud.com/boxes/search).
HashiCorp's Vagrant Cloud has a public directory of freely available boxes that
run various platforms and technologies. You can search Vagrant Cloud to find the box you care about.

You can also host your own
boxes on Vagrant Cloud. Paid accounts can host private boxes to share privately within an organization.

You have successfully downloaded your first Vagrant box and configured the
Vagrantfile to use that box. Continue to the next tutorial to bringing up the machine and
access it via SSH.



The Vagrant getting started tutorials will walk you through your first
Vagrant project, highlighting major features of Vagrant.

If you are curious about the benefits Vagrant read the ["Why Vagrant?"](https://www.vagrantup.com/intro/index) introduction page.

The getting started tutorials use Vagrant with [VirtualBox](https://www.virtualbox.org),
since it is free and available on every major platform. Vagrant
can work with many other providers.

## Prerequisites

- Install the latest version of [Vagrant](https://www.vagrantup.com/docs/installation/).
- Install [VirtualBox](https://www.virtualbox.org)

## Up and Running

After you run the following two commands, you will have a fully running
virtual machine in [VirtualBox](https://www.virtualbox.org) running
[Ubuntu 18.04 LTS 64-bit](https://app.vagrantup.com/hashicorp/boxes/bionic64).

Initialize Vagrant.

```shell-session
$ vagrant init hashicorp/bionic64
```

Start the virtual machine.

```shell-session
$ vagrant up
```

SSH into this machine with `vagrant ssh`, and explore your environment. Leave the SSH session with `logout`.

When you are done exploring terminate the virtual machine, and confirm when the CLI prompts you by typing `yes`.

```shell-session
$ vagrant destroy
```

Now imagine every project you've ever worked on being this easy to
set up! With Vagrant, `vagrant up` is all you need to work on any project,
to install every dependency that project needs, and to set up any
networking or synced folders, so you can continue working from the
comfort of your own machine.

The rest of these tutorials will walk you through setting up a more
complete project.

You have just created your first virtual environment with Vagrant. Read on to
learn more about project setup.



You now have a web server running with the ability to
modify files from our host and have them automatically synced to the guest. In this tutorial, you will use Vagrant's
_networking_ features to provide access to the guest
machine from our host machine.

## Configure port forwarding

Port forwarding allows you to
specify ports on the guest machine to share via a port on the host machine.
This allows you to access a port on your own machine, but actually have
all the network traffic forwarded to a specific port on the guest machine.

Set up a forwarded port so you can access Apache in your guest, by adding it to the Vagrantfile under the line you added to run your bootstrap script. Below is the full file with port forwarding added.

```ruby
Vagrant.configure("2") do |config|
  config.vm.box = "hashicorp/bionic64"
  config.vm.provision :shell, path: "bootstrap.sh"
  config.vm.network :forwarded_port, guest: 80, host: 4567
end
```

Reload so that these changes can take effect.

```shell-session
$ vagrant reload
```

## Access the served files

Once the machine is running again, load [`http://127.0.0.1:4567`](http://127.0.0.1:4567) in
your browser, where you will find a web page that is being served from
the guest virtual machine.

## Next Steps

Vagrant also has other forms of networking, allowing you to assign
a static IP address to the guest machine, or to bridge the guest
machine onto an existing network. If you are interested in other options,
read the [networking](https://www.vagrantup.com/docs/networking/) page.

You have successfully configured networking for your virtual machine using
Vagrant. Read on to learn about setting up shares with Vagrant.



In these tutorials, your project was backed with
[VirtualBox](https://www.virtualbox.org). But Vagrant can work with
a wide variety of [backend providers](https://www.vagrantup.com/docs/providers), such as [VMware](https://www.vagrantup.com/docs/vmware/),
[Hyper-V](https://www.vagrantup.com/docs/hyperv), and more. 

## Install a new provider

Read the documentation
of each provider for more information on how to set it them up.

## Boot with the new provider

Once you have a provider installed, you do not need to make any modifications
to your Vagrantfile; just run `vagrant up` with the proper provider and
Vagrant will do the rest.

```shell-session
$ vagrant up --provider=vmware_desktop
```

Once you run `vagrant up` with another provider other Vagrant
commands will automatically use that provider. So when you are ready to SSH or destroy for example, run the commands normally (no extra
flags necessary).

For more information on providers, read the full documentation on
[providers](https://www.vagrantup.com/docs/providers/).

## Next steps

That's it! You have successfully completed the getting started tutorials for Vagrant.
Here are some interesting topics you might find relevant. 

### Learn more about Vagrant

- [Configuring VirtualBox settings](https://www.vagrantup.com/docs/virtualbox/)
- [Working with Plugins](https://www.vagrantup.com/docs/plugins/)
- [Customizing Synced Folders](https://www.vagrantup.com/docs/synced-folders/)
- [Provisioning with Puppet, Chef, or Ansible](https://www.vagrantup.com/docs/provisioning/)

### Try HashiCorp's other products

If you enjoyed these tutorials, find others like them covering HashiCorp's other products:

- [Terraform](/terraform) - Provision infrastructure as code.
- [Vault](/vault) - Manage secrets and protect data.
- [Consul](/consul) - Discover services and build service meshes.
- [Nomad](/nomad) - Deploy applications at any scale. 
- [Packer](/packer) - Build automated machine images.


Get Started

Create Your First Dev Environment

Quick Start

Install and Specify a Box

Configure the Network

Vagrant and Backend Providers

Explore other Providers

Using Vagrant with Packer

Vagrant Boxes

Looking for docs?

Infrastructure

Security

Networking

Applications

Get Started

Create Your First Dev Environment

Quick Start

Install and Specify a Box

Configure the Network

Vagrant and Backend Providers

Explore other Providers

Using Vagrant with Packer

Vagrant Boxes

Looking for docs?