Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/strapsh/strap

Bootstrap a machine with one command!
https://github.com/strapsh/strap

ansible ansible-playbook ansible-role bootstrap convergence linux machine macos

Last synced: about 1 month ago
JSON representation

Bootstrap a machine with one command!

Awesome Lists containing this project

README 

        
# 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](https://docs.ansible.com/ansible/latest/index.html) 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

1. Doesn't interfere with system or user-specific Ansible installations if there are any.

1. 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](https://docs.ansible.com/ansible/latest/user_guide/playbooks.html) or 

[roles](https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html) 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:



```bash

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:



```bash

me@myhost:~$ strap --help

strap version 0.3.6

usage: strap [options...]  [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 ' 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:



```bash

.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](https://galaxy.ansible.com/docs/using/installing.html#installing-multiple-roles-from-a-file),

    those requirements will be automatically downloaded first using the

    [ansible-galaxy command](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html).

    

    **Strap enhancement**: Strap has a really nice feature that enables [transitive role dependency downloads](https://github.com/lhazlewood/ansible-galaxy-install):  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.



1. 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.



```bash

strap run [--playbook|--role] 

```



where `` 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:



```bash

strap run --role geerlinguy.java

```



or



```bash

strap run --playbook example/foo

```