krishkau / strap

Bootstrap a machine with one command!

Strap: Bootstrap Your Machine with One Command

strap is a simple shell command designed to do one thing:

Strap will take your machine from a starting state (for example, right after you buy it or receive it from your employer) and install and configure everything you want on your machine in a single command, in one shot. Run strap and you can rest assured that your machine will have your favorite command line tools, system defaults, gui applications, and development tools installed and ready to go.

Strap was initially created to help newly-hired software engineers get up and running and productive in minutes after they receive their machine instead of the hours or days it usually takes. But Strap isn't limited to software engineering needs - anyone can use Strap to install what they want - graphics software, office suites, web browsers, whatever.

Overview

At the highest level:

strap is a shell command that does the bare minimum necessary to ensure Ansible is available and then immediately runs ansible to setup (aka 'converge') the local machine.

In this sense, we're not reinventing the wheel - there are plenty of machine convergence tools out there already, and it's best to just use one of them, like Ansible.

The only difference with strap is that strap covers the 'last mile' to obtain Ansible in a generic way that:

1. Ensures anyone can run it without knowing what Ansible is
2. Doesn't interfere with system or user-specific Ansible installations if there are any.
3. Ensures that the fastest way to remove it is to just delete the ~/.strap directory.

As soon as Ansible is available, strap immediately delegates to it, automatically running one or more Ansible playbooks or roles on the local machine.

And we think that's pretty great - installing Ansible or Python is not always a trivial exercise, and we wanted to ensure things 'just work', even if someone has never even heard of Python or Ansible. It's so easy to use, anyone can use it - from setting up a machine, or just installing things for a particular project, etc.

Installation

To install strap, run the following on the command line:

curl -fsSL https://raw.githubusercontent.com/strapsh/strap/master/install | bash
source "$HOME/.strap/releases/current/etc/straprc"

Usage

Strap is a command line tool. Assuming the strap installation's bin directory is in your $PATH as shown in the installation instructions above, you can just type strap --help and see what happens:

me@myhost:~$ strap --help
strap version 0.3.6
usage: strap [options...] <command> [command_options...]
 
commands:
   help        Display help for a command
   run         Runs strap to ensure your machine is configured
   version     Display the version of strap
 
See `strap help <command>' for information on a specific command.
For full documentation, see: https://github.com/strapsh/strap

The strap command itself is quite simple - it basically loads some common environment settings and that's pretty much it. From there, it delegates most functionality to sub-commands, very similar to how the git command-line tool works.

Strap Run

strap run ensures ansible is available and then immediately runs ansible to converge the local machine to a desired state.

This means that, even though one or more people can use run strap without knowing anything about ansible (a great benefit to teams), at least one person needs to know how to write ansible "packages" that will be used during a strap run. These "packages" in ansible's terminology are called playbooks and roles.

Once a playbook or role is identified or available locally, strap makes running them that much easier. You can run ansible playbooks and roles based on the directory where strap is run or by explicitly referencing them by id.

Working Directory

If you just type strap run (without any arguments) in a working directory, and that directory has an ansible playbook available via the relative path:

.strap/ansible/playbooks/default/main.yml

then strap will run that playbook automatically.

It does the following steps in order:

1. If a .strap/ansible/playbooks/default/meta/requirements.yml file exists that lists the playbook's role dependencies, those requirements will be automatically downloaded first using the ansible-galaxy command.

   Strap enhancement: Strap has a really nice feature that enables transitive role dependency downloads: if a dependency role is downloaded, and that role in turn has a meta/requirements.yml file, Strap will automatically transitively download those dependencies that don't yet exist. It will continue to walk the dependency tree, downloading dependencies as necessary until all dependencies are resolved.

   Core ansible does not provide transitive resolution, but Strap does.

2. Strap will call the ansible-playbook command with the discovered playbook file targeting localhost/127.0.0.1.

Specific Roles or Playbooks

If the working directory does not have a .strap/ansible/playbooks/default/main.yml playbook file, then you must specify one or more roles or playbooks using the --playbook or --role arguments, i.e.

strap run [--playbook|--role] <id>

where <id> is an Ansible Galaxy identifier (i.e. username.rolename) or a GitHub url fragment that identifies the role or playbook's git repository, (i.e. username/repo).

For example:

strap run --role geerlinguy.java

or

strap run --playbook example/foo