From 4eacb3d492c58cc6fe2ef0eb793abd99d870dc5b Mon Sep 17 00:00:00 2001 From: Justin Campbell Date: Fri, 19 May 2017 11:01:01 -0400 Subject: [PATCH] website: Import Vagrant Enterprise docs --- .../docs/vagrant-cloud/boxes/catalog.html.md | 46 +++++++++++ .../boxes/create-version.html.md | 29 +++++++ .../docs/vagrant-cloud/boxes/create.html.md | 80 +++++++++++++++++++ .../vagrant-cloud/boxes/distributing.html.md | 59 ++++++++++++++ .../docs/vagrant-cloud/boxes/index.html.md | 32 ++++++++ .../vagrant-cloud/boxes/lifecycle.html.md | 47 +++++++++++ .../docs/vagrant-cloud/boxes/private.html.md | 44 ++++++++++ .../boxes/release-workflow.html.md | 24 ++++++ .../docs/vagrant-cloud/boxes/using.html.md | 23 ++++++ .../source/docs/vagrant-cloud/index.html.md | 13 +++ website/source/layouts/docs.erb | 21 +++++ 11 files changed, 418 insertions(+) create mode 100644 website/source/docs/vagrant-cloud/boxes/catalog.html.md create mode 100644 website/source/docs/vagrant-cloud/boxes/create-version.html.md create mode 100644 website/source/docs/vagrant-cloud/boxes/create.html.md create mode 100644 website/source/docs/vagrant-cloud/boxes/distributing.html.md create mode 100644 website/source/docs/vagrant-cloud/boxes/index.html.md create mode 100644 website/source/docs/vagrant-cloud/boxes/lifecycle.html.md create mode 100644 website/source/docs/vagrant-cloud/boxes/private.html.md create mode 100644 website/source/docs/vagrant-cloud/boxes/release-workflow.html.md create mode 100644 website/source/docs/vagrant-cloud/boxes/using.html.md create mode 100644 website/source/docs/vagrant-cloud/index.html.md diff --git a/website/source/docs/vagrant-cloud/boxes/catalog.html.md b/website/source/docs/vagrant-cloud/boxes/catalog.html.md new file mode 100644 index 000000000..bcc28c3e9 --- /dev/null +++ b/website/source/docs/vagrant-cloud/boxes/catalog.html.md @@ -0,0 +1,46 @@ +--- +layout: "docs" +page_title: "Discovering Vagrant Boxes" +sidebar_current: "vagrant-cloud-boxes-catalog" +--- + +# Discovering Vagrant Boxes + +Atlas serves a public, searchable index of Vagrant boxes. It's easy to find +boxes you can use with Vagrant that contain the technologies you need +for a Vagrant environment. + +You don't need an Atlas account to use public boxes. + +1. Go to the [Box search page](https://vagrantcloud.com/boxes/search) + +1. Once you find a box, click its name to learn more about it. + +1. When you're ready to use it, copy the name, such as "hashicorp/precise64" + and initialize your Vagrant project with `vagrant init hashicorp/precise64`. + Or, if you already have a Vagrant project created, modify the Vagrantfile + to use the box: `config.vm.box = "hashicorp/precise64"` + +## Provider Support + +Not all boxes are available for all providers. You may need +to sort by a provider that you have on your local system +to narrow down your search. + +## Choosing the Right Box + +As with all software and configuration used from a public source, +it's important to keep in mind whose box you're using. Here +are some things to note when you're choosing a box: + +- __The username of the user__. If it's `bento` or `canonical`, you can likely +trust the box more than an anonymous user +- __The number of downloads of the box__. Heavily downloaded boxes +are likely vetted more often by other members of the community. Hashicorp +responds to reports of malicious software distributed via Atlas +and takes down boxes +- __The latest release date__. More up-to-date boxes contain up-to-date +software +- __Availability of the box download__. Atlas periodically checks if box +has is publicly accessible. You can see this information on the box +page next to the provider diff --git a/website/source/docs/vagrant-cloud/boxes/create-version.html.md b/website/source/docs/vagrant-cloud/boxes/create-version.html.md new file mode 100644 index 000000000..d171e8704 --- /dev/null +++ b/website/source/docs/vagrant-cloud/boxes/create-version.html.md @@ -0,0 +1,29 @@ +--- +layout: "docs" +page_title: "Create a New Box Version" +sidebar_current: "vagrant-cloud-boxes-create-version" +--- + +# Create a New Box Version + +To release a new version of a box to the public or to your team: + + 1. Click on the name of the box you want to release a new version for. + + 2. To the right of the box name, there is a dropdown of all the available + versions. Click this, and click "Create a New Version" + + 3. Enter details for your new version and click "Create Version." Note that + after clicking create version, the version is not yet _released_. + + 4. Click "Create new provider" on this next page to add at least one + provider to the version. Specify the name of the provider (this is the + same value you specify to `--provider` when using Vagrant). Then + enter the URL to a self-hosted box file or upload a box to us. + + 5. Once the provider is created, you now have the option to release the + version by clicking "Release now," or you can add more providers. + +Once you click "Release now," that version will be available for installation +with Vagrant. Before clicking this, Vagrant does not know the version even +exists. diff --git a/website/source/docs/vagrant-cloud/boxes/create.html.md b/website/source/docs/vagrant-cloud/boxes/create.html.md new file mode 100644 index 000000000..7eaf84919 --- /dev/null +++ b/website/source/docs/vagrant-cloud/boxes/create.html.md @@ -0,0 +1,80 @@ +--- +layout: "docs" +page_title: "Creating a New Vagrant Box" +sidebar_current: "vagrant-cloud-boxes-create-x" +--- + +# Creating a New Vagrant Box + +This page will cover creating a new box in Atlas and how to distribute +it to users. Boxes can be distributed without Atlas, but +miss out on several [important features](/help/vagrant/boxes). + +There are __three ways to create and upload Vagrant Boxes to Atlas__. All +three options are outlined below. + +We recommend using Packer, as is it is fully repeatable and keeps a strong +history of changes within Atlas. However, for some situations, including +legacy workflows, the Web UI or API will work well. + +All three options require you [sign up for Atlas](/account/new). + +## Creating Boxes with Packer + +Using Packer requires more up front effort, but the repeatable and +automated builds will end any manual management of boxes. Additionally, +all boxes will be stored and served from Atlas, keeping a history along + the way. + +## Creating Boxes via the Atlas Web Interface + +You'll first need to create a box file. This can be done via +the [vagrant `package` command](http://docs.vagrantup.com/v2/boxes/base.html) +or with Packer locally. + +After you've created the `.box` file, this guide can be followed. + +1. Go to the [Create Box](/boxes/new) page. + +1. Name the box and give it a simple description + +1. Create your first version for the box. This version +must match the format `[0-9].[0-9].[0-9]` + +1. Create a provider for the box, matching the provider you need +locally in Vagrant. `virtualbox` is the most common provider. + +1. Upload the `.box` file for each provider, or use a url to the `.box` +file that is publicly accessible + +You can find all of your boxes in the [Vagrant section](/vagrant) of Atlas. + +Once you've created and released a box, you can release new versions of +the box by clicking "Create New Version" under the versions sidebar on +a box page. For more information on the release lifecycle of boxes, see +the [help page dedicated to box lifecycle](/help/boxes/lifecycle). + +## Creating Boxes with the API + +This example uses the [Boxes API](/docs) to upload boxes with `curl`. To +get started, you'll need to get an [access token](/settings/tokens). + +Then, prepare the upload: + + $ curl 'https://atlas.hashicorp.com/api/v1/box/USERNAME/BOX_NAME/version/VERSION/provider/PROVIDER_NAME/upload?access_token=ACCESS_TOKEN' + +This should return something like this: + + { + "upload_path": "https://archivist.hashicorp.com/v1/object/630e42d9-2364-2412-4121-18266770468e" + } + +Then, upload your box with the following command, with the filename in this case being `foo.box`: + + $ curl -X PUT --upload-file foo.box https://archivist.hashicorp.com/v1/object/630e42d9-2364-2412-4121-18266770468e + +When the upload finishes, you can verify it worked by making this request and matching the `hosted_token` it returns to the previously retrieved upload token. + + $ curl 'https://atlas.hashicorp.com/api/v1/box/USERNAME/BOX_NAME/version/VERSION_NUMBER/provider/PROVIDER_NAME?access_token=ACCESS_TOKEN' + +Your box should then be available for download. diff --git a/website/source/docs/vagrant-cloud/boxes/distributing.html.md b/website/source/docs/vagrant-cloud/boxes/distributing.html.md new file mode 100644 index 000000000..bb8c3f014 --- /dev/null +++ b/website/source/docs/vagrant-cloud/boxes/distributing.html.md @@ -0,0 +1,59 @@ +--- +layout: "docs" +page_title: "Distributing Boxes" +sidebar_current: "vagrant-cloud-boxes-distributing" +--- + +## Distributing Boxes + +To distribute the box to your team, update your Vagrantfile to reference the +box on Atlas. + + Vagrant.configure(2) do |config| + config.vm.box = "ATLAS_USERNAME_HERE/example-box" + end + +Now when a team member runs `vagrant up`, the box will be downloaded from Atlas. +If the box is private, the team member will be prompted to authorize access. Users +are granted access to private resources by logging in with an Atlas username and +password or by using a shared Atlas token. +[Learn more about authorization options here](/help/user-accounts/authentication). + +## Private Boxes + +If you create a private box, only you (the owner) and collaborators +will be able to access it. This is valuable if you +have information, data or provisioning in your box +that cannot be public. + +Private boxes will be excluded from the box catalog. + +### Collaborators + +Collaborators can be both teams in +organizations or individual users. + +To add a collaborator: + +1. Go to the "Access" page of a box via the sidebar +2. Enter the username or team name and submit the form +3. You'll now see an the user or team in the list of collaborators, +and if necessary a collaborator can be removed + +### Vagrant Login + +In order to access these private boxes from Vagrant, you'll need to first +authenticate with your Atlas account. + +1. Run `vagrant login` (with [the latest version of Vagrant](/help/intro/updating-tools)) +2. Enter your credentials + +You should now be logged in. We use these credentials to request +a unique authentication token that is stored locally by Vagrant. Your +username or password is never stored on your machine. + +### 404 Not Found + +If you don't authenticate, you will likely receive a `404 Not Found` +error in Vagrant. We return a 404 for security reasons, so a potential +attacker could not verify if a private box exists. diff --git a/website/source/docs/vagrant-cloud/boxes/index.html.md b/website/source/docs/vagrant-cloud/boxes/index.html.md new file mode 100644 index 000000000..8804615e7 --- /dev/null +++ b/website/source/docs/vagrant-cloud/boxes/index.html.md @@ -0,0 +1,32 @@ +--- +layout: "docs" +page_title: "About Vagrant Boxes" +sidebar_current: "vagrant-cloud-boxes" +--- + +# About Vagrant Boxes + +Boxes are the package format for [Vagrant](https://vagrantup.com) environments. +A box can be used on any Vagrant-supported platform to bring up an identical +working environment across a development team. + +## Vagrant Box Creation and Versioning + +Boxes support versioning so that members of your team using Vagrant can update +the underlying box easily, and the people who create boxes can push fixes and +communicate these fixes efficiently. + +Atlas makes it easy to manage the versioning of boxes. Versioning boxes in +Atlas allows for easy updates, transparent fixes, and clear communication in +changes made. Learn more about the [box release lifecycle +here](/docs/vagrant-cloud/boxes/lifecycle.html). + +## Vagrant Box Catalog and Discovery + +Atlas hosts a catalog of publically available Vagrant Boxes. These are boxes +created by both HashiCorp and community contributions. You can find an owner of +a box by selecting their username in the URL or on the box page. + +Public Vagrant boxes let you get up-and-running quickly in unfamiliar +environments. This is a popular way to set a base development environment +launchable in a single command within an organization or community. diff --git a/website/source/docs/vagrant-cloud/boxes/lifecycle.html.md b/website/source/docs/vagrant-cloud/boxes/lifecycle.html.md new file mode 100644 index 000000000..d02a02d50 --- /dev/null +++ b/website/source/docs/vagrant-cloud/boxes/lifecycle.html.md @@ -0,0 +1,47 @@ +--- +layout: "docs" +page_title: "Box Versioning and Lifecycle" +sidebar_current: "vagrant-cloud-boxes-lifecycle" +--- + +# Box Versioning and Lifecycle + +Boxes support versioning so that members of your team using Vagrant can +update the underlying box easily, and the people who create boxes can +push fixes and communicate these fixes efficiently. + +There are multiple components of a box: + +- The box itself, comprised of the box name and description. +- One or more box versions. +- One or more providers for each box version. + +## Vagrant Messaging + +Upon `vagrant up` or `vagrant box outdated`, an out-of-date box +user will see the following message in Vagrant: + + Bringing machine 'default' up with 'virtualbox' provider... + ==> default: Checking if box 'hashicorp/example' is up to date... + ==> default: A newer version of the box 'hashicorp/example' is available! You currently + ==> default: have version '0.0.5'. The latest is version '0.0.6'. Run + ==> default: `vagrant box update` to update. + ... + +## Box Version Release States + +Atlas lets you create new versions of boxes without +releasing them or without Vagrant seeing the update. This lets you prepare +a box for release slowly. Box versions have three states: + +- `unreleased`: Vagrant cannot see this version yet, so it needs +to be released. Versions can be released by editing them and clicking +the release button at the top of the page +- `active`: Vagrant is able to add and use this box version +- `revoked`: Vagrant cannot see this version, and it cannot be re-released. +You must create the version again + +### Release Requirements + +A box can only be released if it has at least one of each component: a +box, a version, and a provider. diff --git a/website/source/docs/vagrant-cloud/boxes/private.html.md b/website/source/docs/vagrant-cloud/boxes/private.html.md new file mode 100644 index 000000000..4f3d8ff6d --- /dev/null +++ b/website/source/docs/vagrant-cloud/boxes/private.html.md @@ -0,0 +1,44 @@ +--- +layout: "docs" +page_title: "Private Boxes" +sidebar_current: "vagrant-cloud-boxes-private" +--- + +# Private Boxes + +If you create a private box, only you (the owner) and collaborators +will be able to access it. + +## Collaborators + +To add a collaborator: + +1. Click the gear setting beside the boxes name in order to edit it. +2. Under the "Add Collaborator" section, enter their username and +submit the form. +3. You'll now see a list of collaborators, and if necessary a collaborator +can be removed. + +Collaborators can edit the box, versions and providers. The only +things they cannot do are: + +- Add another collaborator +- Delete the box + +## Vagrant Login + +In order to access these boxes from Vagrant, you'll need to first +authenticate with your Atlas account. + +1. Run `vagrant login` +2. Enter your credentials + +You should now be logged in. We use these credentials to request +a unique authentication token that is stored locally by Vagrant. Your +username or password is never stored on your machine. + +## 404 Not Found + +If you don't authenticate, you will likely receive a `404 Not Found` +error in Vagrant. We return a 404 for security reasons, so a potential +attacker could not verify if a private box exists. diff --git a/website/source/docs/vagrant-cloud/boxes/release-workflow.html.md b/website/source/docs/vagrant-cloud/boxes/release-workflow.html.md new file mode 100644 index 000000000..4f5a33648 --- /dev/null +++ b/website/source/docs/vagrant-cloud/boxes/release-workflow.html.md @@ -0,0 +1,24 @@ +--- +layout: "docs" +page_title: "API Release Workflow" +sidebar_current: "vagrant-cloud-boxes-release-workflow" +--- + +# API Release Workflow + +Creating new boxes through their [release lifecycle](/help/boxes/lifecycle) +is possible through the Atlas website, but you can also automate +the task via the Atlas API. + +1. Create box, or locate a boxes `tag`, like `hashicorp/precise64` +2. After some event, like the end of a CI build, you may want to +release a new version of the box. To do this, first use the API to +create a new version with a version number and a short description +of the changes +3. Then, create any providers associated with the version, like +`virtualbox` +4. Once your system has made the necessary requests to the API and the +version is ready, make a request to the `release` endpoint on the version +5. The version should now be available to users of the box via +the command `vagrant box outdated` or via the automated checks on +`vagrant up` diff --git a/website/source/docs/vagrant-cloud/boxes/using.html.md b/website/source/docs/vagrant-cloud/boxes/using.html.md new file mode 100644 index 000000000..548a34541 --- /dev/null +++ b/website/source/docs/vagrant-cloud/boxes/using.html.md @@ -0,0 +1,23 @@ +--- +layout: "docs" +page_title: "Finding and Using Boxes" +sidebar_current: "vagrant-cloud-boxes-using" +--- + +# Finding and Using Boxes + +A primary use case of Atlas by HashiCorp is to be able to easily find +boxes you can use with Vagrant that contain the technologies you need +for a Vagrant environment. We've made it extremely easy to do that: + +1. Go to the [Discover page](/discover) + +2. Search for any box you want, or use the navigation on the left + to see [featured](/discover/featured) boxes. + +3. Once you find a box, click its name to learn more about it. + +4. When you're ready to use it, copy the name, such as "hashicorp/precise64" + and initialize your Vagrant project with `vagrant init hashicorp/precise64`. + Or, if you already have a Vagrant project created, modify the Vagrantfile + to use the box: `config.vm.box = "hashicorp/precise64"` diff --git a/website/source/docs/vagrant-cloud/index.html.md b/website/source/docs/vagrant-cloud/index.html.md new file mode 100644 index 000000000..53cb94aaa --- /dev/null +++ b/website/source/docs/vagrant-cloud/index.html.md @@ -0,0 +1,13 @@ +--- +layout: "docs" +page_title: "Vagrant Enterprise" +sidebar_current: "vagrant-cloud" +--- + +# Vagrant Enterprise + +Vagrant Enterprise provides the following features for Vagrant: + +- [Vagrant Box Catalog](/docs/vagrant-cloud/boxes/catalog.html) +- [Vagrant Box Creation](/docs/vagrant-cloud/boxes/create.html) +- [Vagrant Box Versioning](/docs/vagrant-cloud/boxes/lifecycle.html) diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 59e16b863..53d85da4f 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -214,6 +214,27 @@ >WSL + +
+ + > + Vagrant Enterprise + + <% end %>