pups

Simple YAML--based bootstrapper

Installation

Add this line to your application's Gemfile:

gem 'pups'

And then execute:

$ bundle

Or install it yourself as:

$ gem install pups

Usage

pups is a small library that allows you to automate the process of creating Unix images.

Usage: pups [options] [FILE|--stdin]
        --stdin                      Read input from stdin.
        --quiet                      Don't print any logs.
        --ignore <elements>          Ignore specific configuration elements, multiple elements can be provided (comma-delimited).
        --tags <elements>            Only run tagged commands.
        --skip-tags <elements>       Run all but listed tagged commands.
                                     Useful if you want to skip over config in a pups execution.
                                     e.g. `--ignore env,params`.
        --gen-docker-run-args        Output arguments from the pups configuration for input into a docker run command. All other pups config is ignored.
    -h, --help

pups requires input either via a stdin stream or a filename. The entire input is parsed prior to any templating or command execution.

Example:

# somefile.yaml
params:
  hello: hello world

run:
  - exec: /bin/bash -c 'echo $hello >> hello'

Running: pups somefile.yaml will execute the shell script resulting in a file called "hello" with the contents "hello world".

Features

Filtering run commands by tags

The --tags and --skip-tags argument allows pups to target a subset of commands listed in the somefile.yaml. To use this, you may tag your commands in the runblock. --tags will only run commands when commands have a matching tag. --skip-tags will skip when commands have a matching tag.

Note, hooks from tagged commands will be present or absent depending on if the tag is filtered out or not as well. A command filtered out by targeting tag will also filter out the command's before_ and after_ hooks.

Example:

# somefile.yaml

run:
  - exec:
      cmd: /bin/bash -c 'echo hello >> hello'
      tag: sometag
  - exec:
      cmd: /bin/bash -c 'echo hi >> hello'
      tag: anothertag
  - exec:
      cmd: /bin/bash -c 'echo goodbye >> hello'
      tag: thirdtag

Running: pups --tags="sometag,anothertag" somefile.yaml will not run the echo goodbye statement.

Running: pups --skip-tags="sometag,anothertag" somefile.yaml will ONLY run the echo goodbye statement.

Docker run argument generation

The --gen-docker-run-args argument is used to make pups output arguments be in the format of docker run <arguments output>. Specifically, pups will take any env, volume, labels, links, and expose configuration, and coerce that into the format expected by docker run. This can be useful when pups is being used to configure an image (e.g. by executing a series of commands) that is then going to be run as a container. That way, the runtime and image configuration can be specified within the same yaml files.

Environment Variables

By default, pups automatically imports your environment variables and includes them as params.

# In bash
export SECRET_KEY="secret value"

# In somefile.yaml
run:
  - exec: echo "$SECRET_KEY"

Running the above code with pups will produce secret value.

Execution

Run multiple commands in one path:

run:
  - exec:
      cd: some/path
      cmd:
        - echo 1
        - echo 2

Run commands in the background (for services etc)

run:
  - exec:
      cmd: /usr/bin/sshd
      background: true

Suppress exceptions on certain commands

run:
  - exec:
      cmd: /test
      raise_on_fail: false

Replacements:

run:
  - replace:
      filename: "/etc/redis/redis.conf"
      from: /^pidfile.*$/
      to: ""

Will substitute the regex with blank, removing the pidfile line

run:
  - replace:
      filename: "/etc/nginx/conf.d/discourse.conf"
      from: /upstream[^\}]+\}/m
      to: "upstream discourse {
        server 127.0.0.1:3000;
      }"

Additional params:

Global replace (as opposed to first match)

global: true

Hooks

Execute commands before and after a specific command by defining a hook.

run
  - exec:
      hook: hello
      cmd: echo 'Hello'

hooks:
  before_hello:
    - exec:
        cmd: echo 'Starting...'

  after_hello:
    - exec:
        cmd: echo 'World'

Merge yaml files

home: /var/www/my_app
params:
  database_yml:
    production:
      username: discourse
      password: foo

run:
  - merge: $home/config/database.yml $database_yml

Will merge the yaml file with the inline contents.

A common environment

Environment variables can be specified under the env key, which will be included in the environment for the template.

env:
  MY_ENV: "a couple of words"
run:
  - exec: echo $MY_ENV > tmpfile

tmpfile will contain a couple of words.

You can also specify variables to be templated within the environment, such as:

env:
  greeting: "hello, {{location}}!"
env_template:
  location: world

In this example, the greeting environment variable will be set to hello, world! during initialisation as the {{location}} variable will be templated as world. Pups will also look in the environment itself at runtime for template variables, prefixed with env_template_<variable name>. Note that strings should be quoted to prevent YAML from parsing the { } characters.

All commands executed will inherit the environment once parsing and variable interpolation has been completed.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request