diff --git a/website/README.md b/website/README.md index 23ff6b39c72..b53b0bab6db 100644 --- a/website/README.md +++ b/website/README.md @@ -12,7 +12,8 @@ like any normal GitHub project, and we'll merge it in. ## Running the Site Locally -Running the site locally is simple. Clone this repo and run `make website`. +1. Install [Docker](https://docs.docker.com/engine/installation/) if you have not already done so +2. Clone this repo and run `make website` Then open up `http://localhost:4567`. Note that some URLs you may need to append ".html" to make them work (in the navigation). diff --git a/website/source/docs/basics/terminology.html.md b/website/source/docs/basics/terminology.html.md index 3566b0587bb..10249e4acb2 100644 --- a/website/source/docs/basics/terminology.html.md +++ b/website/source/docs/basics/terminology.html.md @@ -6,7 +6,7 @@ description: |- the meaning may not be immediately obvious if you haven't used Packer before. Luckily, there are relatively few. This page documents all the terminology required to understand and use Packer. The terminology is in alphabetical - order for easy referencing. + order for quick referencing. --- # Packer Terminology @@ -15,7 +15,7 @@ There are a handful of terms used throughout the Packer documentation where the meaning may not be immediately obvious if you haven't used Packer before. Luckily, there are relatively few. This page documents all the terminology required to understand and use Packer. The terminology is in alphabetical order -for easy referencing. +for quick referencing. - `Artifacts` are the results of a single build, and are usually a set of IDs or files to represent a machine image. Every builder produces a single artifact. diff --git a/website/source/docs/builders/azure.html.md b/website/source/docs/builders/azure.html.md index 5027ceb4c8d..0b63a794142 100644 --- a/website/source/docs/builders/azure.html.md +++ b/website/source/docs/builders/azure.html.md @@ -217,7 +217,7 @@ builder. The Azure builder uses ARM [templates](https://azure.microsoft.com/en-us/documentation/articles/resource-group-authoring-templates/) to deploy -resources. ARM templates make it easy to express the what without having to express the how. +resources. ARM templates allow you to express the what without having to express the how. The Azure builder works under the assumption that it creates everything it needs to execute a build. When the build has completed it simply deletes the resource group to cleanup any runtime resources. Resource groups are named using the diff --git a/website/source/docs/commands/index.html.md b/website/source/docs/commands/index.html.md index f785fcc8ddc..b31f8e128e3 100644 --- a/website/source/docs/commands/index.html.md +++ b/website/source/docs/commands/index.html.md @@ -35,8 +35,9 @@ However, Packer was built with automation in mind. To that end, Packer supports a fully machine-readable output setting, allowing you to use Packer in automated environments. -The machine-readable output format is easy to use and read and was made with -Unix tools in mind, so it is awk/sed/grep/etc. friendly. +Because the machine-readable output format was made with Unix tools in mind, it +is `awk`/`sed`/`grep`/etc. friendly and provides a familiar interface without +requiring you to learn a new format. ### Enabling Machine-Readable Output @@ -64,8 +65,8 @@ environments. ### Format for Machine-Readable Output The machine readable format is a line-oriented, comma-delimited text format. -This makes it extremely easy to parse using standard Unix tools such as awk or -grep in addition to full programming languages like Ruby or Python. +This makes it more convenient to parse using standard Unix tools such as `awk` or +`grep` in addition to full programming languages like Ruby or Python. The format is: @@ -92,7 +93,7 @@ Each component is explained below: Within the format, if data contains a comma, it is replaced with `%!(PACKER_COMMA)`. This was preferred over an escape character such as `\'` -because it is more friendly to tools like awk. +because it is more friendly to tools like `awk`. Newlines within the format are replaced with their respective standard escape sequence. Newlines become a literal `\n` within the output. Carriage returns diff --git a/website/source/docs/extending/custom-builders.html.md b/website/source/docs/extending/custom-builders.html.md index 6b5a7e708f1..dffabc838ab 100644 --- a/website/source/docs/extending/custom-builders.html.md +++ b/website/source/docs/extending/custom-builders.html.md @@ -25,8 +25,8 @@ recommend getting a bit more comfortable before you dive into writing plugins. ## The Interface The interface that must be implemented for a builder is the `packer.Builder` -interface. It is reproduced below for easy reference. The actual interface in -the source code contains some basic documentation as well explaining what each +interface. It is reproduced below for reference. The actual interface in the +source code contains some basic documentation as well explaining what each method should do. ```go @@ -109,8 +109,7 @@ respond to these cancellations and clean up after itself. The `Run` method is expected to return an implementation of the `packer.Artifact` interface. Each builder must create their own implementation. -The interface is very simple and the documentation on the interface is quite -clear. +The interface has ample documentation to help you get started. The only part of an artifact that may be confusing is the `BuilderId` method. This method must return an absolutely unique ID for the builder. In general, I diff --git a/website/source/docs/extending/custom-post-processors.html.md b/website/source/docs/extending/custom-post-processors.html.md index 16035d590d8..901c086762d 100644 --- a/website/source/docs/extending/custom-post-processors.html.md +++ b/website/source/docs/extending/custom-post-processors.html.md @@ -30,7 +30,7 @@ recommend getting a bit more comfortable before you dive into writing plugins. ## The Interface The interface that must be implemented for a post-processor is the -`packer.PostProcessor` interface. It is reproduced below for easy reference. The +`packer.PostProcessor` interface. It is reproduced below for reference. The actual interface in the source code contains some basic documentation as well explaining what each method should do. diff --git a/website/source/docs/extending/custom-provisioners.html.md b/website/source/docs/extending/custom-provisioners.html.md index 582a5704d81..2ac3c78e895 100644 --- a/website/source/docs/extending/custom-provisioners.html.md +++ b/website/source/docs/extending/custom-provisioners.html.md @@ -29,7 +29,7 @@ recommend getting a bit more comfortable before you dive into writing plugins. ## The Interface The interface that must be implemented for a provisioner is the -`packer.Provisioner` interface. It is reproduced below for easy reference. The +`packer.Provisioner` interface. It is reproduced below for reference. The actual interface in the source code contains some basic documentation as well explaining what each method should do. diff --git a/website/source/docs/extending/plugins.html.md b/website/source/docs/extending/plugins.html.md index c6e19745d88..29ec9e183fa 100644 --- a/website/source/docs/extending/plugins.html.md +++ b/website/source/docs/extending/plugins.html.md @@ -78,7 +78,7 @@ standpoint. Packer plugins must be written in [Go](https://golang.org/), so it is also assumed that you're familiar with the language. This page will not be a Go language tutorial. Thankfully, if you are familiar with Go, the Go toolchain -makes it extremely easy to develop Packer plugins. +provides many conveniences to help to develop Packer plugins. ~> **Warning!** This is an advanced topic. If you're new to Packer, we recommend getting a bit more comfortable before you dive into writing plugins. @@ -104,9 +104,10 @@ process. Pretty cool. ### Plugin Development Basics -Developing a plugin is quite simple. All the various kinds of plugins have a -corresponding interface. The plugin simply needs to implement this interface and -expose it using the Packer plugin package (covered here shortly), and that's it! +Developing a plugin allows you to create additional functionality for Packer. +All the various kinds of plugins have a corresponding interface. The plugin needs +to implement this interface and expose it using the Packer plugin package +(covered here shortly), and that's it! There are two packages that really matter that every plugin must use. Other than the following two packages, you're encouraged to use whatever packages you want. diff --git a/website/source/docs/post-processors/docker-import.html.md b/website/source/docs/post-processors/docker-import.html.md index b881253379a..6757473f633 100644 --- a/website/source/docs/post-processors/docker-import.html.md +++ b/website/source/docs/post-processors/docker-import.html.md @@ -22,8 +22,8 @@ registry. ## Configuration -The configuration for this post-processor is extremely simple. At least a -repository is required. +The configuration for this post-processor only requires a `repository`, a `tag` +is optional. - `repository` (string) - The repository of the imported image. diff --git a/website/source/docs/post-processors/docker-save.html.md b/website/source/docs/post-processors/docker-save.html.md index 98498bd3b80..7b950753934 100644 --- a/website/source/docs/post-processors/docker-save.html.md +++ b/website/source/docs/post-processors/docker-save.html.md @@ -24,7 +24,7 @@ familiar with this and vice versa. ## Configuration -The configuration for this post-processor is extremely simple. +The configuration for this post-processor only requires one option. - `path` (string) - The path to save the image. diff --git a/website/source/docs/post-processors/docker-tag.html.md b/website/source/docs/post-processors/docker-tag.html.md index 4925c62d772..c5ae9393752 100644 --- a/website/source/docs/post-processors/docker-tag.html.md +++ b/website/source/docs/post-processors/docker-tag.html.md @@ -25,8 +25,8 @@ that this works with committed resources, rather than exported. ## Configuration -The configuration for this post-processor is extremely simple. At least a -repository is required. +The configuration for this post-processor requires `repository`, all other settings +are optional. - `repository` (string) - The repository of the image. diff --git a/website/source/docs/post-processors/shell-local.html.md b/website/source/docs/post-processors/shell-local.html.md index a2b58b8e254..1d4fbfe1477 100644 --- a/website/source/docs/post-processors/shell-local.html.md +++ b/website/source/docs/post-processors/shell-local.html.md @@ -11,8 +11,9 @@ description: |- Type: `shell-local` -The local shell post processor executes scripts locally during the post processing stage. Shell local provides an easy -way to automate executing some task with the packer outputs. +The local shell post processor executes scripts locally during the post +processing stage. Shell local provides a convenient way to automate executing +some task with the packer outputs. ## Basic example diff --git a/website/source/docs/templates/engine.html.md b/website/source/docs/templates/engine.html.md index d896b0d8899..6c5eecc1ee8 100644 --- a/website/source/docs/templates/engine.html.md +++ b/website/source/docs/templates/engine.html.md @@ -31,10 +31,11 @@ globally available functions. ## Syntax -The syntax of templates is extremely simple. Anything template related happens -within double-braces: `{{ }}`. Variables are prefixed with a period and -capitalized, such as `{{.Variable}}` and functions are just directly within the -braces, such as `{{timestamp}}`. +The syntax of templates uses the following conventions: + +* Anything template related happens within double-braces: `{{ }}` +* Variables are prefixed with a period and capitalized, such as `{{.Variable}}` +* Functions are directly within the braces, such as `{{timestamp}}` Here is an example from the VMware VMX template that shows configuration templates in action: diff --git a/website/source/docs/templates/post-processors.html.md b/website/source/docs/templates/post-processors.html.md index e54165810ae..4b354a08575 100644 --- a/website/source/docs/templates/post-processors.html.md +++ b/website/source/docs/templates/post-processors.html.md @@ -44,9 +44,8 @@ apply to, if you wish. Within the `post-processors` array in a template, there are three ways to define a post-processor. There are *simple* definitions, *detailed* definitions, and -*sequence* definitions. Don't worry, they're all very easy to understand, and -the "simple" and "detailed" definitions are simply shortcuts for the "sequence" -definition. +*sequence* definitions. Another way to think about this is that the "simple" and +"detailed" definitions are shortcuts for the "sequence" definition. A **simple definition** is just a string; the name of the post-processor. An example is shown below. Simple definitions are used when no additional diff --git a/website/source/docs/templates/user-variables.html.md b/website/source/docs/templates/user-variables.html.md index 3aa7af3ec53..fde4cb98804 100644 --- a/website/source/docs/templates/user-variables.html.md +++ b/website/source/docs/templates/user-variables.html.md @@ -26,12 +26,11 @@ how configuration templates work yet, please read that page first. User variables must first be defined in a `variables` section within your template. Even if you want a variable to default to an empty string, it must be -defined. This explicitness makes it easy for newcomers to your template to +defined. This explicitness helps reduce the time it takes for newcomers to understand what can be modified using variables in your template. -The `variables` section is a simple key/value mapping of the variable name to a -default value. A default value can be the empty string. An example is shown -below: +The `variables` section is a key/value mapping of the variable name to a default +value. A default value can be the empty string. An example is shown below: ```json { @@ -58,11 +57,10 @@ If the default value is `null`, then the user variable will be *required*. This means that the user must specify a value for this variable or template validation will fail. -Using the variables is extremely easy. Variables are used by calling the user -function in the form of {{user \`variable\`}}. This function can be -used in *any value* within the template; in builders, provisioners, *anywhere -outside the `variables` section*. The user variable is available globally -within the rest of the template. +Variables are used by calling the user function in the form of +{{user \`variable\`}}. This function can be used in *any value* +within the template; in builders, provisioners, *anywhere outside the `variables` +section*. The user variable is available globally within the rest of the template. ## Environment Variables @@ -121,8 +119,8 @@ earlier set variables if it has already been set. ### From a File Variables can also be set from an external JSON file. The `-var-file` flag reads -a file containing a basic key/value mapping of variables to values and sets -those variables. The JSON file is simple: +a file containing a key/value mapping of variables to values and sets +those variables. An example JSON file may look like this: ```json { diff --git a/website/source/guides/veewee-to-packer.html.md b/website/source/guides/veewee-to-packer.html.md index 0642ad7fe8f..710cbae722c 100644 --- a/website/source/guides/veewee-to-packer.html.md +++ b/website/source/guides/veewee-to-packer.html.md @@ -30,9 +30,9 @@ $ gem install veewee-to-packer # ... ``` -Once installed, usage is easy! Just point `veewee-to-packer` at the -`definition.rb` file of any template. The converter will output any warnings or -messages about the conversion. The example below converts a CentOS template: +Once installed, just point `veewee-to-packer` at the `definition.rb` file of any +template. The converter will output any warnings or messages about the conversion. +The example below converts a CentOS template: ```text $ veewee-to-packer templates/CentOS-6.4/definition.rb diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md index 7f950b40615..8cda5ae205c 100644 --- a/website/source/intro/getting-started/build-image.html.md +++ b/website/source/intro/getting-started/build-image.html.md @@ -175,7 +175,7 @@ you will also need to set `associate_public_ip_address` to `true`, or set up a Packer only builds images. It does not attempt to manage them in any way. After they're built, it is up to you to launch or destroy them as you see fit. If you -want to store and namespace images for easy reference, you can use [Atlas by +want to store and namespace images for quick reference, you can use [Atlas by HashiCorp](https://atlas.hashicorp.com). We'll cover remotely building and storing images at the end of this getting started guide. diff --git a/website/source/intro/getting-started/install.html.md b/website/source/intro/getting-started/install.html.md index a0efa616a99..884683e9f15 100644 --- a/website/source/intro/getting-started/install.html.md +++ b/website/source/intro/getting-started/install.html.md @@ -4,7 +4,7 @@ sidebar_current: intro-getting-started-install page_title: Install Packer - Getting Started description: |- Packer must first be installed on the machine you want to run it on. To make - installation easy, Packer is distributed as a binary package for all supported + installation easier, Packer is distributed as a binary package for all supported platforms and architectures. This page will not cover how to compile Packer from source, as that is covered in the README and is only recommended for advanced users. @@ -13,7 +13,7 @@ description: |- # Install Packer Packer must first be installed on the machine you want to run it on. To make -installation easy, Packer is distributed as a [binary package](/downloads.html) +installation easier, Packer is distributed as a [binary package](/downloads.html) for all supported platforms and architectures. This page will not cover how to compile Packer from source, as that is covered in the [README](https://github.com/hashicorp/packer/blob/master/README.md) and is only diff --git a/website/source/intro/getting-started/parallel-builds.html.md b/website/source/intro/getting-started/parallel-builds.html.md index 6619dbcc16e..ec5918da354 100644 --- a/website/source/intro/getting-started/parallel-builds.html.md +++ b/website/source/intro/getting-started/parallel-builds.html.md @@ -166,7 +166,8 @@ us-east-1: ami-376d1d5e As you can see, Packer builds both the Amazon and DigitalOcean images in parallel. It outputs information about each in different colors (although you -can't see that in the block above) so that it is easy to identify. +can't see that in the block above), making it is easier to identify the actions +executed when you execute the command. At the end of the build, Packer outputs both of the artifacts created (an AMI and a DigitalOcean snapshot). Both images created are bare bones Ubuntu diff --git a/website/source/intro/getting-started/remote-builds.html.md b/website/source/intro/getting-started/remote-builds.html.md index 7ee554110d3..c9566ec929a 100644 --- a/website/source/intro/getting-started/remote-builds.html.md +++ b/website/source/intro/getting-started/remote-builds.html.md @@ -86,7 +86,7 @@ when you click on the active build, you can view the logs in real-time. Now we have Atlas building an AMI with Redis pre-configured. This is great, but it's even better to store and version the AMI output so it can be easily deployed by a tool like [Terraform](https://www.terraform.io). The `atlas` -[post-processor](/docs/post-processors/atlas.html) makes this process simple: +[post-processor](/docs/post-processors/atlas.html) makes this process easier: ```json {