HowTo configure Apache to run Redmine » History » Version 24

Genadi Saltikov, 2012-08-01 21:31

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 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 14 Cyber Sprocket
29 1 Cyber Sprocket
h3. Basic Steps
30 1 Cyber Sprocket
31 11 Patrick OMalley
* Install Redmine per the [[RedmineInstall| installation instructions]] and get it running with webrick.
32 1 Cyber Sprocket
33 1 Cyber Sprocket
* Kill the webrick session
34 1 Cyber Sprocket
35 1 Cyber Sprocket
* Copy the public/dispatch.cgi.example to public/dispatch.cgi
36 1 Cyber Sprocket
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 18 Matt Brown
  @#!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 10 Patrick OMalley
  @require "/usr/lib/ruby/gems/1.8/gems/rails-2.1.2/lib/dispatcher.rb"@
46 19 Matt Brown
  or
47 19 Matt Brown
  @require "c:/ruby_root/lib/ruby/gems/1.8/gems/rails-2.3.11/lib/dispatcher.rb"@
48 10 Patrick OMalley
49 1 Cyber Sprocket
* Make sure public/dispatch.cgi has execute permissions via:
50 1 Cyber Sprocket
  @# chmod 755 public/dispatch.cgi@
51 1 Cyber Sprocket
52 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:
53 1 Cyber Sprocket
  @ENV['RAILS_ENV'] ||= 'production'@
54 1 Cyber Sprocket
55 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!_
56 3 Cyber Sprocket
57 1 Cyber Sprocket
<pre>
58 1 Cyber Sprocket
    <VirtualHost *:80>
59 1 Cyber Sprocket
        ServerName redmine.<YOUR-DOMAIN>.com
60 1 Cyber Sprocket
        ServerAdmin webmaster@<YOUR-DOMAIN>.com
61 1 Cyber Sprocket
        DocumentRoot /live/redmine/public/
62 1 Cyber Sprocket
        ErrorLog logs/redmine_error_log
63 1 Cyber Sprocket
64 21 Anton Kovalenko
        #If you are using mod_fcgid and are going to upload files larger than
65 21 Anton Kovalenko
        #131072 bytes you should consider adding the following line
66 21 Anton Kovalenko
        #that allows to upload files up to 20 mb
67 21 Anton Kovalenko
        MaxRequestLen 20971520
68 21 Anton Kovalenko
69 1 Cyber Sprocket
        <Directory "/live/redmine/public/">
70 1 Cyber Sprocket
                Options Indexes ExecCGI FollowSymLinks
71 1 Cyber Sprocket
                Order allow,deny
72 1 Cyber Sprocket
                Allow from all
73 1 Cyber Sprocket
                AllowOverride all
74 1 Cyber Sprocket
        </Directory>
75 1 Cyber Sprocket
    </VirtualHost>
76 1 Cyber Sprocket
</pre>
77 1 Cyber Sprocket
78 24 Genadi Saltikov
* Dont forget to bind to the port!
79 24 Genadi Saltikov
<pre>
80 24 Genadi Saltikov
Listen *:3000
81 24 Genadi Saltikov
</pre>
82 24 Genadi Saltikov
83 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:
84 1 Cyber Sprocket
  @# chown -R apache:apache files log tmp vendor@
85 1 Cyber Sprocket
86 1 Cyber Sprocket
87 2 Cyber Sprocket
h3. Error Messages and Resolutions
88 1 Cyber Sprocket
89 2 Cyber Sprocket
  * @Rails requires RubyGems >= 0.9.4. Please install RubyGems@
90 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.
91 1 Cyber Sprocket
92 2 Cyber Sprocket
  * @Premature script headers@
93 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.
94 2 Cyber Sprocket
95 8 William Baum
h3. Helpful Commands
96 2 Cyber Sprocket
97 2 Cyber Sprocket
 * @# which ruby@
98 2 Cyber Sprocket
   tells you which ruby binary is being run when the fully-qualified-filename has not been specified.
99 2 Cyber Sprocket
100 2 Cyber Sprocket
 * @# find / -name ruby@
101 2 Cyber Sprocket
   searches your entire system for any file named ruby, warning: can take a while on large filesystems.
102 2 Cyber Sprocket
 
103 2 Cyber Sprocket
 * @# ruby -v@
104 1 Cyber Sprocket
   tell you what version of ruby you are running by default
