How To Use DigitalOcean as Your Provider in Vagrant on an Ubuntu 12.10 VPS

About Vagrant

Vagrant is a powerful open source software for configuring and deploying multiple development environments. It is designed to work on Linux, Mac OS X, or Windows and although it comes with VirtualBox for the virtualization needs, it can be used also with other providers such as VMware or AWS.

In this tutorial, we will set up Vagrant to use DigitalOcean as a provider. This means that you will be able to use DO droplets (VPS) as development machines to deploy from Vagrant. The tutorial assumes you have already installed Vagrant on your environment and it is recommended you consult two previous articles about Vagrant:

1. How to Install Vagrant on a VPS Running Ubuntu 12.04
2. How to Use Vagrant on Your Own VPS Running Ubuntu

Installing the DigitalOcean: Vagrant Integration Plugin

To install the plugin, you have to follow two quick steps. First, run the command of installing the plugin:

vagrant plugin install vagrant-digitalocean

Followed by the command to add the new box to Vagrant (remember what boxes are from the previous articles?):

vagrant box add digital_ocean https://github.com/smdahlen/vagrant-digitalocean/raw/master/box/digital_ocean.box

Configuring a Project to Run with this Provider

In order to use this plugin, you’ll need some form of letting Vagrant communicate with DigitalOcean. This is why the API is there, and why you now have to log into your DigitalOcean account and generate a new API key for authentication. Navigate to https://www.digitalocean.com/api_access and click Create to generate your new API key. You'll use this in the configuration together with your client ID seen above it.

Now that you have installed the plugin, added the DO specific box, and you have your API key ready. Let’s create a project that will use them. In the previous articles we’ve been working with a project to illustrate how Vagrant works with its default provider: VirtualBox. Let’s now create another project for DigitalOcean cloud server. Create a root directory for it (outside of the previous project folder) and navigate in it:

mkdir test_project2
cd test_project2

Next, run the initialization command:

vagrant init

This will create the required Vagrantfile.

Before we edit this file, let’s create the SSH keys needed for authentication with DigitalOcean. Run the following command to generate your SSH key pair:

ssh-keygen -t rsa

You can accept the defaults by pressing enter. This will place the SSH private and public keys to the path we will specify below in the Vagrantfile configuration. For more information about generating SSH key, check out this tutorial. Now let’s edit the Vagrantfile and configure it:

nano Vagrantfile

Find the following line:

config.vm.box = "base"

And replace it with:

config.vm.box = "digital_ocean"

Below it, add the following lines:

config.ssh.private_key_path = "~/.ssh/id_rsa"
config.vm.provider :digital_ocean do |provider|
    provider.client_id = "YOUR CLIENT ID"
    provider.api_key = "YOUR API KEY"
    provider.image = "Ubuntu 12.10 x64"
    provider.region = "New York 2"
  end

With the first line, you are specifying the path to the SSH private key file. This means that the provider will create a new DigitalOcean SSH key using your public key which is at that path with a .pub extension (the one you created earlier). The next two lines are for the DO API, so make sure you replace where needed with your client ID and the API key. With the image, you specify what type of cloud server you want deployed whereas with the region you choose the DigitalOcean data center you’d like the droplet to be created in. To see the available options, check the DO droplet creation page.

You can add some additional settings in the vm.provider block:

• provider.size: A string representing the size to use when creating a new VPS (e.g. 1GB). Currently, it defaults to 512MB.
• provider.ssh_key_name: A string representing the name to use when creating a DigitalOcean SSH key for VPS authentication. It defaults to Vagrant.

Save the file and exit. Now you can run the vagrant up command specifying the DigitalOcean provider to deploy your new VPS:

vagrant up --provider=digital_ocean

If you get the following error:

The secure connection to the DigitalOcean API has failed. Please
ensure that your local certificates directory is defined in the
provider config.

    config.vm.provider :digital_ocean do |vm|
      vm.ca_path = "/path/to/ssl/ca/cert.crt"
    end

This is generally caused by the OpenSSL configuration associated
with the Ruby install being unaware of the system specific ca
certs.

It means you are missing the root certificates necessary to communicate with DigitalOcean. To fix it, open the .bashrc file:

nano ~/.bashrc

And add the following line at the bottom:

export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt

Save the file and exit. Open again the Vagrantfile and add the following line below the one in which you specified the region (the order is not so important but it has to be part of the vm.provider block):

provider.ca_path = "/etc/ssl/certs/ca-certificates.crt"

Save the file and exit. Now try again to deploy the VPS:

vagrant up --provider=digital_ocean

Now a droplet should be created in your account, in the specified region and using the image you wanted. You can check it out in your DO account. You can use that basically as you would have used a VirtualBox guest machine.

Supported Commands

The provider supports the following Vagrant sub-commands:

• vagrant destroy: Destroys the droplet instance.
• vagrant ssh: Logs into the droplet instance using the configured user account.
• vagrant halt: Powers off the droplet instance.
• vagrant provision: Runs the configured provisioners and rsyncs any specified config.vm.synced_folder.
• vagrant reload: Reboots the droplet instance.
• vagrant rebuild: Destroys the droplet instance and recreates it with the same IP address is was assigned to previously.
• vagrant status: Outputs the status (active, off, not created) for the droplet instance.

Many thanks to Shawn Dahlen for creating this plugin.

Vagrant—Article #1

Vagrant—Article #2

Vagrant—Article #3