Project

General

Profile

HowTo configure Apache to run Redmine » History » Version 18

Matt Brown, 2011-06-03 22:34

1 1 Cyber Sprocket
h1. HowTo configure Apache to run Redmine
2
3 7 Mischa The Evil
{{>toc}}
4 1 Cyber Sprocket
5 2 Cyber Sprocket
These notes assume you already have Redmine running via the webrick server and are looking to get Redmine running via your existing Apache installation.   Most of the commands assume you are in the root installation directory of redmine, so be sure to change directory there before starting.
6 1 Cyber Sprocket
7
h2. For CentOS 5
8
9
h3. Assumptions
10
11
* OS is CentOS 5
12
* Web server is Apache 2
13
** mod_cgi is enabled
14
** name based virtual servers are being used
15 2 Cyber Sprocket
** the web server runs under the user apache, group apache
16 1 Cyber Sprocket
17 4 Cyber Sprocket
h3. Myths
18
19
* You do not need to run mod_fcgid
20
* You do not need to run mod_fastcgi
21 8 William Baum
 
22
bq. -This section needs work. I can't tell if these are the myths or the corrections to the myths.
23
_(note: if someone were so generous to post working, known good, HOWTO steps here for enabling FastCGI, that would be highly valuable to the entire community.- It is reported that www.redmine.org itself runs FastCGI, so it is obviously a valid, worthwhile, stable, performing way to run this great great web app'.)_
24 5 Brad Mace
25 14 Cyber Sprocket
bq. I have added sections detailing the installation and configuration of mod_fastcgi and mod_fcgid below. --wmbaum, (2009-08-30)
26 1 Cyber Sprocket
27 14 Cyber Sprocket
bq. We had problems with getting Rails 2.3.5 working with cgi and fastcgi.  fcgid on Apache2 worked great for 9.3. We tweaked some of the notes based on the recent fcgid updates. -- "cybersprocket":http://www.cybersprocket.com, (2010-04-25)
28
29 1 Cyber Sprocket
h3. Basic Steps
30
31 11 Patrick OMalley
* Install Redmine per the [[RedmineInstall| installation instructions]] and get it running with webrick.
32 1 Cyber Sprocket
33
* Kill the webrick session
34
35
* Copy the public/dispatch.cgi.example to public/dispatch.cgi
36
37 18 Matt Brown
* Edit public/dispatch.cgi to fix the shell script invocation to point to the ruby executable:
38 1 Cyber Sprocket
  @#!/usr/local/bin/ruby@
39 9 Patrick OMalley
  or 
40 1 Cyber Sprocket
  @#!/usr/bin/ruby@
41 18 Matt Brown
  or
42
  @#!c:/ruby_root/bin/ruby.exe@
43 1 Cyber Sprocket
44 10 Patrick OMalley
* Also in public/dispatch.cgi, you may need to change the require line to an absolute path as stated in the comment to something like
45
  @require "/usr/lib/ruby/gems/1.8/gems/rails-2.1.2/lib/dispatcher.rb"@
46
47 1 Cyber Sprocket
* Make sure public/dispatch.cgi has execute permissions via:
48
  @# chmod 755 public/dispatch.cgi@
49
50
* Update the config/environment.rb file to force the rails environment to production, simply uncomment this line at the start of the file:
51
  @ENV['RAILS_ENV'] ||= 'production'@
52
53 3 Cyber Sprocket
* Add your virtual host entry to the apache configuration file (/etc/httpd/conf/httpd.conf).  We installed redmine into the /live/redmine folder on our server. _Note: be sure to point your DocumentRoot to the public sub-folder!_
54
55 1 Cyber Sprocket
<pre>
56
    <VirtualHost *:80>
57
        ServerName redmine.<YOUR-DOMAIN>.com
58
        ServerAdmin webmaster@<YOUR-DOMAIN>.com
59
        DocumentRoot /live/redmine/public/
60
        ErrorLog logs/redmine_error_log
61
62
        <Directory "/live/redmine/public/">
63
                Options Indexes ExecCGI FollowSymLinks
64
                Order allow,deny
65
                Allow from all
66
                AllowOverride all
67
        </Directory>
68
    </VirtualHost>
69
</pre>
70
71
* Make sure your files, log, tmp, and vendor directories are all accessible (read/write) by user apache, group apache. We did that via a change of ownership:
72
  @# chown -R apache:apache files log tmp vendor@
73
74
75 2 Cyber Sprocket
h3. Error Messages and Resolutions
76 1 Cyber Sprocket
77 2 Cyber Sprocket
  * @Rails requires RubyGems >= 0.9.4. Please install RubyGems@
78 1 Cyber Sprocket
    Look for rogue versions of ruby binaries.  We had an older version in /usr/bin/ruby as well as /usr/local/bin/ruby.
79
80 2 Cyber Sprocket
  * @Premature script headers@
81
    This is the generic "got something before the Content-Type: header in a CGI script" error from Apache.  Run dispatch.cgi (see below) and see what comes out BEFORE the Content-Type: directive.
82
83 8 William Baum
h3. Helpful Commands
84 2 Cyber Sprocket
85
 * @# which ruby@
86
   tells you which ruby binary is being run when the fully-qualified-filename has not been specified.
87
88
 * @# find / -name ruby@
89
   searches your entire system for any file named ruby, warning: can take a while on large filesystems.
90
 
91
 * @# ruby -v@
92 1 Cyber Sprocket
   tell you what version of ruby you are running by default
93
94
 * @#public/dispatch.cgi@
95
   runs the dispatch CGI script.   It should spit out HTML that start with @Content-Type: text/html; charset=utf-8@, if ANYTHING precedes the Content-Type text you will get a "premature script headers" error in the Apache log files.
96 8 William Baum
97
98
h2. mod_fastcgi
99
100 17 André Jonsson
I suggest getting redmine running with mod_cgi above, not only to verify your basic redmine and apache configuration, but also so you can appreciate the perfomance gains you'll get from mod_fastcgi or mod_fcgid.
101 8 William Baum
102
We'll start with "mod_fastcgi":http://www.fastcgi.com/.  
103
104
Install prerequisites:
105
106
<pre>
107
yum install libtool httpd-devel apr-devel apr
108
</pre>
109
110
h3. Download and Install mod_fastcgi
111
112
<pre>
113
cd /usr/local/src/
114
wget http://www.fastcgi.com/dist/mod_fastcgi-current.tar.gz
115
116
tar -zxvf mod_fastcgi-current.tar.gz
117
cd mod_fastcgi-2.4.6/
118
cp Makefile.AP2 Makefile 
119
make top_dir=/usr/lib/httpd
120
make install top_dir=/usr/lib/httpd
121
</pre>
122
123
Create or edit @/etc/httpd/conf.d/mod_fastcgi.conf@
124
<pre>
125
LoadModule fastcgi_module modules/mod_fastcgi.so
126
<IfModule mod_fastcgi.c>
127
FastCgiIpcDir /tmp/fcgi_ipc/
128
</IfModule>
129
</pre>
130
131
The @/tmp/fcgi_ipc/@ directory needs to be writable to the apache user:
132
<pre>
133
chown -R apache.apache /tmp/fcgi_ipc/
134
chmod -R 777 /tmp/fcgi_ipc/
135
</pre>
136
137
> Note:  I had to do this more than once.. It created directories which it then didn't own.. ??
138
139
h3. Download and install @fcgi@ (for fcgi gem)
140
141
<pre>
142
wget http://www.fastcgi.com/dist/fcgi-2.4.0.tar.gz
143
tar -zxvf fcgi-2.4.0.tar.gz
144
cd fcgi-2.4.0
145
./configure
146
make
147
make install
148
</pre>
149
150
h3. Install fcgi gem:
151
152
<pre>
153
gem install fcgi
154
</pre>
155
156
h2. Configuring redmine to use fastcgi:
157
158
In your redmine/public/ directory, copy @dispatch.fcgi.example@ to @dispatch.fcgi@
159
> Note: Mine was shebanged to "#!/usr/bin/env ruby", which is fine.  I found a reference or two that seemed to indicate the 'env' bit is preferable to calling ruby directly.  If this doesn't work, then you'll need to change it to wherever your ruby is as above.
160
161
@./public/.htaccess@
162
<pre>
163
#<IfModule mod_fastcgi.c>
164
#       RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]
165
#</IfModule>
166
#<IfModule mod_fcgid.c>
167
#       RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]
168
#</IfModule>
169
#<IfModule mod_cgi.c>
170
#       RewriteRule ^(.*)$ dispatch.cgi [QSA,L]
171
#</IfModule>
172
RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]
173
</pre>
174
175
The default .htaccess will use cgi if it's available, so we need to force fcgi.  You could perhaps rearrange the directives to prefer fcgi -- I just commented out the others and forced it with <code>RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]</code>  You can see which one is actually in use with <code>ps gaux</code>
176
177
Give it a whirl:
178
<pre>
179
/etc/init.d/httpd configtest
180
/etc/init.d/httpd restart
181
</pre>
182
183
h2. Additional Apache Configuration
184
185
When I first fired up apache with redmine, apache started very slowly and sucked up a significantly larger chunk of RAM than normal.  Further investigation revealed that it had fired off *8* @ruby .../redmine/public/dispatch.fcgi@ processes! No wonder it was slow. 
186
187
I was running redmin under the apache default VirtualHost, and the default StartServers, MinSpareServers, etc. applied.  You can adjust the defaults in @/etc/httpd/conf/httpd.conf@ or even better is to run redmine under a @NameVirtualHost@ or a different @VirtualHost@.  This prevents apache from firing off a bunch of extraneous processes, and @NameVirtualHost@ should allow you to configure multiple redmine environments on the same IP without wasting a bunch of resources.
188
189
If you're having issues with apache virtual hosts, this can be very helpful:
190
<pre>
191
/usr/sbin/httpd -t -D DUMP_VHOSTS
192
</pre>
193
194
h2. mod_fcgid
195 1 Cyber Sprocket
196 14 Cyber Sprocket
h3. fcgid from Apache
197
198
"Official Apache mod_fcgid":http://httpd.apache.org/mod_fcgid/ this is the Apache version, seems newer and we had more luck with this than the Coremail hosted version below.
199
200
<pre>
201
cd /usr/local/src/
202
wget http://apache.mirrors.hoobly.com/httpd/mod_fcgid/mod_fcgid-2.3.5.tar.gz
203
tar zxvf mod_fcgid.2.3.5.tgz
204
cd mod_fcgid.2.3.5
205
</pre>
206
207
Configure and Install
208
<pre>
209
./configure.apxs
210
make
211
make install
212
service httpd restart
213
</pre>
214
215
216
217
h3. fcgid from China Coremail service
218
219 8 William Baum
"mod_fcgid":http://fastcgi.coremail.cn/ seems newer and preferable to mod_fastcgi.
220 1 Cyber Sprocket
221 14 Cyber Sprocket
222 1 Cyber Sprocket
<pre>
223 8 William Baum
cd /usr/local/src/
224 14 Cyber Sprocket
wget http://apache.mirrors.hoobly.com/httpd/mod_fcgid/mod_fcgid-2.2.tar.gz
225 13 William Baum
tar zxvf mod_fcgid.2.2.tgz
226
cd mod_fcgid.2.2
227 8 William Baum
</pre>
228
229
Edit Makefile
230
<pre>
231
#top_dir      = /usr/local/apache2
232 1 Cyber Sprocket
top_dir      = /usr/lib/httpd
233 13 William Baum
</pre>
234
235
Build it..
236
<pre>
237
make
238
make install
239 8 William Baum
</pre>
240
241
Edit/create @/etc/httpd/conf.d/mod_fcgid.conf@
242
<pre>
243
LoadModule fcgid_module /usr/lib/httpd/modules/mod_fcgid.so
244
245
<IfModule mod_fcgid.c>
246
    SocketPath /tmp/fcgid_sock/
