Skip to content

Latest commit

 

History

History
158 lines (115 loc) · 5.22 KB

README.rdoc

File metadata and controls

158 lines (115 loc) · 5.22 KB
Raw

cartage-rack by Kinetic Cafe ↑

code

github.com/KineticCafe/cartage-rack/

issues

github.com/KineticCafe/cartage-rack/issues

continuous integration

<img src=“https://travis-ci.org/KineticCafe/cartage-rack.png” />

Description ↑

This release is the last version of cartage-rack. It will be replaced with a different tool in the future, but this release will allow installation in modern Ruby versions.

cartage-rack is a plug-in for cartage to provide a Rack application that reports on release metadata.

Cartage provides a repeatable means to create a package for a Rails application that can be used in deployment with a configuration tool like Ansible, Chef, Puppet, or Salt. The package is created with its dependencies bundled in vendor/bundle, so it can be deployed in environments with strict access control rules and without requiring development tool access.

Synopsis ↑

cartage-rack provides a generator method that instantiates a Rack application that reports on release metadata, which will assist in verifying application deploys.

To add the default generator to a Rails application, simply mount it in config/routes.rb:

require 'cartage/rack'

Rails.application.routes.draw do
  get '/release' => Cartage::Rack::Simple(Rails.root)
end

To map it in a normal Rack application in config.ru:

require 'cartage/rack'
map('/release') do
  run Cartage::Rack::Simple(Dir.pwd)
end

Once mounted, it can then be queried easily:

% rails start
% curl localhost:3000/release
development: (git) main
% curl localhost:3000/release.json | jq .
{
  "env" : "development",
  "release_hashref" : "(git) main"
}

Metadata ↑

The core of cartage-rack is Cartage::Rack::Metadata, which collects data from release-metadata.json, release_hashref, or the runtime environment (if Cartage::Rack.require_metadata is false). You may instantiate the class yourself if you wish to have a different sort of report for the release.

Metadata Reporters ↑

There are two Rack applications provided in cartage-rack 2.0 to report on release metadata. Metadata is pulled from release-metadata.json, release_hashref, or the current environment (which allows Cartage::Rack verification in development).

When reading release_hashref, the first line is the hashref of the release; a second line, if present, is the Cartage timestamp of the release (an integer value of the form YYYYmmddHHMMSS).

If a metadata file (release-metadata.json or release_hashref) exists, it will be read on application creation and cached for the lifetime of the Rack application. cartage-rack may be configured to throw an exception if a metadata file cannot be found:

Cartage::Rack.require_metadata false

All reporters support JSON and plain text formats.

Cartage::Rack ↑

A full metadata reporter. This reporter may include information that is considered private (including the source repository URL), so it is only recommended for use on protected endpoints. The default report format is JSON.

The data returned is what is recorded in release-metadata.json, plus the name of the environment.

{
  "env": {
    "name": "production",
  },
  "package": {
    "name": "package-name",
    "repo": {
      "type": "git",
      "url": "git:[email protected]/KineticCafe/cartage-rack.git"
    },
    hashref: "decafbad",
    timestamp: "19851027024200"
  }
}

Mount this reporter with Cartage::Rack(Rails.root). The data may be filtered out by providing a block to Cartage::Rack() which modifies the metadata in place.

Cartage::Rack(Rails.root) do |metadata|
  unless Rails.env.development?
    # Remove the repo data before returning
    metadata[:package].delete(:repo)
  end
end

Cartage::Rack::Simple ↑

A simplified metadata reporter, including only the information that was provided in cartage-rack 1.x (the environment, the hashref, and optionally a timestamp). The default report format is plain text.

Mount this reporter with Cartage::Rack::Simple(Rails.root). For backwards compatibility, this reporter may also be mounted with Cartage::Rack.mount(Rails.root). The Simple reporter does not support filtering.

Install ↑

Add cartage-rack to your Gemfile:

gem 'cartage-rack', '~> 2.0'

Or manually install:

% gem install cartage-rack

cartage-rack should be in the main section of your Gemfile, unlike Cartage itself.

cartage-rack Semantic Versioning ↑

cartage-rack uses a Semantic Versioning scheme with one change:

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

cartage-rack will generally track cartage for major versions to ensure plugin API compatibility.

Community and Contributing ↑

cartage-rack welcomes your contributions as described in Contributing.md. This project, like all Kinetic Cafe open source projects, is under the Kinetic Cafe Open Source Code of Conduct.