Installation guide of Redmine on Windows system

This instruction describes Redmine installation on Windows system in the following configuration:

• Redmine 1.3.0+
• Ruby 1.8.7 p302
• Ruby on Rails 2.3.14 -> Mongrel 1.1.5 -> Apache 2.2.x+ with proxy_balancer_module
• MySQL 5.1.x
• Domain: redmine.mycompany.com as Apache virtual host
• Redmine root folder (directory): %REDMINE_ROOT% = e:\data\redmine
• Folder where virtual hosts definitions reside: %VHOSTS_DIR% = e:\data\vhosts
• Folder where logs are written: %LOGDIR% = e:\data\log

A. Prerequisites.

A.1. Installation of Ruby interpreter.

Ruby 1.8.7 should be used currently. This is applicable for Redmine 1.3.x. It seems that Redmine 1.4.x will be compatible with Ruby 1.9.2 but it is in the future yet.

Download link: http://rubyforge.org/frs/download.php/72085/rubyinstaller-1.8.7-p302.exe

This is an usual Windows setup wizard installer. Ruby executable path must be put in PATH= system variable. The related option should be set in the wizard dialog.

A submenu Ruby 1.8.7-p302 will appear in start menu.  Run ‘Interactive Ruby’ command from there. This way you will see if Ruby is installed properly.

A.2 RubyGems installation.

Execute gem command in a console window. If it does not proceed (file or command not found error) do the following:

Download http://rubyforge.org/frs/download.php/70697/rubygems-1.3.7.zip. Unzip the archive in a temporary folder, go there and execute ruby setup.rb in a console.

A.3 Ruby on Rails installation.

Execute the command:

gem install rails -v=2.3.14

Redmine 1.3.0 requires Rails 2.3.14, no any older.

A.4 Install rack.

Execute the command:

gem install rack -v=1.1.1 or
gem install rack -v=1.1.2

B. Redmine installation.

B.1 Redmine application.

Download Redmine from http://rubyforge.org/frs/?group_id=1850.

Unzip the archive in %REDMINE_ROOT%.

B2. MySQL database.

Create database:

create database redmine;
create user 'redmine'@'localhost' identified by 'redminepassword';
grant all privileges on redmine.* to 'redmine'@'localhost';

Copy %REDMINE_ROOT%\config\database.yml.example to %REDMINE_ROOT%\config\database.yml and edit it in the production section.

production:
  adapter: mysql
  database: redmine
  host: localhost
  username: redmine
  password: redminepassword
  encoding: utf-8

Go to %REDMINE_ROOT% and execute

rake generate_session_store

Install mysql gem:

gem install mysql

Execute

set RAILS_ENV=production
rake db:migrate
rake redmine:load_default_data

The second command may fail. If this happens download http://instantrails.rubyforge.org/svn/trunk/InstantRails-win/InstantRails/mysql/bin/libmySQL.dll and put it in the bin folder of Ruby installation, this way replacing the defective libmysql.dll. Then execute second command again and then third one.

B.3. Test.

The basic installation should be finished at this point. Go to %REDMINE_ROOT% and execute

ruby script\server –e production

In Firefox or MSIE, go to http://localhost:3000. You should see the main page of Redmine. You may log in with username admin and password admin.

Log in and create second user with administrative rights.

Stop Redmine and continue with installation.

B.4. Redmine mail service (SMTP server Configuration).

Open %REDMINE_ROOT%\config\configuration.yml and edit the email configuration in the production section.

production:
 # Outgoing emails configuration (see examples above)
 email_delivery:
   delivery_method: :smtp
   smtp_settings:
     address: "your.mail.server"
     port: 25
     domain: "your.domain"

The configuration depends on the actual requirements of your mail server and may differ from the above example. You should restart Redmine so as the configuration take effect.

Play for a while with settings in Administration panel and test if Redmine is able to send emails to you (the administrator).

C. Mongrel.

C.1. Mongrel gem.

The site of mongrel is http://rubyforge.org/projects/mongrel/.

Execute

gem install mongrel

The expected result is

Successfully installed gem_plugin-0.2.3
Successfully installed cgi_multipart_eof_fix-2.5.0
Successfully installed mongrel-1.1.5-x86-mingw32

C.2. Virtual host redmine.mycompany.com.

The definition of the virtual host is

<VirtualHost *:80>
    ServerName redmine.mycompany.com
    ServerAdmin admin@mycompany.com
    DocumentRoot e:/data/redmine/public              # %REDMINE_ROOT%/public
    DirectoryIndex index.html index.php
    Include e:/data/vhosts/httpd-proxy-mongrel.conf  # %VHOSTS_DIR%/httpd-proxy-mongrel.conf
    ErrorLog e:/data/log/redmine.error.log           # %LOGDIR%/redmine.error.log
    TransferLog e:/data/log/redmine.transfer.log     # %LOGDIR%/redmine.transfer.log
    AddDefaultCharset WINDOWS-1251                   # these two lines are optional
    AddCharset WINDOWS-1251 .cp-1251 .win-1251
 </VirtualHost>

This file must be included in Apache’s httpd.conf file in the section where virtual hosts are defined. Note that there is an Include directive for httpd-proxy-mongrel.conf in above definition. This file should be visible by Apache.

Contents of httpd_proxy_mongrel.conf:

# Redmine configuration behind Apache 2.2.x and mongrel
# Loading mod_proxy, mod_proxy_http and mod_proxy_balancer
<IfModule !mod_proxy.c>
    LoadModule proxy_module lib/modules/mod_proxy.so
