mirror of
https://github.com/ViViDboarder/shoestrap.git
synced 2024-11-01 00:16:28 +00:00
151 lines
5.1 KiB
Markdown
151 lines
5.1 KiB
Markdown
# 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.
|