Merge pull request #2501 from mitchellh/docs-revamp-content

[WIP] Update packer docs related to Atlas

website/source/docs/command-line/push.html.markdown

 ---
 description: |
-    The `packer push` Packer command takes a template and pushes it to a build
-    service that will automatically build this Packer template.
+    The `packer push` command uploads a template and other required files to the
+    Atlas build service, which will run your packer build for you.
 layout: docs
 page_title: 'Push - Command-Line'
 ...
 
 # Command-Line: Push
 
-The `packer push` Packer command takes a template and pushes it to a Packer
-build service such as [HashiCorp's Atlas](https://atlas.hashicorp.com). The
-build service will automatically build your Packer template and expose the
-artifacts.
+The `packer push` command uploads a template and other required files to the
+Atlas service, which will run your packer build for you. [Learn more about
+Packer in Atlas.](https://atlas.hashicorp.com/help/packer/features)
 
-External build services such as HashiCorp's Atlas make it easy to iterate on
-Packer templates, especially when the builder you are running may not be easily
-accessable (such as developing `qemu` builders on Mac or Windows).
+Running builds remotely makes it easier to iterate on packer builds that are not
+supported on your operating system, for example, building docker or QEMU while
+developing on Mac or Windows. Also, the hard work of building VMs is offloaded
+to dedicated servers with more CPU, memory, and network resources.
 
-!> The Packer build service will receive the raw copy of your Packer template
-when you push. **If you have sensitive data in your Packer template, you should
-move that data into Packer variables or environment variables!**
+When you use push to run a build in Atlas, you may also want to store your build
+artifacts in Atlas. In order to do that you will also need to configure the
+[Atlas post-processor](/docs/post-processors/atlas.html). This is optional, and
+both the post-processor and push commands can be used independently.
 
-For the `push` command to work, the [push
-configuration](/docs/templates/push.html) must be completed within the template.
+!> The push command uploads your template and other files, like provisioning
+scripts, to Atlas. Take care not to upload files that you don't intend to, like
+secrets or large binaries. **If you have secrets in your Packer template, you
+should [move them into environment
+variables](https://packer.io/docs/templates/user-variables.html).**
+
+Most push behavior is [configured in your packer
+template](/docs/templates/push.html). You can override or supplement your
+configuration using the options below.
 
 ## Options
 
@@ -30,12 +38,21 @@ configuration](/docs/templates/push.html) must be completed within the template.
     template much like a VCS commit message. This message will be passed to the
     Packer build service. This option is also available as a short option `-m`.
 
--   `-token` - An access token for authenticating the push to the Packer build
-    service such as Atlas. This can also be specified within the push
-    configuration in the template.
+-   `-token` - Your access token for the Atlas API.
+
+-> Login to Atlas to [generate an Atlas
+Token](https://atlas.hashicorp.com/settings/tokens). The most convenient way to
+configure your token is to set it to the `ATLAS_TOKEN` environment variable, but
+you can also use `-token` on the command line.
 
 -   `-name` - The name of the build in the service. This typically looks like
-    `hashicorp/precise64`.
+    `hashicorp/precise64`, which follows the form `<username>/<buildname>`. This
+    must be specified here or in your template.
+
+-   `-var` - Set a variable in your packer template. This option can be used
+    multiple times. This is useful for setting version numbers for your build.
+
+-   `-var-file` - Set template variables from a file.
 
 ## Examples
 
@@ -50,3 +67,32 @@ Push a Packer template with a custom token:
 ``` {.shell}
 $ packer push -token ABCD1234 template.json
 ```
+
+## Limits
+
+`push` is limited to 5gb upload when pushing to Atlas. To be clear, packer *can*
+build artifacts larger than 5gb, and Atlas *can* store artifacts larger than
+5gb. However, the initial payload you push to *start* the build cannot exceed
+5gb. If your boot ISO is larger than 5gb (for example if you are building OSX
+images), you will need to put your boot ISO in an external web service and
+download it during the packer run.
+
+## Building Private `.iso` and `.dmg` Files
+
+If you want to build a private `.iso` file you can upload the `.iso` to a secure
+file hosting service like [Amazon
+S3](http://docs.aws.amazon.com/AmazonS3/latest/dev/ShareObjectPreSignedURL.html),
+[Google Cloud
+Storage](https://cloud.google.com/storage/docs/gsutil/commands/signurl), or
+[Azure File
+Service](https://msdn.microsoft.com/en-us/library/azure/dn194274.aspx) and
+download it at build time using a signed URL. You should convert `.dmg` files to
+`.iso` and follow a similar procedure.
+
+Once you have added [variables in your packer
+template](/docs/templates/user-variables.html) you can specify credentials or
+signed URLs using Atlas environment variables, or via the `-var` flag when you
+run `push`.
+
+![Configure your signed URL in the Atlas build variables
+menu](/assets/images/packer-signed-urls.png)

website/source/docs/post-processors/atlas.html.markdown

@@ -11,9 +11,15 @@ page_title: 'Atlas Post-Processor'
 
 Type: `atlas`
 
-The Atlas post-processor for Packer receives an artifact from a Packer build and
-uploads it to Atlas. [Atlas](https://atlas.hashicorp.com) hosts and serves
-artifacts, allowing you to version and distribute them in a simple way.
+The Atlas post-processor uploads artifacts from your packer builds to Atlas for
+hosting. Artifacts hosted in Atlas are are automatically made available for use
+with Vagrant and Terraform, and Atlas provides additional features for managing
+versions and releases. [Learn more about packer in
+Atlas.](https://atlas.hashicorp.com/help/packer/features)
+
+You can also use the push command to [run packer builds in
+Atlas](/docs/command-line/push.html). The push command and Atlas post-processor
+can be used together or independently.
 
 ## Workflow
 
@@ -40,24 +46,22 @@ The configuration allows you to specify and access the artifact in Atlas.
 
 ### Required:
 
--   `token` (string) - Your access token for the Atlas API. This can be
-    generated on your [tokens
-    page](https://atlas.hashicorp.com/settings/tokens). Alternatively you can
-    export your Atlas token as an environmental variable and remove it from
-    the configuration.
+-   `token` (string) - Your access token for the Atlas API.
+
+-> Login to Atlas to [generate an Atlas
+Token](https://atlas.hashicorp.com/settings/tokens). The most convenient way to
+configure your token is to set it to the `ATLAS_TOKEN` environment variable, but
+you can also use `token` configuration option.
 
 -   `artifact` (string) - The shorthand tag for your artifact that maps to
     Atlas, i.e `hashicorp/foobar` for `atlas.hashicorp.com/hashicorp/foobar`.
-    You must have access to the organization, hashicorp in this example, in
-    order to add an artifact to the organization in Atlas.
+    You must have access to the organization—hashicorp in this example—in order
+    to add an artifact to the organization in Atlas.
 
 -   `artifact_type` (string) - For uploading AMIs to Atlas, `artifact_type` will
     always be `amazon.ami`. This field must be defined because Atlas can host
     other artifact types, such as Vagrant boxes.
 
--> **Note:** If you want to upload Vagrant boxes to Atlas, use the [Atlas
-post-processor](/docs/post-processors/atlas.html).
-
 ### Optional:
 
 -   `atlas_url` (string) - Override the base URL for Atlas. This is useful if