</IfModule>
<IfModule !mod_proxy_http.c>
    LoadModule proxy_http_module lib/modules/mod_proxy_http.so
</IfModule>
<IfModule !mod_proxy_balancer.c>
    LoadModule proxy_balancer_module lib/modules/mod_proxy_balancer.so
</IfModule>
<Directory E:/data/redmine/public/>           # %REDMINE_ROOT%/public/
    Options Indexes FollowSymLinks MultiViews
    AllowOverride All
    Order deny,allow
    Deny from all
    Allow from 192.168.20
</Directory>
<Proxy *>
    Order Deny,Allow
    Deny from all
    Allow from 192.168.20
</Proxy>
ProxyPass / balancer://redmine_cluster/
ProxyPassReverse / balancer://redmine_cluster/
<Proxy balancer://redmine_cluster>
    BalancerMember http://redmine.mycompany.com:3001
    BalancerMember http://redmine.mycompany.com:3002
    BalancerMember http://redmine.mycompany.com:3003
</Proxy>

Note ports 3001, 3002, 3003 above. These ports should be the same in C.3 in the commands that install Mongrel services.

The file mongrel.rb is copied into %REDMINE_ROOT%\config\initializers\. This file is needed because Mongrel_rails service „–prefix“ does not work with Rails 2.3.x.

mongrel.rb may be downloaded from http://www.redmine.org/attachments/6901/mongrel.rb

Contents of mongrel.rb:

if ['2.3.8', '2.3.9', '2.3.10', '2.3.11', '2.3.12', '2.3.14'].include?(Rails.version) && Gem.available?('mongrel', '~>1.1.5') && self.class.const_defined?(:Mongrel)

  # Pulled right from latest rack. Old looked like this in 1.1.0 version.
  #
  # def [](k)
  #   super(@names[k] ||= @names[k.downcase])
  # end
  #
  module Rack
    module Utils
      class HeaderHash < Hash
        def [](k)
          super(@names[k]) if @names[k]
          super(@names[k.downcase])
        end
      end
    end
  end

  # Code pulled from the ticket above.
  #
  class Mongrel::CGIWrapper
    def header_with_rails_fix(options = 'text/html')
      @head['cookie'] = options.delete('cookie').flatten.map { |v| v.sub(/^\n/,'') } if options.class != String and options['cookie']
      header_without_rails_fix(options)
    end
    alias_method_chain :header, :rails_fix
  end

  # Pulled right from 2.3.8 ActionPack. Simple diff was
  #
  # if headers.include?('Set-Cookie')
  #   headers['cookie'] = headers.delete('Set-Cookie').split("\n")
  # end
  #
  # to
  #
  # if headers['Set-Cookie']
  #   headers['cookie'] = headers.delete('Set-Cookie').split("\n")
  # end
  #
  module ActionController
    class CGIHandler
      def self.dispatch_cgi(app, cgi, out = $stdout)
        env = cgi.__send__(:env_table)
        env.delete "HTTP_CONTENT_LENGTH"
        cgi.stdinput.extend ProperStream
        env["SCRIPT_NAME"] = "" if env["SCRIPT_NAME"] == "/"
        env.update({
          "rack.version" => [0,1],
          "rack.input" => cgi.stdinput,
          "rack.errors" => $stderr,
          "rack.multithread" => false,
          "rack.multiprocess" => true,
          "rack.run_once" => false,
          "rack.url_scheme" => ["yes", "on", "1"].include?(env["HTTPS"]) ? "https" : "http"
        })
        env["QUERY_STRING"] ||= ""
        env["HTTP_VERSION"] ||= env["SERVER_PROTOCOL"]
        env["REQUEST_PATH"] ||= "/"
        env.delete "PATH_INFO" if env["PATH_INFO"] == ""
        status, headers, body = app.call(env)
        begin
          out.binmode if out.respond_to?(:binmode)
          out.sync = false if out.respond_to?(:sync=)
          headers['Status'] = status.to_s
          if headers['Set-Cookie']
            headers['cookie'] = headers.delete('Set-Cookie').split("\n")
          end
          out.write(cgi.header(headers))
          body.each { |part|
            out.write part
            out.flush if out.respond_to?(:flush)
          }
        ensure
          body.close if body.respond_to?(:close)
        end
      end
    end
  end
end

The following line is added at the end of %REDMINE_ROOT%\redmine\config\environment.rb:

Redmine::Utils::relative_url_root = ""

C.3 Mongrel service.

Download win32-service version 0.5.2 from http://rubyforge.org/frs/?group_id=1306.

Download mongrel_service-0.3.4-i386-mswin32.gem from http://files.ruby.inoack.com/win32utils/

Put these files in some folder and execute in it

gem install mongrel_service

The expected result is

Successfully installed win32-service-0.5.2-x86-mswin32
Successfully installed mongrel_service-0.3.4-x86-mswin32
2 gems installed

Install Windows services:

mongrel_rails service::install -N mongrel_redmine_3001 -D "Mongrel serving Redmine on 3001" -p 3001 -e production -c e:\data\Redmine
mongrel_rails service::install -N mongrel_redmine_3002 -D "Mongrel serving Redmine on 3002" -p 3002 -e production -c e:\data\Redmine
mongrel_rails service::install -N mongrel_redmine_3003 -D "Mongrel serving Redmine on 3003" -p 3003 -e production -c e:\data\Redmine

Start services in Windows Control panel. Restart Apache.

In a browser, go to http://redmine.mycompany.com.

Enjoy!