105 1 Cyber Sprocket
106 1 Cyber Sprocket
 * @#public/dispatch.cgi@
107 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.
108 8 William Baum
109 8 William Baum
110 8 William Baum
h2. mod_fastcgi
111 8 William Baum
112 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.
113 8 William Baum
114 8 William Baum
We'll start with "mod_fastcgi":http://www.fastcgi.com/.  
115 8 William Baum
116 8 William Baum
Install prerequisites:
117 8 William Baum
118 8 William Baum
<pre>
119 8 William Baum
yum install libtool httpd-devel apr-devel apr
120 8 William Baum
</pre>
121 8 William Baum
122 8 William Baum
h3. Download and Install mod_fastcgi
123 8 William Baum
124 8 William Baum
<pre>
125 8 William Baum
cd /usr/local/src/
126 8 William Baum
wget http://www.fastcgi.com/dist/mod_fastcgi-current.tar.gz
127 8 William Baum
128 8 William Baum
tar -zxvf mod_fastcgi-current.tar.gz
129 8 William Baum
cd mod_fastcgi-2.4.6/
130 8 William Baum
cp Makefile.AP2 Makefile 
131 8 William Baum
make top_dir=/usr/lib/httpd
132 8 William Baum
make install top_dir=/usr/lib/httpd
133 8 William Baum
</pre>
134 8 William Baum
135 8 William Baum
Create or edit @/etc/httpd/conf.d/mod_fastcgi.conf@
136 8 William Baum
<pre>
137 8 William Baum
LoadModule fastcgi_module modules/mod_fastcgi.so
138 8 William Baum
<IfModule mod_fastcgi.c>
139 8 William Baum
FastCgiIpcDir /tmp/fcgi_ipc/
140 8 William Baum
</IfModule>
141 8 William Baum
</pre>
142 8 William Baum
143 8 William Baum
The @/tmp/fcgi_ipc/@ directory needs to be writable to the apache user:
144 8 William Baum
<pre>
145 8 William Baum
chown -R apache.apache /tmp/fcgi_ipc/
146 8 William Baum
chmod -R 777 /tmp/fcgi_ipc/
147 8 William Baum
</pre>
148 8 William Baum
149 8 William Baum
> Note:  I had to do this more than once.. It created directories which it then didn't own.. ??
150 8 William Baum
151 8 William Baum
h3. Download and install @fcgi@ (for fcgi gem)
152 8 William Baum
153 8 William Baum
<pre>
154 8 William Baum
wget http://www.fastcgi.com/dist/fcgi-2.4.0.tar.gz
155 8 William Baum
tar -zxvf fcgi-2.4.0.tar.gz
156 8 William Baum
cd fcgi-2.4.0
157 8 William Baum
./configure
158 8 William Baum
make
159 8 William Baum
make install
160 8 William Baum
</pre>
161 8 William Baum
162 8 William Baum
h3. Install fcgi gem:
163 8 William Baum
164 8 William Baum
<pre>
165 8 William Baum
gem install fcgi
166 8 William Baum
</pre>
167 8 William Baum
168 8 William Baum
h2. Configuring redmine to use fastcgi:
169 8 William Baum
170 8 William Baum
In your redmine/public/ directory, copy @dispatch.fcgi.example@ to @dispatch.fcgi@
171 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.
172 8 William Baum
173 8 William Baum
@./public/.htaccess@
174 8 William Baum
<pre>
175 22 Anton Kovalenko
#RewriteRule ^(stylesheets.*|images.*|favicon.*|javascripts.*|plugin_assets.*|themes.*|help.*)$ $1 [L]
176 8 William Baum
#<IfModule mod_fastcgi.c>
177 8 William Baum
#       RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]
178 8 William Baum
#</IfModule>
179 8 William Baum
#<IfModule mod_fcgid.c>
180 8 William Baum
#       RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]
181 8 William Baum
#</IfModule>
182 8 William Baum
#<IfModule mod_cgi.c>
183 8 William Baum
#       RewriteRule ^(.*)$ dispatch.cgi [QSA,L]
184 8 William Baum
#</IfModule>
185 8 William Baum
RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]
186 8 William Baum
</pre>
187 8 William Baum
188 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>
189 24 Genadi Saltikov
190 24 Genadi Saltikov
191 8 William Baum
192 8 William Baum
Give it a whirl:
193 8 William Baum
<pre>
194 8 William Baum
/etc/init.d/httpd configtest
195 8 William Baum
/etc/init.d/httpd restart
196 8 William Baum
</pre>
197 8 William Baum
198 8 William Baum
h2. Additional Apache Configuration
199 8 William Baum
200 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. 
201 8 William Baum
202 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.
203 8 William Baum
204 8 William Baum
If you're having issues with apache virtual hosts, this can be very helpful:
205 8 William Baum
<pre>
206 8 William Baum
/usr/sbin/httpd -t -D DUMP_VHOSTS
207 8 William Baum
</pre>
208 8 William Baum
209 8 William Baum
h2. mod_fcgid
210 1 Cyber Sprocket
211 14 Cyber Sprocket
h3. fcgid from Apache
212 14 Cyber Sprocket
213 14 Cyber Sprocket
"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.
214 14 Cyber Sprocket
215 14 Cyber Sprocket
<pre>
216 14 Cyber Sprocket
cd /usr/local/src/
217 14 Cyber Sprocket
wget http://apache.mirrors.hoobly.com/httpd/mod_fcgid/mod_fcgid-2.3.5.tar.gz
218 14 Cyber Sprocket
tar zxvf mod_fcgid.2.3.5.tgz
219 14 Cyber Sprocket
cd mod_fcgid.2.3.5
220 14 Cyber Sprocket
</pre>
221 14 Cyber Sprocket
222 14 Cyber Sprocket
Configure and Install
223 14 Cyber Sprocket
<pre>
224 14 Cyber Sprocket
./configure.apxs
225 14 Cyber Sprocket
make
226 14 Cyber Sprocket
make install
227 14 Cyber Sprocket
service httpd restart
228 14 Cyber Sprocket
</pre>
229 14 Cyber Sprocket
230 14 Cyber Sprocket
231 14 Cyber Sprocket
232 14 Cyber Sprocket
h3. fcgid from China Coremail service
233 14 Cyber Sprocket
234 8 William Baum
"mod_fcgid":http://fastcgi.coremail.cn/ seems newer and preferable to mod_fastcgi.
235 1 Cyber Sprocket
236 14 Cyber Sprocket
237 1 Cyber Sprocket
<pre>
238 8 William Baum
cd /usr/local/src/
239 14 Cyber Sprocket
wget http://apache.mirrors.hoobly.com/httpd/mod_fcgid/mod_fcgid-2.2.tar.gz
240 13 William Baum
tar zxvf mod_fcgid.2.2.tgz
241 13 William Baum
cd mod_fcgid.2.2
242 8 William Baum
</pre>
243 8 William Baum
244 8 William Baum
Edit Makefile
245 8 William Baum
<pre>
246 8 William Baum
#top_dir      = /usr/local/apache2
247 1 Cyber Sprocket
top_dir      = /usr/lib/httpd
248 13 William Baum
</pre>
249 13 William Baum
250 13 William Baum
Build it..
251 13 William Baum
<pre>
252 13 William Baum
make
253 13 William Baum
make install
254 8 William Baum
</pre>
255 8 William Baum
256 8 William Baum
Edit/create @/etc/httpd/conf.d/mod_fcgid.conf@
257 8 William Baum
<pre>
258 8 William Baum
LoadModule fcgid_module /usr/lib/httpd/modules/mod_fcgid.so
259 8 William Baum
260 8 William Baum
<IfModule mod_fcgid.c>
261 8 William Baum
    SocketPath /tmp/fcgid_sock/
