build-support/packer/README.md

# Apache Aurora development environment

This directory contains [Packer](https://packer.io) scripts
to build and distribute the base development environment for Aurora.

The goal of this environment is to pre-fetch dependencies and artifacts
needed for the integration test environment so that `vagrant up` is
cheap after the box has been fetched for the first time.

As dependencies (libraries, or external packages) of Aurora change, it
will be helpful to update this box and keep this cost low.

## Updating the box

1. Download [packer](https://www.packer.io/downloads.html)

2. Modify build scripts to make the changes you want
   (e.g. install packages via `apt`)

3. Fetch the latest version of our base box

        $ vagrant box update --box bento/ubuntu-16.04

    The box will be stored in version-specific directory under
    `~/.vagrant.d/boxes/bento-VAGRANTSLASH-ubuntu-16.04/`.  Find the path to the `.ovf` file for the
    latest version of the box.  For the remainder of this document, this path will be referred to as
    `$UBUNTU_OVF`.

4. Build the new box
    Using the path from the previous step, run the following command to start the build.

        $ packer build -var "base_box_ovf=$UBUNTU_OVF" aurora.json

    This takes a while, approximately 20 minutes.  When finished, your working directory will
    contain a file named `packer_virtualbox-ovf_virtualbox.box`.

5. Verify your box locally

        $ vagrant box add --name aurora-dev-env-testing \
          packer_virtualbox-ovf_virtualbox.box

    This will make a vagrant box named `aurora-dev-env-testing` locally available to vagrant
    (i.e. not on Vagrant Cloud).  We use a different name here to avoid confusion that could
    arise from using an unreleased base box.

    Edit the [`Vagrantfile`](../../Vagrantfile), changing the line

        config.vm.box = "apache-aurora/dev-environment"

    to

        config.vm.box = "aurora-dev-env-testing"

    and comment out vm version

        # config.vm.box_version = "0.0.X"

    At this point, you can use the box as normal to run integration tests.

6. Upload the box to Vagrant Cloud
    Our boxes are stored in [Vagrant Cloud](https://vagrantcloud.com/apache-aurora/dev-environment).

    In order to upload a new version of our box, you must have committer access to upload
    a dev image box, please ask in dev@aurora.apache.org or our Slack Channel
    if you would like to contribute. More info can be found by visiting our
    [community page](http://aurora.apache.org/community/).

    Once you have access to our Vagrant Cloud organization, a token can be generated by
    going to your [security settings](https://app.vagrantup.com/settings/security).
    Store the token in a safe place as it will be needed for future submissions.

    Next, three environmental variables must be set: `$UBUNTU_OVF`, `$VAGRANT_CLOUD_TOKEN`,
    and `$BOX_VERSION`.

        $ export UBUNTU_OVF=<Location of base image (.ovf) on local machine>
        $ export VAGRANT_CLOUD_TOKEN=<API Token from Hashicorp>
        $ export BOX_VERSION=<SemVer to be given to this box>

    **Make sure the variables are set correctly before proceeding as a mistake can cause
    the very time consuming process to fail or clobber a previous box.**

        $ env | grep -E "UBUNTU_OVF|VAGRANT_CLOUD_TOKEN|BOX_VERSION"

    Then finally run the release packer configuration which will upload the vagrant box.

        $ packer build aurora-release.json

    Note: This process will rebuild the box and upload it to the Vagrant Cloud. Unfortunately,
    there currently is no way to skip the build step as the output from the first post-processor
    (Vagrant) is required for the second (Vagrant-Cloud).

    You may now change the version in [`Vagrantfile`](../../Vagrantfile) to the one specified in
    `$BOX_VERSION` and commit the change.