Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kineticcafe/cartage-rack

Show the release_hashref file from a Cartage package
https://github.com/kineticcafe/cartage-rack

deprecated packager rack ruby

Last synced: 2 months ago
JSON representation

Show the release_hashref file from a Cartage package

Awesome Lists containing this project

README 

        
= cartage-rack by Kinetic Cafe



code :: https://github.com/KineticCafe/cartage-rack/

issues :: https://github.com/KineticCafe/cartage-rack/issues

continuous integration :: {}[https://travis-ci.org/KineticCafe/cartage-rack]



== 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}[https://github.com/KineticCafe/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}[http://semver.org/] 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}[https://github.com/KineticCafe/cartage-rack/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].