HowTo configure Apache to run Redmine » History » Version 11

Patrick OMalley, 2009-09-03 17:46
added link to installation instructions

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