cartage

= 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 tar cfj. (The compression method is configurable, but defaults to +bzip2+.)
• Cartage only understands +git+, which is used for creating release_manifest.jsons, +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 Twelve FactorHeroku 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].