A simple alternative to Chef and Puppet to bootstrap *nix machines.
Go to file
2024-06-24 11:52:00 -07:00
assets/default Upate ghpr to accept a name field 2024-06-24 11:52:00 -07:00
helpers Shellcheck fixes 2023-03-08 15:03:28 -08:00
recipes Run linters 2024-06-13 12:59:23 -07:00
.gitignore Ignore temp dir 2021-07-25 20:36:37 -07:00
.pre-commit-config.yaml Linting cleanup 2023-02-24 14:36:51 -08:00
ansible-cookbook Add linter and fix all linting errors and warnings 2019-11-21 12:07:37 -08:00
docker-devenv.sh Add Dockerfile to run dev env in an image 2021-06-09 17:07:15 -07:00
Dockerfile Add Dockerfile to run dev env in an image 2021-06-09 17:07:15 -07:00
hass Add hass cookbook 2021-09-07 09:03:53 -07:00
mac-setup Add packages to mac-setup 2024-06-17 09:49:13 -07:00
main-cookbook Avoid reinstall of golang 2023-03-08 14:59:57 -08:00
Makefile Add Dockerfile to run dev env in an image 2021-06-09 17:07:15 -07:00
minimal Clean up scripts 2022-04-05 10:27:56 -07:00
no-sudo Add linter and fix all linting errors and warnings 2019-11-21 12:07:37 -08:00
README.md initial commit 2012-03-21 16:05:28 -04:00
test-cookbook Add linter and fix all linting errors and warnings 2019-11-21 12:07:37 -08:00
TODO.md Add linter and fix all linting errors and warnings 2019-11-21 12:07:37 -08:00


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.


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


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


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


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:


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


Add a user to the system.


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


Write an error to the screen and halt execution.


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


Write a line to the screen.


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


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


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


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.


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

  [default]            # Assets to be used by default
    [recipe1]          # Assets for 'recipe1'.
  [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].
  custom               # Your custom Bash functions and helpers
  default              # Shoestrap's default helpers
  initialize           # Initialize script.
  [default]            # Recipes to be used by default
  [cookbook1]          # Recipes for 'cookbook1'. Overrides anything in [default].
cookbook1              # The cookbook script itself. This is your point of entry to Shoestrap


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.