= An Example cartage.yml

The best way to understand how to configure Cartage is to see an annotated
example of a +cartage.yml+ file.

== Secrets and cartage.yml

The items in the main part of the Cartage configuration are *not* generally
secret, but they are also not typically things that would be set in a static
configuration file. The main value that would probably be set under most
circumstances is the +name+ value.

Because Cartage reads its configuration through ERB, the following structure is
recommended for +config/cartage.yml+.

    ---
    name: my-application

    # This must not be indented for it to work.
    <% if File.exist?('config/ansible/cartage.yml') %>
    <%= File.read('config/ansible/cartage.yml') %>
    <% end %>
    <% if File.exist?('config/local/cartage.yml') %>
    <%= File.read('config/local/cartage.yml') %>
    <% end %>

== Main Cartage Configuration Options

=== +name+

The name of the application. Optional, defaults to the basename of the origin
Git URL. Overridden with <tt>cartage --name NAME</tt>.

    name: my-application

=== +target+

The target path for the Cartage package. Optional and defaults to
<tt>./tmp</tt>. Overridden with <tt>cartage --target PATH</tt>.

    target: tmp/cartage

=== +root_path+

The root path of the application. Optional, defaults to the top of the Git
repository (<tt>git rev-parse --show-cdup</tt>). Overridden with <tt>cartage
--root-path ROOT_PATH</tt>.

    root_path: .

=== +timestamp+

The timestamp for the final package (which is
<tt><em>name</em>-<em>timestamp</em></tt>). Optional, defaults to the current
time in UTC. Overridden with <tt>cartage --timestamp TIMESTAMP</tt>. This
value is *not* validated to be a time value when supplied.

    timestamp: not-a-timestamp

=== +bundle_cache+

The bundle cache path, where the package’s <tt>vendor-bundle.tar.bz2</tt>
will be stored between builds. Optional, defaults to <tt>./tmp</tt>.
Overridden with <tt>cartage --bundle-cache BUNDLE_CACHE</tt>.

    bundle_cache: tmp/cache

=== +without+

The groups to exclude from <tt>bundle install</tt>. Optional, defaults to <tt>[
"development", "test"]</tt>. Overridden with <tt>cartage --without
group1,group2</tt>.

    without:
      - development
      - test
      - other

=== +plugins+

A dictionary that contains all plug-in configuration, keyed by plug-in name.

== Cartage Plug-In Configuration Options

=== cartage-s3

Cartage-s3 needs to know where to put the completed package and how to log into
the selected storage provider.

==== +path+

The path to the cartage S3 bucket or directory (for another service that
Fog::Storage supports). This has no default and is overridden with <tt>cartage
s3 --path PATH</tt>.

    plugins:
      s3:
        path: cartage-bucket

==== +credentials+

The credentials dictionary passed to Fog::Storage for uploads. Each provider
has different keys. If present, this will dictionary be used in preference to
<tt>cartage s3</tt> flags <tt>--key-id</tt>, <tt>--secret-key</tt>, and
<tt>--region</tt> as those work *only* with Amazon AWS S3.

===== AWS

AWS S3 storage connections need +provider+, +aws_access_key_id+,
+aws_secret_access_key+, and +region+.

    plugins:
      s3:
        credentials:
          provider: AWS
          aws_access_key_id: YOUR_AWS_ACCESS_KEY_ID
          aws_secret_access_key: YOUR_AWS_SECRET_ACCESS_KEY
          region: us-west-2

===== Rackspace

Rackspace storage connections need +provider+, +rackspace_username+,
+rackspace_api_key+, and optionally +rackspace_auth_url+.

    plugins:
      s3:
        credentials:
          provider: Rackspace
          rackspace_username: RACKSPACE_USERNAME
          rackspace_api_key: RACKSPACE_API_KEY
          rackspace_auth_url: lon.auth.api.rackspacecloud.com

===== Google

