Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 151 lines (98 sloc) 5.243 kB
dfab188 @cmer initial commit
authored
1 # Shoestrap
2
3 Shoestrap is a simple framework to bootstrap *nix machines.
4
5 It speaks Bash so there's virtually no learning curve. More importantly, you
6 won't have to learn yet another DSL. Shoestrap aims to get out of your way.
7
8 You should be able to get up and running in minutes, not hours.
9
10
11 ## What about Chef, Puppet and co.?
12
13 Chef and Puppet are great tools, but they are too complex for most use cases.
14 The learning curve for these tools is quite steep as they each have their own
15 DSL. On the other end, Shoestrap is just Bash. It does not require any
16 'Bash to config files' translation.
17
18 I believe Shoestrap is a great simple alternative to Chef or Puppet that will
19 fulfill the needs of most people.
20
21
22 ## Terminology
23
24 Shoestrap uses some of the Chef terminology since I couldn't come up with
25 better names or analogies.
26
27 ### Cookbook
28
29 A cookbook is a Bash script that executes different actions. For example,
30 it may install packages, run 'recipes'. Think of it as a dispatcher.
31
32 Cookbooks live at the root of your Shoestrap project. You can have multiple
33 cookbooks per project.
34
35 ### Recipes
36
37 Recipes are snippets of Bash code that can be executed from a Cookbook. For
38 example, you may have a recipe to install `memcached`, or a recipe to setup
39 SSH keys on the target machine. Remember, it's just Bash, so anything goes.
40
41 ### Assets
42
43 An asset is a file that will be needed by the target machine. For example,
44 a configuration file or an init script.
45
46
47 ## Helpers
48
49 Shoestrap ships with many Bash helpers functions. They can be found in
50 `helpers/default`. You do NOT need to use the built-in helper functions,
51 but they will simplify many of the most common tasks you'll need to perform.
52
53 Helper functions can be used from cookbooks or recipes. You may also pass
54 arguments to these functions.
55
56 You may add your own helper functions in `helpers/custom`.
57
58 Here are some of the most commonly used helpers:
59
60 #### `add_line`
61 Concatenate a line to a text file if it's not already there.
62
63 #### `add_user`
64 Add a user to the system.
65
66 #### `copy`
67 Copy an asset file. It first looks in the assets/{cookbook} directory and falls back to assets/default if file doesn't exist.
68
69 #### `error`
70 Write an error to the screen and halt execution.
71
72 #### `is_installed`
73 Check if an element has already been installed. Useful to prevent code from running more than once. Also see `set_installed`.
74
75 #### `log`
76 Write a line to the screen.
77
78 #### `package`
79 Install a package (ie: apt-get install {package-name}).
80
81 #### `package_update`
82 Update packages in package manager (ie: apt-get update).
83
84 #### `recipe`
85 Run a recipe. It first looks in the recipes/{cookbook} directory and falls back to recipes/default if file doesn't exist.
86
87 #### `set_installed`
88 Sets an element as 'installed'.
89
90
91 ## Getting Started
92
93 1. Clone the `shoestrap` repo to your local machine.
94 `git clone https://github.com/cmer/shoestrap.git`
95
96 2. Rename `./my-cookbook` to something a little bit more meaningful. For example,
97 you might want to call your cookbook `web` if it bootstraps a web server. Make
98 sure it is executable (`chmod +x {my-cookbook}`).
99
100 3. Specify actions to take in the cookbook. For example, which recipes to run, which
101 packages to install or which user(s) to add. For example: `recipe 'nginx'`.
102
103 4. Create a recipe file under `recipes/default`. For example: `recipes/default/nginx`. The recipe
104 is the code to execute. In our example, it would be the code to run to install `nginx`.
105
106 5. Add assets (if needed) under `assets/default/{recipe}`. For example: `assets/default/nginx/nginx.conf`.
107
108 6. Upload your project to the target machine. You can use `scp`, Capistrano, Git or whatever you feel
109 comfortable with.
110
111 7. Run your cookbook from the target machine. For example: `sudo ./web`.
112
113
114 ## Example
115
116 You can see a sample project at http://github.com/cmer/shoestrap-example
117
118 Browse the source code, it's the best way to familiarize yourself with Shoestrap. It's also a great starting
119 point for your own Shoestrap project.
120
121
122 ## Example: Directory Structure of a Shoestrap Project
123
124 [assets]
125 [default] # Assets to be used by default
126 [recipe1] # Assets for 'recipe1'.
127 foo.conf
128 bar.conf
129 [cookbook1] # Assets for 'cookbook1'. If asset cannot be found here, fallback is 'default'
130 [recipe1] # Assets for 'recipe1' when executed from 'cookbook1'. Overrides anything in [default].
131 foo.conf
132 [helpers]
133 custom # Your custom Bash functions and helpers
134 default # Shoestrap's default helpers
135 initialize # Initialize script.
136 [recipes]
137 [default] # Recipes to be used by default
138 recipe1
139 recipe2
140 recipe3
141 [cookbook1] # Recipes for 'cookbook1'. Overrides anything in [default].
142 recipe1
143 cookbook1 # The cookbook script itself. This is your point of entry to Shoestrap
144
145
146 ## Compatibility
147
148 Shoestrap has only been tested with Ubuntu Oneiric 11.10 but should work with any/most Unix-like
149 operating systems. My goal is to support Ubuntu/Debian, CentOS/Red Hat and Mac OS X. I will need
150 help from the community to achieve this, however.
Something went wrong with that request. Please try again.