Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 196 lines (151 sloc) 7.524 kB
3c76ca4 git-svn-id: svn://cherokee-project.com/cherokee/trunk@1816 5dc97367-9…
taher authored
1 == link:index.html[Index] -> link:cookbook.html[Cookbook]
2
bec5271 git-svn-id: svn://cherokee-project.com/cherokee/trunk@1801 5dc97367-9…
taher authored
3 Cookbook: Setting up Ruby on Rails
4 ----------------------------------
8205a03 git-svn-id: svn://cherokee-project.com/cherokee/trunk@1786 5dc97367-9…
taher authored
5
e324ca8 Updates Rails recipe
taher authored
6 Setting up a Rails application to run with Cherokee is not only
dd83a7c Updates the rest of the documentation
taher authored
7 easy. It is also the best possible solution to manage the load among a
8 bunch of servers running Rails. This is done by using an extremely
bdd5bf4 Documentation updates
taher authored
9 efficient web server to manage the web part and leaving as many free
10 resources as possible to Rails.
11
1518f47 Documentation updates
taher authored
12 There is a
13 link:http://www.cherokee-project.com/screencasts.html#rails[screencast]
14 available at the
15 link:http://www.cherokee-project.com/[Cherokee-Project website] to
16 demonstrate how easy it is to use the Rails wizard.
17
18 image:media/images/screencast.png["Rails wizard",
19 link="http://www.cherokee-project.com/screencasts.html#rails"]
20
21
5ba12d9 @skinkie Aspelled all the cookbooks.
skinkie authored
22 [[framework]]
bdd5bf4 Documentation updates
taher authored
23 === Preparing the framework
8205a03 git-svn-id: svn://cherokee-project.com/cherokee/trunk@1786 5dc97367-9…
taher authored
24
bec5271 git-svn-id: svn://cherokee-project.com/cherokee/trunk@1801 5dc97367-9…
taher authored
25 Of course you will need a working Rails installation for this to
5ba12d9 @skinkie Aspelled all the cookbooks.
skinkie authored
26 succeed. You can set this up easily. If you have Ruby and Ruby Gems
bec5271 git-svn-id: svn://cherokee-project.com/cherokee/trunk@1801 5dc97367-9…
taher authored
27 installed, you can directly install the 'Rails' gem like this:
28
29 ----
30 # gem update --system
31 # gem install rails
32 ----
33
34 Note that on Debian based systems you don't even need to install
35 Rubygems. There is already a package that will install every needed
36 dependency:
37
38 ----
39 # apt-get install rails
40 ----
41
42 The installation of the 'Rails' gem directly would also work, but note
43 that you cannot execute the first command because it is disabled by
44 default.
45
46 ----
47 # gem update --system
48 ERROR: While executing gem ... (RuntimeError)
49 gem update --system is disabled on Debian. RubyGems can be updated \
50 using the official Debian repositories by aptitude or apt-get.
51 ----
52
e324ca8 Updates Rails recipe
taher authored
53 You can also install some other gems. `thin`, `mongrel`, `unicorn`,
54 `rack` and `fcgi` are some that you might find useful.
55
bec5271 git-svn-id: svn://cherokee-project.com/cherokee/trunk@1801 5dc97367-9…
taher authored
56 Once you are done with that, you must deploy your Rails project:
57
58 ----
59 $ rails example
60 ----
61
e324ca8 Updates Rails recipe
taher authored
62 You can do so wherever you want, but the usual recommended way of doing
bec5271 git-svn-id: svn://cherokee-project.com/cherokee/trunk@1801 5dc97367-9…
taher authored
63 this is by deploying it outside of your web root path and then
e324ca8 Updates Rails recipe
taher authored
64 creating a symbolic link. This is simply to protect from exposing all
bec5271 git-svn-id: svn://cherokee-project.com/cherokee/trunk@1801 5dc97367-9…
taher authored
65 the files that do not need to be in your document root.
66
67 Assuming you deployed the `example` project in `/home/foo/example`,
68 and you have writing permissions to your web path, `/var/www`, simply
69 type:
70
71 ----
72 $ ln -s /home/foo/example/public /var/www/example
73 ----
74
bdd5bf4 Documentation updates
taher authored
75 Now you are ready to configure Cherokee.
76
77 [[cherokee]]
78 === Preparing Cherokee
79
80 You can either do it by hand, or you can use the appropriate wizard
81 for a hassle-free configuration.
82
a49d7e0 Some updates to the Rails recipe. Issue 679.
taher authored
83 [[wizard]]
84 === Setting up Cherokee with the wizard
85
bdd5bf4 Documentation updates
taher authored
86 You should really use the recommended method, which is using the
87 configuration wizard provided by Cherokee-Admin. Simply go to the
dd83a7c Updates the rest of the documentation
taher authored
88 virtual server list page and click on the `Add` button at the top of
89 the panel to show the list of available wizards. This will allow you
90 to set up a new dedicated virtual host for your Rails application.
91 Once in there, use the `Add` button at the top of the panel to see the
92 available wizards.
93
94 If you wanted to configure Rails to run under a web directory of an
95 existing virtual server, you would have to launch the wizard from
96 within the specific virtual server, visiting the `Behavior` tab and
97 trigger the `Rule panel` by clicking on the `Rule Management`
98 button.
bdd5bf4 Documentation updates
taher authored
99
12dfa0f Minor adjustments and cleanup for some entries of the cookbook
taher authored
100 .Wizards
bdd5bf4 Documentation updates
taher authored
101 image::media/images/admin_vservers_wizard.png[Virtual Server Wizards]
102
103 Now, you will have to select the `Platforms` category, and run the
104 `RoR` wizard. You will be asked for some basic parameters about the
105 installation, and the wizard will try to fill in automatically as many
106 entries as possible. The virtual server configuration will cover the
107 vast majority of the cases. Most probably it will cover your needs,
108 although you are free to modify it as you will. No more configuration
109 is needed after this step.
110
12dfa0f Minor adjustments and cleanup for some entries of the cookbook
taher authored
111 .The wizard in action
a49d7e0 Some updates to the Rails recipe. Issue 679.
taher authored
112 image::media/images/cookbook_ror_wizard.png[Rails Wizard]
113
e324ca8 Updates Rails recipe
taher authored
114 It is usually best to proxy one or several of the servers used by
c1b8f32 Typo fix
taher authored
115 Rails, be it Thin, Mongrel, Unicorn or whatever it can handle. You
116 could also choose the FastCGI alternative if there is a suitable
e324ca8 Updates Rails recipe
taher authored
117 spawning method in your system. This approach, however, has been known
c1b8f32 Typo fix
taher authored
118 to give inconsistent results on several releases of Rails. In
119 particular, Rails releases 2.3 or higher are known to give errors when
120 used with FastCGI. You will have to test it out and choose the method
121 that best suits your need.
a49d7e0 Some updates to the Rails recipe. Issue 679.
taher authored
122
123 === Setting up Cherokee by hand
e324ca8 Updates Rails recipe
taher authored
124
bdd5bf4 Documentation updates
taher authored
125 If you decide to ignore the configuration wizard you can set up
126 everything by hand. Although it is not complicated, this method is not
127 recommended.
128
129 You only need to know that you can spawn the FastCGI process using a
130 script that is already in your deployed project. In this case,
131 `/home/foo/example/script/process/spawner`. We will be using the
132 default parameters (3 instances starting at port 8000) but you can
133 fine tune this using the many parameters provided by the script.
bec5271 git-svn-id: svn://cherokee-project.com/cherokee/trunk@1801 5dc97367-9…
taher authored
134
135 The process is fairly simple. Set up a new rule for this new path and
136 manage it with the FastCGI handler.
137
138 .Common CGI options
139 Under `Common CGI options` make sure to check the `Error handler` box and
140 uncheck `Check file`. This is to prevent possible errors with the
141 `INFO_PATH` generation that can happen when an application, in this
142 case 'Rails', manages the whole subtree. This is mentioned in the
143 link:modules_handlers_cgi.html[Common CGI] section of the
7e15172 git-svn-id: svn://cherokee-project.com/cherokee/trunk@2346 5dc97367-9…
taher authored
144 documentation. It is a good idea to enable the `Error handler`
145 checkbox since it will help you determine if an error is associated
8b9f72f @alobbs git-svn-id: svn://cherokee-project.com/cherokee/trunk@2541 5dc97367-9…
alobbs authored
146 with your Ruby on Rails application or with Cherokee. This, however,
147 is not required.
bec5271 git-svn-id: svn://cherokee-project.com/cherokee/trunk@1801 5dc97367-9…
taher authored
148
12dfa0f Minor adjustments and cleanup for some entries of the cookbook
taher authored
149 .FastCGI handler
bec5271 git-svn-id: svn://cherokee-project.com/cherokee/trunk@1801 5dc97367-9…
taher authored
150 image::media/images/cookbook_ror_common.png[Common CGI options]
151
152 .FastCGI specific
153 Under `FastCGI specific` make sure to add the hosts providing the
1ee8b21 git-svn-id: svn://cherokee-project.com/cherokee/trunk@2041 5dc97367-9…
taher authored
154 service. Do this by adding one or more
155 link:config_info_sources.html[Information Sources].
156
5ba12d9 @skinkie Aspelled all the cookbooks.
skinkie authored
157 Note that, in the definition of the information source, you will have
1ee8b21 git-svn-id: svn://cherokee-project.com/cherokee/trunk@2041 5dc97367-9…
taher authored
158 to manually launch the `spawner` if you use a `Remote host` as
159 `Information source` instead of a `Local interpreter`.
bec5271 git-svn-id: svn://cherokee-project.com/cherokee/trunk@1801 5dc97367-9…
taher authored
160
161 You will simply have to add as many sources as desired, for instance
1ee8b21 git-svn-id: svn://cherokee-project.com/cherokee/trunk@2041 5dc97367-9…
taher authored
162 our example uses the default values to set up ports 8000 through
163 8002. These sources will be nicknamed *ror0*, *ror1* and *ror2*.
bec5271 git-svn-id: svn://cherokee-project.com/cherokee/trunk@1801 5dc97367-9…
taher authored
164
7d3d6a2 @skarcha asciidoc.py upgraded to version 8.4.5
skarcha authored
165 [cols="20%,80%",options="header"]
166 |===============================================================
167 |Host |Interpreter
168 |localhost:8000 |`/home/foo/example/script/process/spawner fcgi`
169 |localhost:8001 |`/home/foo/example/script/process/spawner fcgi`
170 |localhost:8002 |`/home/foo/example/script/process/spawner fcgi`
171 |===============================================================
bec5271 git-svn-id: svn://cherokee-project.com/cherokee/trunk@1801 5dc97367-9…
taher authored
172
173 If any of those ports was not reachable, the `interpreter` command
174 would be launched and the fallen one would be reinstantiated.
175
12dfa0f Minor adjustments and cleanup for some entries of the cookbook
taher authored
176 According to that table, the creation of the *ror0* information source
177 would use the following settings. The rest are similar using the port
178 variation detailed above.
1ee8b21 git-svn-id: svn://cherokee-project.com/cherokee/trunk@2041 5dc97367-9…
taher authored
179
12dfa0f Minor adjustments and cleanup for some entries of the cookbook
taher authored
180 .ror0 information source
181 [cols="15%,20%,65%",options="header"]
182 |===============================================================
183 |Nick |Connection |Interpreter
184 |ror0 |localhost:8000 |`/home/foo/example/script/process/spawner fcgi`
185 |===============================================================
186
187 .ror0 information source
bec5271 git-svn-id: svn://cherokee-project.com/cherokee/trunk@1801 5dc97367-9…
taher authored
188 image::media/images/cookbook_ror_fcgi.png[FastCGI specifics]
7e15172 git-svn-id: svn://cherokee-project.com/cherokee/trunk@2346 5dc97367-9…
taher authored
189
190 Once everything is done you can check if Rails is really
191 working. Simply navigate to the path configured by your rule,
192 http://localhost/example/ for instance, and you should see some notes
193 about your recently created project.
194
195 image::media/images/cookbook_ror.png[Rails example]
Something went wrong with that request. Please try again.