Vagrant Repository

Cloudsmith provides public & private repositories for Vagrant boxes

Vagrant is an automation tool for building and managing virtual machine environments. Developed by the wizards at Hashicorp it makes setting up environments easier to manage.

For more information on Vagrant, please see:

Vagrant: The official website for Vagrant
Vagrant Docs: The official docs for Vagrant
Public Vagrant Repository: The official public repository for Vagrant boxes

Contextual Documentation
The examples in this document are generic. Cloudsmith provides contextual setup instructions within each repository, complete with copy and paste snippets (with your namespace/repo/rsa-key pre-configured).

In the following examples:

Identifier	Description
OWNER	Your Cloudsmith account name or organization name (namespace)
REPOSITORY	Your Cloudsmith Repository name (also called "slug")
TOKEN	Your Cloudsmith Entitlement Token (see Entitlements for more details)
USERNAME	Your Cloudsmith username
PASSWORD	Your Cloudsmith password
API-KEY	Your Cloudsmith API Key
BOX_NAME	The name of your Vagrant box
BOX_VERSION	The version number of your Vagrant box
PROVIDER_NAME	The name of the Vagrant provider (i.e virtualbox, hyperv, vmware_desktop etc)

Upload a Box

To upload, you need to generate your Vagrant box first. You can do this with:

shell

vagrant package --output BOX_NAME.box

This generates a box file (.box) like your-package-1.2.3.box that you can upload.

Note
This assumes that you've created a Vagrantfile file for your project and that you have used vagrant up at least once. Please see the official Vagrant docs for more information.

Upload via the Cloudsmith CLI

For full details of how to install and setup the Cloudsmith CLI, see Command Line Interface.

The command to upload an (Objective-C or Swift) CocoaPods package via the Cloudsmith CLI is:

shell

cloudsmith push vagrant OWNER/REPOSITORY BOX_NAME.box --provider PROVIDER_NAME --name BOX_NAME --version BOX_VERSION

Example:

shell

cloudsmith push vagrant your-account/your-repo awesome.box --provider virtualbox --name awesome --version 1.0

Upload via Cloudsmith UI

Please see Upload a Package for details of how to upload via the Cloudsmith web app.

Download / Install a Box

To enable the retrieval of Cloudsmith hosted Vagrant boxes, the box can either be added directly via Vagrant's CLI or the project's Vagrantfile can be updated.

Setup

To add the box directly via Vagrant's CLI, execute the following:

Public Repositories

shell

vagrant box add 'https://dl.cloudsmith.io/public/OWNER/REPOSITORY/vagrant/BOX_NAME/metadata.json' \
  --name 'BOX_NAME' \
  --box-version 'BOX_VERSION' \
  --provider 'PROVIDER_NAME'

Private Repositories

Private Repositories
Private Cloudsmith repositories require authentication. You can choose between two types of authentication, Entitlement Token Authentication or HTTP Basic Authentication. The setup method will differ depending on what authentication type you choose to use.

Warning
Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code, or expose them in any logs.

shell

vagrant box add 'https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/vagrant/BOX_NAME/metadata.json' \
  --name 'BOX_NAME' \
  --box-version 'BOX_VERSION' \
  --provider 'PROVIDER_NAME'

shell

vagrant box add 'https://USERNAME:PASSWORD@dl.cloudsmith.io/basic/OWNER/REPOSITORY/vagrant/BOX_NAME/metadata.json' \
  --name 'BOX_NAME' \
  --box-version 'BOX_VERSION' \
  --provider 'PROVIDER_NAME'

shell

vagrant box add 'https://USERNAME:API-KEY@dl.cloudsmith.io/basic/OWNER/REPOSITORY/vagrant/BOX_NAME/metadata.json' \
  --name 'BOX_NAME' \
  --box-version 'BOX_VERSION' \
  --provider 'PROVIDER_NAME'

shell

vagrant box add 'https://token:TOKEN@dl.cloudsmith.io/basic/OWNER/REPOSITORY/vagrant/BOX_NAME/metadata.json' \
  --name 'BOX_NAME' \
  --box-version 'BOX_VERSION' \
  --provider 'PROVIDER_NAME'

To add the box without having to specify the URL each time, the following must be added to the project's Vagrantfile:

Public Repositories

shell

config.vm.box = "BOX_NAME"
config.vm.box_url = "https://dl.cloudsmith.io/public/OWNER/REPOSITORY/vagrant/BOX_NAME/metadata.json"

Private Repositories

shell

config.vm.box = "BOX_NAME"
config.vm.box_url = "https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/vagrant/BOX_NAME/metadata.json"

shell

config.vm.box = "BOX_NAME"
config.vm.box_url = "https://USERNAME:PASSWORD@dl.cloudsmith.io/basic/OWNER/REPOSITORY/vagrant/BOX_NAME/metadata.json"

shell

config.vm.box = "BOX_NAME"
config.vm.box_url = "https://USERNAME:API-KEY@dl.cloudsmith.io/basic/OWNER/REPOSITORY/vagrant/BOX_NAME/metadata.json"

shell

config.vm.box = "BOX_NAME"
config.vm.box_url = "https://token:TOKEN@dl.cloudsmith.io/basic/OWNER/REPOSITORY/vagrant/BOX_NAME/metadata.json"

Install a Box

After you have added a box, Vagrants CLI tool can now be used as normal to install and start a box:

shell

vagrant up

Upstream Proxying / Caching

Not Supported

Key Signing Support

GPG

Troubleshooting

Please see the Troubleshooting page for further help and information.