Google storage connections need +provider+, +google_storage_access_key_id+, and
+google_storage_secret_access_key+.

    plugins:
      s3:
        credentials:
          provider: Google
          google_storage_access_key_id: YOUR_SECRET_ACCESS_KEY_ID
          google_storage_secret_access_key: YOUR_SECRET_ACCESS_KEY

=== cartage-remote

Cartage-remote needs to know where its remote build is going to run and how to
authenticate. It may also be told *what* to run. For cartage-remote 1.0, the
+remote+ configuration section is *required* (at least the +server+ key).

==== +server+

The name of the build server. This field is required and can show up in two
different formats. The first is as a string matching
<tt>[user@]host[:port]</tt>.

    plugins:
      remote:
        server: build@my-build-machine:2222

The second is as a dictionary with +user+, +host+, and +port+ keys.

    plugins:
      remote:
        server:
          user: build
          host: my-build-machine
          port: 2222

==== +keys+

The SSH key(s) used to connect to the server. Optional, and cartage-remote will
use <tt>~/.ssh/*id_[rd]sa</tt> to find keys if this is not provided. The first
format is as a dictionary, embedding private keys directly in the configuration
file.

    plugins:
      remote:
        keys:
          custom: |
            -----BEGIN RSA PRIVATE KEY-----
            ...
            -----END RSA PRIVATE KEY-----

The second form is as an array of glob patterns to match key files.

    plugins:
      remote:
        keys:
          - "config/secrets/*id_[rd]sa"
          - "~/.ssh/*id_[rd]sa"

The third form is as a single glob pattern to match key files or a specific key
file.

    plugins:
      remote:
        keys: "config/secrets/*id_[rd]sa"

==== +build+

The build script that will be run on the remote server. This is optional with a
reasonable default, below.

    #!/bin/bash
    set -e
    if [ -f Gemfile ]; then
      bundle install --path %<remote_bundle>s
      bundle exec cartage build \
        --config-file %<config_file>s \
        --target %<project_path>s
    else
      cartage build --config-file %<config_file>s \
        --target %<project_path>s
    fi

An example with an alternate build script that uses cartage-s3 to upload.

    plugins:
      remote:
        build: |
          #!/bin/bash
          set -e
          if [ -f Gemfile ]; then
            bundle install --path %<remote_bundle>s
            bundle exec cartage s3 \
              --config-file %<config_file>s \
              --target %<project_path>s \
              --verbose
          else
            cartage build \
              --config-file %<config_file>s \
              --target %<project_path>s \
              --verbose
          fi

==== +prebuild+

The prebuild script that will be run on the local system. This is optional with
a reasonable default, below:

    #!/bin/bash
    ssh-keyscan -H %<remote_host>s >> ~/.ssh/known_hosts

An example with a slightly extended example is below. It is strongly
recommended that the <tt>ssh-keyscan</tt> step be run in all prebuild scripts
as cartage-remote runs SSH in a paranoid mode.

    plugins:
      remote:
        prebuild: |
          #!/bin/bash
          ssh-keyscan -H %<remote_host>s >> ~/.ssh/known_hosts
          echo 'Prebuild complete'

==== +postbuild+

The postbuild script that will be run on the local system. This is optional
with no default (no post-build actions).

The postbuild script will be passed the stage identifier as <tt>$1</tt>
(valid values are +config+, +ssh_config+, +prebuild+, +remote_clone+,
+remote_build+, +cleanup+, or +finished+). If the build was interrupted with
an error, the error message will be passed as <tt>$2</tt>.

An example that posts a message to Slack is below.

    plugins:
      remote:
        postbuild: |
          #!/bin/bash
          case ${1:-undefined} in
            finished)
              t="token=SLACK_TOKEN"
              c="channel=%23ci"
              d=MYDOMAIN
              u="https://${d}.slack.com/services/hooks/slackbot?${t}&${c}"
              curl --data "Build %<name>s-%<timestamp>s complete." ${u}
              ;;
            *)
              : # ${1} is the stage, ${2} is the error message
              ;;
          esac