HowTo configure Apache to run Redmine » History » Version 7

« Previous - Version 7/26 (diff) - Next » - Current version
Mischa The Evil, 2009-07-26 23:07
Moved TOC to the right.

HowTo configure Apache to run Redmine

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.

For CentOS 5


  • OS is CentOS 5
  • Web server is Apache 2
    • mod_cgi is enabled
    • name based virtual servers are being used
    • the web server runs under the user apache, group apache


  • You do not need to run mod_fcgid
  • You do not need to run mod_fastcgi
  • You
    bq. This sections needs work. I can't tell if these are the myths or the corrections to the myths.
    (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 itself runs FastCGI, so it is obviously a valid, worthwhile, stable, performing way to run this great great web app'.)

Basic Steps

  • Install Redmine per the installation instructions and get it running with webrick.
  • Kill the webrick session
  • Copy the public/dispatch.cgi.example to public/dispatch.cgi
  • Edit public/dispatch.cgi to fix the shell script invocation to read:
  • Make sure public/dispatch.cgi has execute permissions via:
    # chmod 755 public/dispatch.cgi
  • Update the config/environment.rb file to force the rails environment to production, simply uncomment this line at the start of the file:
    ENV['RAILS_ENV'] ||= 'production'
  • 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!
    <VirtualHost *:80>
        ServerName redmine.<YOUR-DOMAIN>.com
        ServerAdmin webmaster@<YOUR-DOMAIN>.com
        DocumentRoot /live/redmine/public/
        ErrorLog logs/redmine_error_log

        <Directory "/live/redmine/public/">
                Options Indexes ExecCGI FollowSymLinks
                Order allow,deny
                Allow from all
                AllowOverride all
  • 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:
    # chown -R apache:apache files log tmp vendor

Error Messages and Resolutions

  • Rails requires RubyGems >= 0.9.4. Please install RubyGems
    Look for rogue versions of ruby binaries. We had an older version in /usr/bin/ruby as well as /usr/local/bin/ruby.
  • Premature script headers
    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.

Helpful Commands

  • # which ruby
    tells you which ruby binary is being run when the fully-qualified-filename has not been specified.
  • # find / -name ruby
    searches your entire system for any file named ruby, warning: can take a while on large filesystems.
  • # ruby -v
    tell you what version of ruby you are running by default
  • #public/dispatch.cgi
    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.