262 8 William Baum
    AddHandler fcgid-script .fcgi
263 8 William Baum
</IfModule>
264 8 William Baum
</pre>
265 8 William Baum
266 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/@
267 8 William Baum
<pre>
268 8 William Baum
cd /etc/httpd/conf.d/
269 8 William Baum
mv mod_fastcgi.conf mod_fastcgi.conf.not
270 1 Cyber Sprocket
/etc/init.d/httpd restart
271 1 Cyber Sprocket
</pre>
272 14 Cyber Sprocket
273 14 Cyber Sprocket
274 14 Cyber Sprocket
h3. Either Version, Permissions
275 14 Cyber Sprocket
276 14 Cyber Sprocket
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.
277 14 Cyber Sprocket
278 14 Cyber Sprocket
<pre>
279 14 Cyber Sprocket
chmod 755 /var/log/httpd
280 14 Cyber Sprocket
service httpd restart
281 14 Cyber Sprocket
</pre>
282 14 Cyber Sprocket
283 8 William Baum
284 8 William Baum
h2. Installation Sources
285 8 William Baum
286 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.
287 12 Fred Eisele
288 23 Clinton Ooi
bq. You can find mod_fcgid rpm "here":http://rpmfind.net/linux/RPM/epel/6/x86_64/mod_fcgid-2.3.7-1.el6.x86_64.html --yingchun437, (2012-06-25)
289 23 Clinton Ooi
290 23 Clinton Ooi
291 16 Lu Pa
h2. Ubuntu Server (Version ?) (This not don't work for 8.04 LTS)
292 12 Fred Eisele
293 12 Fred Eisele
Install passenger
294 12 Fred Eisele
<pre>
295 12 Fred Eisele
sudo aptitude install libapache2-mod-passenger
296 12 Fred Eisele
</pre>
297 12 Fred Eisele
This did switch the type of apache server to worker from prefork but in my case that was acceptable.
298 12 Fred Eisele
299 12 Fred Eisele
I had installed the redmine tarball into /opt/redmine as redmine-0.8.5 and made a symlink named current.
300 12 Fred Eisele
Then make a link to the redmine public directory from the apache DocumentRoot (see /etc/apache2/config.d/*).
301 12 Fred Eisele
<pre>
302 12 Fred Eisele
ln -s /opt/redmine/current/public /var/www/redmine
303 12 Fred Eisele
</pre>
304 12 Fred Eisele
305 12 Fred Eisele
Updated /etc/apache/config.d/redmine (or wherever your virtualhost is defined) with the following:
306 12 Fred Eisele
<pre>
307 12 Fred Eisele
RailsEnv production
308 12 Fred Eisele
RailsBaseURI /redmine
309 12 Fred Eisele
</pre>
310 12 Fred Eisele
311 12 Fred Eisele
Restart apache.
312 15 Martin Cyr
313 15 Martin Cyr
h2. For FreeBSD (and possibly others)
314 15 Martin Cyr
315 15 Martin Cyr
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.
316 15 Martin Cyr
317 15 Martin Cyr
Make sure 'Apache 2.2', 'Ruby', 'fastcgi' (including the gem) are installed.
318 15 Martin Cyr
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.
319 15 Martin Cyr
So here it is, my httpd.conf :
320 15 Martin Cyr
<pre>
321 15 Martin Cyr
LoadModule fastcgi_module     libexec/apache22/mod_fastcgi.so
322 15 Martin Cyr
323 15 Martin Cyr
DocumentRoot "/usr/local/www/redmine/public"
324 15 Martin Cyr
325 15 Martin Cyr
FastCgiServer /usr/local/www/redmine/public/dispatch.fcgi -idle-timeout 120 -initial-env RAILS_ENV=production -initial-env PATH=/usr/local/bin -processes 2
326 15 Martin Cyr
327 15 Martin Cyr
<Directory /usr/local/www/redmine/public>
328 15 Martin Cyr
   AddHandler fastcgi-script fcgi
329 15 Martin Cyr
   Order allow,deny
330 15 Martin Cyr
   Allow from all
331 15 Martin Cyr
   AllowOverride all
332 15 Martin Cyr
   Options +FollowSymLinks +ExecCGI
333 15 Martin Cyr
   RewriteEngine On
334 15 Martin Cyr
   RewriteCond %{REQUEST_FILENAME} !-f
335 15 Martin Cyr
   RewriteRule ^(.*)$ dispatch.fcgi
336 15 Martin Cyr
</Directory>
337 15 Martin Cyr
</pre>
338 15 Martin Cyr
339 15 Martin Cyr
Now let's explain what happens and why:
340 15 Martin Cyr
# _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).
341 15 Martin Cyr
# _Options +FollowSymLinks +ExecCGI_: tells apache that within this directory, CGI-ish script execution is allowed
342 15 Martin Cyr
# _RewriteCond %{REQUEST_FILENAME} !-f_: only rewrite if the file doesn't exist
343 15 Martin Cyr
# _RewriteRule ^(.*)$ dispatch.fcgi_: everything goes to dispatch.fcgi
344 15 Martin Cyr
# _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'.
345 15 Martin Cyr
346 15 Martin Cyr
Restart apache and you should be set.