github.com/aspring/packer@v0.8.1-0.20150629211158-9db281ac0f89/README.md (about)

     1  # Packer
     2  
     3  [![Build Status](https://travis-ci.org/mitchellh/packer.svg?branch=master)](https://travis-ci.org/mitchellh/packer)
     4  
     5  * Website: http://www.packer.io
     6  * IRC: `#packer-tool` on Freenode
     7  * Mailing list: [Google Groups](http://groups.google.com/group/packer-tool)
     8  
     9  Packer is a tool for building identical machine images for multiple platforms
    10  from a single source configuration.
    11  
    12  Packer is lightweight, runs on every major operating system, and is highly
    13  performant, creating machine images for multiple platforms in parallel.
    14  Packer comes out of the box with support for the following platforms:
    15  * Amazon EC2 (AMI). Both EBS-backed and instance-store AMIs
    16  * DigitalOcean
    17  * Docker
    18  * Google Compute Engine
    19  * OpenStack
    20  * Parallels
    21  * QEMU. Both KVM and Xen images.
    22  * VirtualBox
    23  * VMware
    24  
    25  Support for other platforms can be added via plugins.
    26  
    27  The images that Packer creates can easily be turned into
    28  [Vagrant](http://www.vagrantup.com) boxes.
    29  
    30  ## Quick Start
    31  
    32  **Note:** There is a great
    33  [introduction and getting started guide](http://www.packer.io/intro)
    34  for those with a bit more patience. Otherwise, the quick start below
    35  will get you up and running quickly, at the sacrifice of not explaining some
    36  key points.
    37  
    38  First, [download a pre-built Packer binary](http://www.packer.io/downloads.html)
    39  for your operating system or [compile Packer yourself](#developing-packer).
    40  
    41  After Packer is installed, create your first template, which tells Packer
    42  what platforms to build images for and how you want to build them. In our
    43  case, we'll create a simple AMI that has Redis pre-installed. Save this
    44  file as `quick-start.json`. Be sure to replace any credentials with your
    45  own.
    46  
    47  ```json
    48  {
    49    "builders": [{
    50      "type": "amazon-ebs",
    51      "access_key": "YOUR KEY HERE",
    52      "secret_key": "YOUR SECRET KEY HERE",
    53      "region": "us-east-1",
    54      "source_ami": "ami-de0d9eb7",
    55      "instance_type": "t1.micro",
    56      "ssh_username": "ubuntu",
    57      "ami_name": "packer-example {{timestamp}}"
    58    }]
    59  }
    60  ```
    61  
    62  Next, tell Packer to build the image:
    63  
    64  ```
    65  $ packer build quick-start.json
    66  ...
    67  ```
    68  
    69  Packer will build an AMI according to the "quick-start" template. The AMI
    70  will be available in your AWS account. To delete the AMI, you must manually
    71  delete it using the [AWS console](https://console.aws.amazon.com/). Packer
    72  builds your images, it does not manage their lifecycle. Where they go, how
    73  they're run, etc. is up to you.
    74  
    75  ## Documentation
    76  
    77  Full, comprehensive documentation is viewable on the Packer website:
    78  
    79  http://www.packer.io/docs
    80  
    81  ## Developing Packer
    82  
    83  If you wish to work on Packer itself or any of its built-in providers,
    84  you'll first need [Go](http://www.golang.org) installed (version 1.4+ is
    85  _required_). Make sure Go is properly installed, including setting up
    86  a [GOPATH](http://golang.org/doc/code.html#GOPATH).
    87  
    88  Next, install the following software packages, which are needed for some dependencies:
    89  
    90  - [Bazaar](http://bazaar.canonical.com/en/)
    91  - [Git](http://git-scm.com/)
    92  - [Mercurial](http://mercurial.selenic.com/)
    93  
    94  Then, install [Gox](https://github.com/mitchellh/gox), which is used
    95  as a compilation tool on top of Go:
    96  
    97      $ go get -u github.com/mitchellh/gox
    98  
    99  Next, clone this repository into `$GOPATH/src/github.com/mitchellh/packer`.
   100  Install the necessary dependencies by running `make updatedeps` and then just
   101  type `make`. This will compile some more dependencies and then run the tests. If
   102  this exits with exit status 0, then everything is working!
   103  
   104      $ make updatedeps
   105      ...
   106      $ make
   107      ...
   108  
   109  To compile a development version of Packer and the built-in plugins,
   110  run `make dev`. This will put Packer binaries in the `bin` folder:
   111  
   112      $ make dev
   113      ...
   114      $ bin/packer
   115      ...
   116  
   117  
   118  If you're developing a specific package, you can run tests for just that
   119  package by specifying the `TEST` variable. For example below, only
   120  `packer` package tests will be run.
   121  
   122      $ make test TEST=./packer
   123      ...
   124  
   125  ### Acceptance Tests
   126  
   127  Packer has comprehensive [acceptance tests](https://en.wikipedia.org/wiki/Acceptance_testing)
   128  covering the builders of Packer.
   129  
   130  If you're working on a feature of a builder or a new builder and want
   131  verify it is functioning (and also hasn't broken anything else), we recommend
   132  running the acceptance tests.
   133  
   134  **Warning:** The acceptance tests create/destroy/modify *real resources*, which
   135  may incur real costs in some cases. In the presence of a bug, it is technically
   136  possible that broken backends could leave dangling data behind. Therefore,
   137  please run the acceptance tests at your own risk. At the very least,
   138  we recommend running them in their own private account for whatever builder
   139  you're testing.
   140  
   141  To run the acceptance tests, invoke `make testacc`:
   142  
   143  ```sh
   144  $ make testacc TEST=./builder/amazon/ebs
   145  ...
   146  ```
   147  
   148  The `TEST` variable is required, and you should specify the folder where the
   149  backend is. The `TESTARGS` variable is recommended to filter down to a specific
   150  resource to test, since testing all of them at once can sometimes take a very
   151  long time.
   152  
   153  Acceptance tests typically require other environment variables to be set for
   154  things such as access keys. The test itself should error early and tell
   155  you what to set, so it is not documented here.