Project

General

Profile

HowTo configure Apache to run Redmine » History » Version 10

Patrick OMalley, 2009-09-03 17:43
added note about require line

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 8 William Baum
bq. I have added sections detailing the installation and configuration of mod_fastcgi and mod_fcid below. --wmbaum, (2009-08-30)
26
27 1 Cyber Sprocket
h3. Basic Steps
28
29
* Install Redmine per the installation instructions and get it running with webrick.
30
31
* Kill the webrick session
32
33
* Copy the public/dispatch.cgi.example to public/dispatch.cgi
34
35 9 Patrick OMalley
* Edit public/dispatch.cgi to fix the shell script invocation to point to your ruby install location like:
36 1 Cyber Sprocket
  @#!/usr/local/bin/ruby@
37 9 Patrick OMalley
  or 
38
  @#!/usr/bin/ruby@
39 1 Cyber Sprocket
40 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
41
  @require "/usr/lib/ruby/gems/1.8/gems/rails-2.1.2/lib/dispatcher.rb"@
42
43 1 Cyber Sprocket
* Make sure public/dispatch.cgi has execute permissions via:
44
  @# chmod 755 public/dispatch.cgi@
45
46
* Update the config/environment.rb file to force the rails environment to production, simply uncomment this line at the start of the file:
47
  @ENV['RAILS_ENV'] ||= 'production'@
48
49 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!_
50
51 1 Cyber Sprocket
<pre>
52
    <VirtualHost *:80>
53
        ServerName redmine.<YOUR-DOMAIN>.com
54
        ServerAdmin webmaster@<YOUR-DOMAIN>.com
55
        DocumentRoot /live/redmine/public/
56
        ErrorLog logs/redmine_error_log
57
58
        <Directory "/live/redmine/public/">
59
                Options Indexes ExecCGI FollowSymLinks
60
                Order allow,deny
61
                Allow from all
62
                AllowOverride all
63
        </Directory>
64
    </VirtualHost>
65
</pre>
66
67
* 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:
68
  @# chown -R apache:apache files log tmp vendor@
69
70
71 2 Cyber Sprocket
h3. Error Messages and Resolutions
72 1 Cyber Sprocket
73 2 Cyber Sprocket
  * @Rails requires RubyGems >= 0.9.4. Please install RubyGems@
74 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.
75
76 2 Cyber Sprocket
  * @Premature script headers@
77
    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.
78
79 8 William Baum
h3. Helpful Commands
80 2 Cyber Sprocket
81
 * @# which ruby@
82
   tells you which ruby binary is being run when the fully-qualified-filename has not been specified.
83
84
 * @# find / -name ruby@
85
   searches your entire system for any file named ruby, warning: can take a while on large filesystems.
86
 
87
 * @# ruby -v@
88 1 Cyber Sprocket
   tell you what version of ruby you are running by default
89
90
 * @#public/dispatch.cgi@
91
   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.
92 8 William Baum
93
94
h2. mod_fastcgi
95
96
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_fcid.
97
98
We'll start with "mod_fastcgi":http://www.fastcgi.com/.  
99
100
Install prerequisites:
101
102
<pre>
103
yum install libtool httpd-devel apr-devel apr
104
</pre>
105
106
h3. Download and Install mod_fastcgi
107
108
<pre>
109
cd /usr/local/src/
110
wget http://www.fastcgi.com/dist/mod_fastcgi-current.tar.gz
111
112
tar -zxvf mod_fastcgi-current.tar.gz
113
cd mod_fastcgi-2.4.6/
114
cp Makefile.AP2 Makefile 
115
make top_dir=/usr/lib/httpd
116
make install top_dir=/usr/lib/httpd
117
</pre>
118
119
Create or edit @/etc/httpd/conf.d/mod_fastcgi.conf@
120
<pre>
121
LoadModule fastcgi_module modules/mod_fastcgi.so
122
<IfModule mod_fastcgi.c>
123
FastCgiIpcDir /tmp/fcgi_ipc/
124
</IfModule>
125
</pre>
126
127
The @/tmp/fcgi_ipc/@ directory needs to be writable to the apache user:
128
<pre>
129
chown -R apache.apache /tmp/fcgi_ipc/
130
chmod -R 777 /tmp/fcgi_ipc/
131
</pre>
132
133
> Note:  I had to do this more than once.. It created directories which it then didn't own.. ??
134
135
h3. Download and install @fcgi@ (for fcgi gem)
136
137
<pre>
138
wget http://www.fastcgi.com/dist/fcgi-2.4.0.tar.gz
139
tar -zxvf fcgi-2.4.0.tar.gz
140
cd fcgi-2.4.0
141
./configure
142
make
143
make install
144
</pre>
145
146
h3. Install fcgi gem:
147
148
<pre>
149
gem install fcgi
150
</pre>
151
152
h2. Configuring redmine to use fastcgi:
153
154
In your redmine/public/ directory, copy @dispatch.fcgi.example@ to @dispatch.fcgi@
155
> 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.
156
157
@./public/.htaccess@
158
<pre>
159
#<IfModule mod_fastcgi.c>
160
#       RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]
161
#</IfModule>
162
#<IfModule mod_fcgid.c>
163
#       RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]
164
#</IfModule>
165
#<IfModule mod_cgi.c>
166
#       RewriteRule ^(.*)$ dispatch.cgi [QSA,L]
167
#</IfModule>
168
RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]
169
</pre>
170
171
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>
172
173
Give it a whirl:
174
<pre>
175
/etc/init.d/httpd configtest
176
/etc/init.d/httpd restart
177
</pre>
178
179
h2. Additional Apache Configuration
180
181
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. 
182
183
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.
184
185
If you're having issues with apache virtual hosts, this can be very helpful:
186
<pre>
187
/usr/sbin/httpd -t -D DUMP_VHOSTS
188
</pre>
189
190
h2. mod_fcgid
191
192
"mod_fcgid":http://fastcgi.coremail.cn/ seems newer and preferable to mod_fastcgi.
193
194
<pre>
195
cd /usr/local/src/
196
http://downloads.sourceforge.net/project/mod-fcgid/mod-fcgid/mod_fcgid.2.2.tar.gz/mod_fcgid.2.2.tgz
197
</pre>
198
199
Edit Makefile
200
<pre>
201
#top_dir      = /usr/local/apache2
202
top_dir      = /usr/lib/httpd
203
</pre>
204
205
Edit/create @/etc/httpd/conf.d/mod_fcgid.conf@
206
<pre>
207
LoadModule fcgid_module /usr/lib/httpd/modules/mod_fcgid.so
208
209
<IfModule mod_fcgid.c>
210
    SocketPath /tmp/fcgid_sock/
211
    AddHandler fcgid-script .fcgi
212
</IfModule>
213
</pre>
214
215
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/@
216
<pre>
217
cd /etc/httpd/conf.d/
218
mv mod_fastcgi.conf mod_fastcgi.conf.not
219
/etc/init.d/httpd restart
220
</pre>
221
222
h2. Installation Sources
223
224
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.