README.md

menagerie

Simple release management tool for controlling versioned artifacts

Usage

Menagerie manages Collections of Releases, as well as the Artifacts that are used in those Releases. A quick tl;dr:

• Artifact -- a downloaded asset: a compiled Linux kernel, the python package, a picture of your cat, etc
• Release -- a set of Artifacts at specific versions: "Python 2.7, Linux kernel 3.18.1, and the 3rd revision of your cat's picture"
• Collection - all the Releases currently downloaded, including the "latest" release as well any previous releases

Also relevant are "Orphans"; these are artifacts that are not needed by any currently tracked releases.

The gem provides a simple script that will print out the contents of an existing collection:

Release: 0
  initrd: 0.0.36
  kernel: 3.19-rc7_1
  rootfs: 0.0.73
Release: 1
  initrd: 0.0.36
  kernel: 3.19-rc7_1
  rootfs: 0.0.71
Release: 2
  initrd: 0.0.36
  kernel: 3.19-rc6_1
  rootfs: 0.0.69

Orphans:
  kernel
    3.19-rc5_1

To start using Menagerie, create a collection:

require 'menagerie'
my_collection = Menagerie.new

Initially, your collection has no releases. To add a release, call .add_release with the details for the artifacts you want to install:

new_artifacts = [
    {
        name: 'kernel',
        version: '3.19-rc7_1',
        url: 'https://github.com/dock0/kernel/releases/download/3.19-rc7_1/vmlinuz'
    },
    {
        name: 'initrd',
        version: '0.0.36',
        url: 'https://github.com/dock0/initrd/releases/download/0.0.36/initrd.img'
    }
]
my_collection.add_release(new_artifacts)

This will download the new artifacts into ./artifacts and symlink them into ./releases/0, with ./latest linked to ./releases/0:

# tree
.
├── artifacts
│   ├── initrd
│   │   └── 0.0.36
│   └── kernel
│       └── 3.19-rc7_1
├── latest -> releases/0
└── releases
    └── 0
        ├── initrd -> ../../artifacts/initrd/0.0.36
        └── kernel -> ../../artifacts/kernel/3.19-rc7_1

Now lets say you update your kernel package, so you want to make a new releaes with your updated 3.19_1 kernel:

new_artifacts = [
    {
        name: 'kernel',
        version: '3.19_1',
        url: 'https://github.com/dock0/kernel/releases/download/3.19-rc7_1/vmlinuz'
    },
    {
        name: 'initrd',
        version: '0.0.36',
        url: 'https://github.com/dock0/initrd/releases/download/0.0.36/initrd.img'
    }
]
my_collection.add_release(new_artifacts)

Menagerie will rotate the '0' release to '1', download the new kernel, and link the correct assets into '0'. Note that it doesn't download a new copy of the initrd asset, as the version didn't change:

# tree
.
├── artifacts
│   ├── initrd
│   │   └── 0.0.36
│   └── kernel
│       ├── 3.19_1
│       └── 3.19-rc7_1
├── latest -> releases/0
└── releases
    ├── 0
    │   ├── initrd -> ../../artifacts/initrd/0.0.36
    │   └── kernel -> ../../artifacts/kernel/3.19_1
    └── 1
        ├── initrd -> ../../artifacts/initrd/0.0.36
        └── kernel -> ../../artifacts/kernel/3.19-rc7_1

Menagerie will retain 5 old releases by default (for a total of 6, including the current version). Older releases will be removed, and orphaned artifacts (those no longer used in any releases) will be deleted. To change the retention or disable reaping of orphans, pass the desired options to Menagerie when you create your collection:

larger_collection = Menagerie.new(options: { retention: 20 }) # this will retain 20 old releases

permanent_collection = Menagerie.new(options: { reap: false }) # this will not reap orphaned artifacts

By default, Menagerie will log to STDOUT when it manipulates releases and artifacts. You can disable this via the verbose option:

quiet_collection = Menagerie.new(options: { verbose: false })

You can also override the paths used for artifacts/releases and the "latest" symlink, via the paths parameter:

custom_paths = {
    artifacts: '/srv/artifacts',
    releases: '/opt/releases',
    latest: '/var/latest_release'
}

my_collection = Menagerie.new(paths: custom_paths)

Installation

gem install menagerie

License

menagerie is released under the MIT License. See the bundled LICENSE file for details.