= Cartage by Kinetic Cafe

code :: https://github.com/KineticCafe/cartage/
issues :: https://github.com/KineticCafe/cartage/issues
docs :: http://www.rubydoc.info/github/KineticCafe/cartage/master

== Description

Cartage provides a repeatable means to create a package for a server-side
application that can be used in deployment with a configuration tool like
Ansible, Chef, Puppet, or Salt. The package is created with vendored
dependencies so that it can be deployed in environments with strict access
control rules and without requiring development tool presence on the target
server(s).

This is the last release of cartage. It's been a fun ride, but Docker-based
images are our future at Kinetic Commerce. There is one feature that remains
useful, the release-metadata output. We have created a new, more extensible
format for which we will be creating a gem to manage this. One example of the
implementation can be found at:

https://github.com/KineticCafe/release-metadata-ts

We will also be replacing `cartage-rack` with a new gem supporting this new
format.

=== Overview

Cartage has learned its tricks from Heroku’s build process, Capistrano
deployments, and Hoe. From Hoe, it learned to keep a manifest to control what
is packaged (as well as its plug-in system). From Heroku, it learned to keep
a simple ignore file. From Capistrano, it learned to mark the Git hashref as
a file in its built package, and to timestamp the packages.

Cartage follows a relatively simple set of steps when creating a package:

1.  Copy the application files to the work area. The application’s files are
    specified in +Manifest.txt+ and filtered against the exclusion list
    (+.cartignore+). If there is no +.cartignore+, try to use +.slugignore+. If
    there is no +.slugignore+, Cartage will use a sensible default exclusion
    list. To override the use of this exclusion list, an empty +.cartignore+
    file must be present.

2.  The Git hashref is written to the work area (as +release_manifest.json+) and to
    the package staging area.

3.  Files that have been modified are restored to pristine condition in the
    work area. The source files are not touched. (This ensures that a Rails
    +config/database.yml+, for example, will not be the version used by a
    continuous integration system.)

4.  Dependencies are vendored using installed and enabled plug-ins. Vendored
    dependencies will be cached for speeding up future installations.

5.  A timestamped tarball is created from the contents of the work area. It can
    then be copied to a more permanent or accessible location.

Cartage is extremely opinionated about its tools and environment:

*   The packages are created with +tar+ and +bzip2+ using <tt>tar cfj</tt>.
    (The compression method is configurable, but defaults to +bzip2+.)
*   Cartage only understands +git+, which is used for creating
    <tt>release_manifest.json</tt>s, +Manifest.txt+ creation and comparison, and even
    default application name detection (from the name of the origin remote).

== Synopsis

    # Build a package from the current machine, using the Manifest.txt.
    cartage pack # or cartage build

    # Create or update a Manifest.txt from the current repository.
    cartage manifest generate # or cartage manifest update
    # Check the current Manifest against the files that should be there.
    cartage manifest check

    # Show the files that will be included in the package.
    cartage manifest show

    # Create a .cartignore file for use.
    cartage manifest cartignore
    # Overwrite the current .cartignore with the default.
    cartage manifest cartignore --force # or --mode overwrite
    # Merge the current .cartignore with the default. Merging automatically
    # removes any comments.
    cartage manifest cartignore --merge # or --mode merge

== Install

Add cartage to your Gemfile:

    gem 'cartage', '~> 2.0', groups: [ :development, :test ]

Or manually install:

    % gem install cartage

Cartage should not be part of your production environment; its purpose is to
*create* production-ready packages.

== Alternate Projects

The closest project to Cartage is {pkgr}[https://github.com/crohr/pkgr]. Pkgr
will create a distribution package for Ubuntu (14.04 and 12.02, Debian 7),
CentOS 6, SLES 12, and Fedora 20.

Both Cartage and Pkgr provide isolated builds with all in-application
dependencies included.

Pkgr offers some advantages over Cartage:

* It includes language interpreters local to the deployed application, as
  appropriate.

* It has built-in support for Ruby, Go, and Node.js.

* It creates an OS distribution package, meaning that you can just use
  +apt-get+ or +yum+ to install or upgrade your package.

* It reuses Heroku buildpacks. This requires that your application behave like
  a <del>Twelve Factor</del>Heroku application, including the use of STDOUT and
  STDERR for various aspects. Pkgr has some tooling that reduces the negative
  impact that this has for application configuration, but the changes are still
  unavoidably present.

Cartage offers advantages over Pkgr:

* Cartage offers plug-in based extensions. Support for remote builds
  (+cartage-remote+), uploads to S3 (+cartage-s3+), and bundler
  (+cartage-bundler+) already exist and new plug-ins are not hard to add
  (+cartage-npm+ is in development).

* Cartage offers more accessible information about *what* was built into the
  release package. There is a Rack application (+cartage-rack+) that will
  render the +release_manifest.json+ file over an API call.

* Cartage makes it easier to integrate into a workflow translated from
  Capistrano, as it essentially replaces the source control checkout stage.
  This process makes it easy to integrate into an Ansible playbook (as
  we have done at Kinetic Cafe).

== Cartage Semantic Versioning

Cartage uses a {Semantic Versioning}[http://semver.org/] scheme with one
significant change:

* When PATCH is zero (+0+), it will be omitted from version references.

Additionally, the major version will generally be reserved for plug-in
infrastructure changes.

== Community and Contributing

Cartage welcomes your contributions as described in
{Contributing.md}[https://github.com/KineticCafe/cartage/blob/master/Contributing.md].
This project, like all Kinetic Cafe {open source
projects}[https://github.com/KineticCafe], is under the Kinetic Cafe Open
Source {Code of Conduct}[https://github.com/KineticCafe/code-of-conduct].