247
    AddHandler fcgid-script .fcgi
248
</IfModule>
249
</pre>
250
251
Now you should be able to switch between mod_fastcgi and mod_fcgid by renaming one of them to other than *.conf in @/etc/httpd/conf.d/@
252
<pre>
253
cd /etc/httpd/conf.d/
254
mv mod_fastcgi.conf mod_fastcgi.conf.not
255 1 Cyber Sprocket
/etc/init.d/httpd restart
256
</pre>
257 14 Cyber Sprocket
258
259
h3. Either Version, Permissions
260
261
With either fcgid version you may run into problems with the fcgid service starting.   Make sure the socks parent directory (typically /var/log/httpd) has proper permissions.   The default directory permissions for /var/log/httpd is for a standard non-fcgid install of Apache.  You need to add execute permissions for Apache to read/write to the directory properly while it is running fcgid.
262
263
<pre>
264
chmod 755 /var/log/httpd
265
service httpd restart
266
</pre>
267
268 8 William Baum
269
h2. Installation Sources
270
271
In the above steps, I installed from sources only where I didn't find any RPM's in common repo's.  I'm rather surprised that one can't simply @yum install@ mod_fastcgi, mod_fcgid, fcgi, etc., but there we are.  If you find better methods or sources for any of the above, please feel free to update.
272 12 Fred Eisele
273 16 Lu Pon
h2. Ubuntu Server (Version ?) (This not don't work for 8.04 LTS)
274 12 Fred Eisele
275
Install passenger
276
<pre>
277
sudo aptitude install libapache2-mod-passenger
278
</pre>
279
This did switch the type of apache server to worker from prefork but in my case that was acceptable.
280
281
I had installed the redmine tarball into /opt/redmine as redmine-0.8.5 and made a symlink named current.
282
Then make a link to the redmine public directory from the apache DocumentRoot (see /etc/apache2/config.d/*).
283
<pre>
284
ln -s /opt/redmine/current/public /var/www/redmine
285
</pre>
286
287
Updated /etc/apache/config.d/redmine (or wherever your virtualhost is defined) with the following:
288
<pre>
289
RailsEnv production
290
RailsBaseURI /redmine
291
</pre>
292
293
Restart apache.
294 15 Martin Cyr
295
h2. For FreeBSD (and possibly others)
296
297
I found the current instructions to be lacking on some way. With the information above, the scripts and css might not appear correctly, the link get broken and such. Also, some hacks seems to have been lost to history (the #!/bin/bash/ruby hack, wich is not required with this technique). Here is how I got it going.
298
299
Make sure 'Apache 2.2', 'Ruby', 'fastcgi' (including the gem) are installed.
300
First, putting redmine in a sub-directory requires more work and is left for the reader as an exercise to get properly (hint Rewrite is your friend), so from now on, I will assume that redmine will be the DocumentRoot.
301
So here it is, my httpd.conf :
302
<pre>
303
LoadModule fastcgi_module     libexec/apache22/mod_fastcgi.so
304
305
DocumentRoot "/usr/local/www/redmine/public"
306
307
FastCgiServer /usr/local/www/redmine/public/dispatch.fcgi -idle-timeout 120 -initial-env RAILS_ENV=production -initial-env PATH=/usr/local/bin -processes 2
308
309
<Directory /usr/local/www/redmine/public>
310
   AddHandler fastcgi-script fcgi
311
   Order allow,deny
312
   Allow from all
313
   AllowOverride all
314
   Options +FollowSymLinks +ExecCGI
315
   RewriteEngine On
316
   RewriteCond %{REQUEST_FILENAME} !-f
317
   RewriteRule ^(.*)$ dispatch.fcgi
318
</Directory>
319
</pre>
320
321
Now let's explain what happens and why:
322
# _AddHandler fastcgi-script fcgi_: defines that when apache identifies a file with extension fcgi, if should be handled buy the fastcgi-script handler. This definition of a handler is created by the mod_fastcgi.so module (loaded through the LoadModule directive of couse).
323
# _Options +FollowSymLinks +ExecCGI_: tells apache that within this directory, CGI-ish script execution is allowed
324
# _RewriteCond %{REQUEST_FILENAME} !-f_: only rewrite if the file doesn't exist
325
# _RewriteRule ^(.*)$ dispatch.fcgi_: everything goes to dispatch.fcgi
326
# _FastCgiServer /usr/local/www/redmine/public/dispatch.fcgi -idle-timeout 120 -initial-env RAILS_ENV=production -initial-env PATH=/usr/local/bin -processes 2_: This is the main thing. As Scott Laird explains in this "blog":http://scottstuff.net/blog/2005/07/20/apache-tuning-for-rails-and-fastcgi, running FastCGI can run in three modes (see post). This tells FastCGI how to handle our script, with the important part being the initial-env to define what variables should be set in the FastCGI context. As FastCGI starts, it will normally start with a blank (*emtpy*) environment variables, so yeah, your $PATH will be empty, and no /usr/bin/env *will NOT* find the ruby executable in the path and thus failing with the error _env: ruby: No such file or directory_. Also, ruby will not know that he is expected to start in production env. With this line, you don't have to fix your dispatch.fcgi shabang (the #!/usr/bin/env ruby line) nor will you have to change the config/environment.rb file with a ENV['RAILS_ENV'] ||= 'production'.
327
328
Restart apache and you should be set.