shoestrap/README.md

# Shoestrap

Shoestrap is a simple framework to bootstrap *nix machines.

It speaks Bash so there's virtually no learning curve. More importantly, you
won't have to learn yet another DSL. Shoestrap aims to get out of your way.

You should be able to get up and running in minutes, not hours.


## What about Chef, Puppet and co.?

Chef and Puppet are great tools, but they are too complex for most use cases.
The learning curve for these tools is quite steep as they each have their own
DSL. On the other end, Shoestrap is just Bash. It does not require any
'Bash to config files' translation.

I believe Shoestrap is a great simple alternative to Chef or Puppet that will
fulfill the needs of most people.


## Terminology

Shoestrap uses some of the Chef terminology since I couldn't come up with
better names or analogies.

### Cookbook

A cookbook is a Bash script that executes different actions. For example,
it may install packages, run 'recipes'. Think of it as a dispatcher.

Cookbooks live at the root of your Shoestrap project. You can have multiple
cookbooks per project.

### Recipes

Recipes are snippets of Bash code that can be executed from a Cookbook. For
example, you may have a recipe to install `memcached`, or a recipe to setup
SSH keys on the target machine. Remember, it's just Bash, so anything goes.

### Assets

An asset is a file that will be needed by the target machine. For example,
a configuration file or an init script.


## Helpers

Shoestrap ships with many Bash helpers functions. They can be found in
`helpers/default`. You do NOT need to use the built-in helper functions,
but they will simplify many of the most common tasks you'll need to perform.

Helper functions can be used from cookbooks or recipes. You may also pass
arguments to these functions.

You may add your own helper functions in `helpers/custom`.

Here are some of the most commonly used helpers:

#### `add_line`
Concatenate a line to a text file if it's not already there.

#### `add_user`
Add a user to the system.

#### `copy`
Copy an asset file. It first looks in the assets/{cookbook} directory and falls back to assets/default if file doesn't exist.

#### `error`
Write an error to the screen and halt execution.

#### `is_installed`
Check if an element has already been installed. Useful to prevent code from running more than once. Also see `set_installed`.

#### `log`
Write a line to the screen.

#### `package`
Install a package (ie: apt-get install {package-name}).

#### `package_update`
Update packages in package manager (ie: apt-get update).

#### `recipe`
Run a recipe. It first looks in the recipes/{cookbook} directory and falls back to recipes/default if file doesn't exist.

#### `set_installed`
Sets an element as 'installed'.


## Getting Started

1.  Clone the `shoestrap` repo to your local machine.
    `git clone https://github.com/cmer/shoestrap.git`

2.  Rename `./my-cookbook` to something a little bit more meaningful. For example,
    you might want to call your cookbook `web` if it bootstraps a web server. Make
    sure it is executable (`chmod +x {my-cookbook}`).

3.  Specify actions to take in the cookbook. For example, which recipes to run, which
    packages to install or which user(s) to add. For example: `recipe 'nginx'`.

4.  Create a recipe file under `recipes/default`. For example: `recipes/default/nginx`. The recipe
    is the code to execute. In our example, it would be the code to run to install `nginx`.

5.  Add assets (if needed) under `assets/default/{recipe}`. For example: `assets/default/nginx/nginx.conf`.

6.  Upload your project to the target machine. You can use `scp`, Capistrano, Git or whatever you feel
    comfortable with.

7.  Run your cookbook from the target machine. For example: `sudo ./web`.


## Example

You can see a sample project at http://github.com/cmer/shoestrap-example

Browse the source code, it's the best way to familiarize yourself with Shoestrap. It's also a great starting
point for your own Shoestrap project.


## Example: Directory Structure of a Shoestrap Project

    [assets]
      [default]            # Assets to be used by default
        [recipe1]          # Assets for 'recipe1'.
          foo.conf
          bar.conf
      [cookbook1]          # Assets for 'cookbook1'. If asset cannot be found here, fallback is 'default'
        [recipe1]          # Assets for 'recipe1' when executed from 'cookbook1'. Overrides anything in [default].
          foo.conf
    [helpers]
      custom               # Your custom Bash functions and helpers
      default              # Shoestrap's default helpers
      initialize           # Initialize script.
    [recipes]
      [default]            # Recipes to be used by default
        recipe1
        recipe2
        recipe3
      [cookbook1]          # Recipes for 'cookbook1'. Overrides anything in [default].
        recipe1
    cookbook1              # The cookbook script itself. This is your point of entry to Shoestrap


## Compatibility

Shoestrap has only been tested with Ubuntu Oneiric 11.10 but should work with any/most Unix-like
operating systems. My goal is to support Ubuntu/Debian, CentOS/Red Hat and Mac OS X. I will need
help from the community to achieve this, however.