Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 262 lines (165 sloc) 12.106 kB
ddfb863 @jtimberman Custom bootstrap for quickstart, installs older working rubygems for …
jtimberman authored
1 This guide describes how to build a Ruby On Rails application stack using Chef cookbooks available from the [Cookbooks Community Site](http://cookbooks.opscode.com) and Hosted Chef. It assumes you followed the [Getting Started Guide](http://help.opscode.com/faqs/start/how-to-get-started) and have Chef installed.
d07aee0 @jtimberman re-add cookbooks dir w/ README
jtimberman authored
2
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
3 *This guide uses Ubuntu 10.04 on Amazon AWS EC2 with Chef 0.10.0.*
ef2bd33 @jtimberman Add top-level readme.
jtimberman authored
4
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
5 ***Note:** At this time, the steps described above have only been tested on the identified platform(s). Opscode has not researched and does not support alternative steps that may lead to successful completion on other platforms. Platform(s) supported by this guide may change over time, so please do check back for updates. If you'd like to undertake this guide on an alternate platform, you may desire to turn to open source community resources for support assistance.*
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
6
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
7 You can watch a short screencast of this guide [here](http://blip.tv/file/4703126).
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
8
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
9 <embed src="http://blip.tv/play/hMAggqCWHwA" type="application/x-shockwave-flash" width="600" height="480" allowscriptaccess="always" allowfullscreen="true"></embed>
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
10
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
11 At the end of this guide, you'll have four total Ubuntu 10.04 systems running in Amazon EC2.
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
12
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
13 - 1 haproxy load balancer.
14 - 2 Ruby on Rails application servers.
15 - 1 MySQL database server.
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
16
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
17 The Ruby on Rails application used in this guide is [Radiant CMS](http://radiantcms.org/).
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
18
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
19 We're going to reuse a number of cookbooks from the [Cookbooks Community Site](http://cookbooks.opscode.com) to build the environment. For example, the source code lives in **git**, so that cookbook will ensure Git is available. The load balancer is **haproxy** because it is very simple to deploy and configure, and we use a recipe that automatically discovers the Rails application systems. The heavy lifting is handled by recipes in the **application** and **database** cookbooks. Finally, as we're deploying Radiant, we'll get some help from the **radiant** cookbook.
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
20
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
21 If you don't already have an account with Amazon AWS, go to [Amazon Web Sevices](http://aws.amazon.com/) and click "Sign up". You'll need the access and secret access key credentials from the sign-up later.
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
22
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
23 Environment Setup
24 ----
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
25
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
26 First, let's configure the local workstation.
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
27
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
28 ### Shell Environment
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
29
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
30 Obtain the repository used for this guide. It contains all the components required. Use git:
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
31
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
32 git clone git://github.com/opscode/rails-quick-start.git
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
33
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
34 ### Chef and Knife
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
35
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
36 *Ubuntu/Debian users*: Install XML2 and XLST development headers on your system:
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
37
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
38 sudo apt-get install libxml2-dev libxslt-dev
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
39
deac7e4 @metaxis knife-ec2 gem fix
metaxis authored
40 *All Users*: You'll need some additional gems for Knife to launch instances in Amazon EC2:
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
41
deac7e4 @metaxis knife-ec2 gem fix
metaxis authored
42 sudo gem install knife-ec2
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
43
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
44 As part of the [Getting Started Guide](help.opscode.com/faqs/start/how-to-get-started), you cloned a chef-repo and copied the Knife configuration file (knife.rb), validation certificate (ORGNAME-validator.pem) and user certificate (USERNAME.pem) to **~/chef-repo/.chef/**. Copy these files to the new rails-quick-start repository. You can also re-download the Knife configuration file for your [Organization from the Management Console](http://help.opscode.com/faqs/start/user-environment).
e7ca82d @jtimberman update readmes for info on cookbook_path and knife locations
jtimberman authored
45
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
46 mkdir ~/rails-quick-start/.chef
47 cp ~/chef-repo/.chef/knife.rb ~/rails-quick-start/.chef
48 cp ~/chef-repo/.chef/USERNAME.pem ~/rails-quick-start/.chef
49 cp ~/chef-repo/.chef/ORGNAME-validator.pem ~/rails-quick-start/.chef
11c15de @jtimberman Clarify / update documentation to be in line with new wiki page.
jtimberman authored
50
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
51 Add the Amazon AWS credentials to the Knife configuration file.
52
53 vi ~/rails-quick-start/.chef/knife.rb
54
55 Add the following two lines to the end:
56
57 knife[:aws_access_key_id] = "replace with the Amazon Access Key ID"
58 knife[:aws_secret_access_key] = "replace with the Amazon Secret Access Key ID"
59
60 Once the rails-quick-start and knife configuration is in place, we'll work from this directory.
61
62 cd rails-quick-start
63
64 ### Amazon AWS EC2
65
66 In addition to the credentials, two additional things need to be configured in the AWS account.
67
68 Configure the default [security group](http://docs.amazonwebservices.com/AWSEC2/latest/DeveloperGuide/index.html?using-network-security.html) to allow incoming connections for the following ports.
69
70 * 22 - ssh
71 * 80 - haproxy load balancer
72 * 22002 - haproxy administrative interface
73 * 8080 - unicorn Rails application
74
75 Add these to the default security group for the account using the AWS Console.
76
77 1. Sign into the [Amazon AWS Console](https://console.aws.amazon.com/s3/home).
78 2. Click on the "Amazon EC2" tab at the top.
79 3. Click on "Security Groups" in the left sidebar of the AWS Console.
80 4. Select the "Default" group in the main pane.
81 5. Enter the values shown for each of the ports required. Use "Custom" in the drop-down for 22002 and 8080.
82 ![aws-management-console](http://img.skitch.com/20101104-qyy612rgcrr9k24ca29qarehc9.jpg)
83
84 Create an [SSH Key Pair](http://docs.amazonwebservices.com/AWSEC2/latest/DeveloperGuide/index.html?using-credentials.html#using-credentials-keypair) and save the private key in **~/.ssh**.
85
86 1. In the AWS Console, click on "Key Pairs" in the left sidebar.
87 2. Click on "Create Keypair" at the top of the main pane.
88 3. Give the keypair a name like "rails-quick-start".
89 4. The keypair will be downloaded automatically by the browser and saved to the default Downloads location.
90 5. Move the rails-quick-start.pem file from the default Downloads location to **~/.ssh** and change permissions so that only you can read the file. For example,
91
92 mv ~/Downloads/rails-quick-start.pem ~/.ssh
93 chmod 600 ~/.ssh/rails-quick-start.pem
94
95 Acquire Cookbooks
96 ----
97
98 The rails-quick-start has all the cookbooks we need for this guide. They were downloaded along with their dependencies from the cookbooks site using Knife. These are in the **cookbooks/** directory.
99
100 apt
101 git
102 application
103 database
104 radiant
105 haproxy
106
ddfb863 @jtimberman Custom bootstrap for quickstart, installs older working rubygems for …
jtimberman authored
107 Upload all the cookbooks to Hosted Chef.
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
108
109 knife cookbook upload -a
110
111 Server Roles
112 ------------
113
114 All the required roles have been created in the rails-quick-start repository. They are in the **roles/** directory.
115
116 base.rb
117 radiant_database_master.rb
118 radiant.rb
119 radiant_run_migrations.rb
120 radiant_load_balancer.rb
121
ddfb863 @jtimberman Custom bootstrap for quickstart, installs older working rubygems for …
jtimberman authored
122 Upload all the roles to Hosted Chef.
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
123
124 rake roles
125
126 Data Bag Item
127 ----
128
129 The rails-quick-start repository contains a data bag item that has all the information required to deploy and configure the Radiant application from source using the recipes in the **application** and **database** cookbooks.
130
ddfb863 @jtimberman Custom bootstrap for quickstart, installs older working rubygems for …
jtimberman authored
131 The data bag name is **apps** and the item name is **radiant**. Upload this to Hosted Chef.
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
132
133 knife data bag create apps
134 knife data bag from file apps radiant.json
135
136 Decision Time
137 ====
138
139 It is time for you to decide whether you want a single instance running Radiant, or a few instances as a small infrastructure.
140
141 In either case, we're going to use m1.small instances with the 32 bit Ubuntu 10.04 image provided [by Canonical](http://uec-images.ubuntu.com/releases/10.04/release-20101228/). The identifier is **ami-88f504e1** for the AMI in us-east-1 with instance storage that we will use in this guide. We'll show you the **knife ec2 server create** sub-command to launch instances.
142
143 This command will:
144
145 * Launch a server on EC2.
ddfb863 @jtimberman Custom bootstrap for quickstart, installs older working rubygems for …
jtimberman authored
146 * Connect it to Hosted Chef.
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
147 * Configure the system with Chef.
148
149 See the appropriate section below for instruction on launching a single instance, or launching the multi-system infrastructure.
150
151 Launch Single Instance
152 ----
153
154 Launch the entire stack on a single instance.
155
156 knife ec2 server create -G default -I ami-7000f019 -f m1.small \
ddfb863 @jtimberman Custom bootstrap for quickstart, installs older working rubygems for …
jtimberman authored
157 -S rails-quick-start -i ~/.ssh/rails-quick-start.pem -x ubuntu -d ubuntu10.04-gems-qs \
6146f96 @schisamo add lb to the single node stack
schisamo authored
158 -r 'role[base],role[radiant_database_master],role[radiant],role[radiant_run_migrations],recipe[radiant::db_bootstrap],role[radiant_load_balancer]'
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
159
160 Once complete, the instance will be running MySQL and Radiant under Unicorn. With only one system, a load balancer is unnecessary.
161
162 Launch Multi-instance Infrastructure
163 ----
164
165 We will launch one database server, two application servers and one load balancer. One of the application server instances will include the role for running migrations as discussed before.
166
167 First, launch the database instance.
168
169 knife ec2 server create -G default -I ami-7000f019 -f m1.small \
ddfb863 @jtimberman Custom bootstrap for quickstart, installs older working rubygems for …
jtimberman authored
170 -S rails-quick-start -i ~/.ssh/rails-quick-start.pem -x ubuntu -d ubuntu10.04-gems-qs \
74bf9ea @schisamo move from app_environment to chef_environment; use _default as default
schisamo authored
171 -r 'role[base],role[radiant_database_master]'
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
172
173 Once the database master is up, launch one node that will run database migration and set up the database with default data.
174
175 knife ec2 server create -G default -I ami-7000f019 -f m1.small \
ddfb863 @jtimberman Custom bootstrap for quickstart, installs older working rubygems for …
jtimberman authored
176 -S rails-quick-start -i ~/.ssh/rails-quick-start.pem -x ubuntu -d ubuntu10.04-gems-qs \
74bf9ea @schisamo move from app_environment to chef_environment; use _default as default
schisamo authored
177 -r 'role[base],role[radiant],role[radiant_run_migrations],recipe[radiant::db_bootstrap]'
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
178
179 Launch the second application instance w/o the **radiant_run_migrations** role or **radiant::db_bootstrap** recipe.
180
181 knife ec2 server create -G default -I ami-7000f019 -f m1.small \
ddfb863 @jtimberman Custom bootstrap for quickstart, installs older working rubygems for …
jtimberman authored
182 -S rails-quick-start -i ~/.ssh/rails-quick-start.pem -x ubuntu -d ubuntu10.04-gems-qs \
74bf9ea @schisamo move from app_environment to chef_environment; use _default as default
schisamo authored
183 -r 'role[base],role[radiant]'
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
184
185 Once the second application instance is up, launch the load balancer.
186
187 knife ec2 server create -G default -I ami-7000f019 -f m1.small \
ddfb863 @jtimberman Custom bootstrap for quickstart, installs older working rubygems for …
jtimberman authored
188 -S rails-quick-start -i ~/.ssh/rails-quick-start.pem -x ubuntu -d ubuntu10.04-gems-qs \
74bf9ea @schisamo move from app_environment to chef_environment; use _default as default
schisamo authored
189 -r 'role[base],role[radiant_load_balancer]'
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
190
191 Once complete, we'll have four instances running in EC2 with MySQL, Radiant and haproxy up and available to serve traffic.
192
193 Verification
194 ----
195
6146f96 @schisamo add lb to the single node stack
schisamo authored
196 Knife will output the fully qualified domain name of the instance when the commands complete. Navigate to the public fully qualified domain name on port 80:
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
197
198 http://ec2-xx-xxx-xx-xxx.compute-1.amazonaws.com/
199
200 The login is admin and the password is radiant.
201
6146f96 @schisamo add lb to the single node stack
schisamo authored
202 You can access the haproxy admin interface at:
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
203
204 http://ec2-xx-xxx-xx-xxx.compute-1.amazonaws.com:22002/
205
206 Appendix
207 ----
208
209 ### Database Passwords
210
211 The data bag item for Radiant contains default passwords that should certainly be changed to something stronger.
212
213 The passwords in the Radiant Data Bag Item are set to the values show below:
214
215 "mysql_root_password": {
74bf9ea @schisamo move from app_environment to chef_environment; use _default as default
schisamo authored
216 "_default": "mysql_root"
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
217 },
218 "mysql_debian_password": {
74bf9ea @schisamo move from app_environment to chef_environment; use _default as default
schisamo authored
219 "_default": "mysql_debian"
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
220 },
221 "mysql_repl_password": {
74bf9ea @schisamo move from app_environment to chef_environment; use _default as default
schisamo authored
222 "_default": "mysql_repl"
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
223 },
224
225 To change the password to something stronger, modify **mysql_root**, **mysql_debian**, **mysql_repl** values. Something like the following secure passwords:
226
227 vi data_bags/apps/radiant.json
228 "mysql_root_password": {
74bf9ea @schisamo move from app_environment to chef_environment; use _default as default
schisamo authored
229 "_default": "super_s3cur3_r00t_pw"
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
230 },
231 "mysql_debian_password": {
74bf9ea @schisamo move from app_environment to chef_environment; use _default as default
schisamo authored
232 "_default": "super_s3cur3_d3b1@n_pw"
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
233 },
234 "mysql_repl_password": {
74bf9ea @schisamo move from app_environment to chef_environment; use _default as default
schisamo authored
235 "_default": "super_s3cur3_r3pl_pw"
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
236 },
237
238 Once the entries are modified, simply load the data bag item from the json file:
239
240 knife data bag from file apps radiant.json
241
242 ### Non-EC2 Systems
243
244 For people not using Amazon EC2, other Cloud computing providers can be used. Supported by knife and fog as of this revision:
245
246 * Rackspace Cloud
247
248 See the [launch cloud instances page](http://wiki.opscode.com/display/chef/Launch+Cloud+Instances+with+Knife) on the Chef wiki for more information about using Knife to launch these instance types.
249
250 For people not using cloud at all, but have their own infrastructure and hardware, use the [bootstrap](http://wiki.opscode.com/display/chef/Knife+Bootstrap) knife command. Note that the run-list specification is slightly different. For the first example of the single instance:
251
252 knife bootstrap IPADDRESS \
6146f96 @schisamo add lb to the single node stack
schisamo authored
253 -r 'role[base],role[radiant_database_master],role[radiant],role[radiant_run_migrations],recipe[radiant::db_bootstrap],role[radiant_load_balancer]'
deefdf6 @metaxis replaced generic readme with quickstart guide
metaxis authored
254
255 See the contextual help for knife bootstrap on the additional options to set for SSH.
256
257 knife bootstrap --help
258
259 ### A Note about EC2 Instances
260
261 We used m1.small instances. This is a low performance instance size in EC2 and just fine for testing. Visit the Amazon AWS documentation to [learn more about instance sizes](http://aws.amazon.com/ec2/instance-types/).
Something went wrong with that request. Please try again.