Redmine

h1. HowTo Install Redmine in a sub-URI on Windows with Apache

{{>toc}}

bq. Following the steps below exactly as listed will produce a working *Redmine 0.8.7* installation hosted under *http://localhost/redmine* sub-URI on Windows XP/2003/2008 x86/x64 with Apache HTTP Server 2.2.x, MySQL 5.1.x and Ruby 1.8.7.

This walk-through also applies to installation of the latest Redmine revision. It was tested with *Redmine revision r3255 (version 0.9)* after updating Rails to version 2.3.5.

The intended audience for this walk-through are Windows users.

h2. Install Apache HTTP server 2.2.x

# Download *Win32 Binary* with or without crypto (depending if you need SSL) from "here":http://httpd.apache.org/download.cgi

# Install to C:\webserver\apache

h2. Install MySQL 5.1.x

# Download *Windows Essentials (x86)* from "here":http://dev.mysql.com/downloads/mysql/5.1.html#win32

#* _x64 version could be used for x64 Windows installations, but the x86 version works well on all Windows versions and is recommended._

# Install to C:\webserver\MySQL

#* (_optional:_) Set data files installation directory to C:\webserver\MySQLData

h2. Install MySQL GUI Tools for MySQL 5.0

# Download *Windows (x86) Installer* from "here":http://dev.mysql.com/downloads/gui-tools/5.0.html

# Install to C:\webserver\MySQL_GUI_Tools

h2. Install Ruby 1.8.7

* _At the time of writing this document the latest version of Ruby was 1.9.1 which does *NOT* work with Redmine_

* *+Use Ruby version 1.8.7 only+*.

* Since there is no installer package for 1.8.7, we will first install 1.8.6 then copy 1.8.7 binaries on top of it.

# Download "rubyinstaller-1.8.6-p383-rc1.exe" from "here":http://rubyforge.org/frs/?group_id=167

# Install to C:\webserver\ruby

# Open command window, then execue: <pre>

mkdir C:\webserver\railsapps

cd C:\webserver\railsapps

gem list

gem uninstall rails

gem uninstall actionmailer

gem uninstall actionpack

gem uninstall activerecord

gem uninstall activeresource

gem uninstall activesupport

</pre>

# Download *Ruby 1.8.7-p72 Binary* "ruby-1.8.7-p72-i386-mswin32.zip" from "here":http://www.ruby-lang.org/en/downloads/

# Extract the archive contents to C:\webserver\ruby overwritting the 1.8.6 version

# _Add "C:\webserver\ruby\bin" to your PATH environment variable if not already included_

# Download the zlib package from "here":http://www.zlib.net/zlib123-dll.zip

## extract the zlib1.dll

## rename it to zlib.dll

## move it to C:\webserver\ruby\bin

# Download the iconv package from "here":http://sourceforge.net/project/showfiles.php?group_id=25167&package_id=51458

## extract iconv.dll

## move it to C:\webserver\ruby\bin

# Verify Ruby version

## in command window, execute: <pre>

ruby -v

</pre>

##* expected output:<pre>

ruby 1.8.7 (2008-08-11 patchlevel 72) [i386-mswin32]

</pre>

h2. Install RubyGems

* _At the time of writting this document the latest version of RubyGems was 1.3.5. Newer versions should work too._

# Download "rubygems-1.3.5.zip" from "here":http://rubyforge.org/frs/?group_id=126

# Extract the package to C:\webserver\railsapps

# Install Ruby Gems

## in command window, execute: <pre>

cd C:\webserver\railsapps\rubygems-1.3.5

ruby setup.rb

</pre>

##* expected output:<pre>

RubyGems 1.3.5 installed

</pre>

## in command window, execute: <pre>

cd ..

gem update --system

</pre>

h2. Additional gems

* _mongrel-service and win32-service gems have to be downloaded manually. Download locations are added to sections below._

h3. Install Rake

* _At the time of writting this document the latest version of Rake was 0.8.7. Newer versions should work too._

# Install Rake gem

## in command window, execute: <pre>

gem install rake</pre>

##* expected output:<pre>

Successfully installed rake-0.8.7

</pre>

h3. Install Rails

* _At the time of writting this document the latest version of Rails was 2.3.5 which does *NOT* work with Redmine 0.8.7_

* *Use Rails version 2.1.2 for Redmine 0.8.7 deployment.*

* *Use Rails version 2.3.5 for Redmine revision >= r3235  deployment.*

* _Procedure below assumes we will be installing Redmine 0.8.7_

# Install Rails gems

## in command window, execute: <pre>

gem install rails -v=2.1.2

</pre>

##* expected output:<pre>

Successfully installed activesupport-2.1.2

Successfully installed activerecord-2.1.2

Successfully installed actionpack-2.1.2

Successfully installed actionmailer-2.1.2

Successfully installed activeresource-2.1.2

Successfully installed rails-2.1.2

</pre>

h3. Install Mongrel

* _At the time of writting this document the latest version of Mongrel was 1.1.5. Newer versions should work too._

* "_Project page_":http://rubyforge.org/projects/mongrel/

# Install Mongrel gems

## in command window, execute: <pre>

gem install mongrel

</pre>

##* expected output:<pre>

Successfully installed gem_plugin-0.2.3

Successfully installed cgi_multipart_eof_fix-2.5.0

Successfully installed mongrel-1.1.5-x86-mswin32-60

</pre>

h3. Install mysql gem

* _At the time of writting this document the latest version of mysql gem was 2.8.1. Newer versions should work too._

* It drastically improves page generation speed.

# Install mysql gem

## in command window, execute: <pre>

gem install mysql

</pre>

##* expected output:<pre>

Successfully installed mysql-2.8.1

</pre>

h3. Install mongrel-service + win32-service gems

* _At the time of writting this document the latest version of win32-service was 0.7 which does *NOT* work with Ruby 1.8.7_

* *Use only win32-service version 0.5.2 for Redmine deployment.*

# Download mongrel-service 0.3.4 ("project page":http://rubyforge.org/frs/?group_id=1306)

# Move mongrel_service-0.3.4-i386-mswin32.gem to C:\webserver\railsapps

# Download win32-service 0.5.2 from "HERE":http://files.ruby.inoack.com/win32utils/win32-service-0.5.2-mswin32.gem

# Move win32-service-0.5.2-mswin32.gem to C:\webserver\railsapps

# Install the gem

## in command window, execute: <pre>

cd C:\webserver\railsapps

gem install mongrel_service

</pre>

##* expected output:<pre>

Successfully installed gem win32-service-0.5.2-mswin32

Successfully installed gem mongrel_service-0.3.4-i386-mswin32

</pre>

h2. Install Redmine

* _Procedure below assumes we will be installing Redmine 0.8.7, but it also works with revision >= r3235_

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

# Extract the archive to C:\webserver\railsapps\redmine

# Log into MySQL using GUI Tools as "root"

#* Open a new script tab and execute the following script: <pre>

create database redmine character set utf8;

create user 'redmine'@'localhost' identified by 'my_password';

grant all privileges on redmine.* to 'redmine'@'localhost';

</pre>

# Copy C:\webserver\railsapps\redmine\config\database.yml.example to C:\webserver\railsapps\redmine\config\database.yml

# Edit "config\database.yml" file in order to configure your database settings for "production" environment.

#* set hostname, username and password to the velues entered in the SQL script above.

#* save and close the file.

# Create default tables and populate with data

## in command window, execute: <pre>

cd redmine

rake config\initializers\session_store.rb

set RAILS_ENV=production

rake db:migrate

rake redmine:load_default_data

</pre>

# _Procedure below assumes we will be hosting Redmine under http://localhost/redmine:_

# Edit "config\environment.rb" file in order to configure Redmine to work as a sub-URI (Apache configuration listed below).

#* _This is a preferred way of setting up the application prefix. *Mongrel_rails service "--prefix" directive does +NOT+ work with Rails 2.3.x*_

#* add the following line at the bottom of the file:<pre>

Redmine::Utils::relative_url_root = "/redmine" 

</pre>

#* save and close the file.

h2. Setup windows services

# Create windows services

## in command window, execute: <pre>

mongrel_rails service::install -N mongrel_redmine_3001 -D "Mongrel serving Redmine on 3001" -p 3001 -e production -c C:\webserver\railsapps\redmine

mongrel_rails service::install -N mongrel_redmine_3002 -D "Mongrel serving Redmine on 3002" -p 3002 -e production -c C:\webserver\railsapps\redmine

mongrel_rails service::install -N mongrel_redmine_3003 -D "Mongrel serving Redmine on 3003" -p 3003 -e production -c C:\webserver\railsapps\redmine

</pre>

# Start windows services, which in turn will start mongrel servers

## in command window, execute: <pre>

net start mongrel_redmine_3001

net start mongrel_redmine_3002

net start mongrel_redmine_3003

</pre>

# Go to the Windows Services list and set all "Mongrel serving Redmine on 300#" services to start automatically

## in command window, execute: <pre>

services.msc /s

</pre>

h2. Configure Apache 2.2.x as proxy to Mongrel cluster

* _Procedure below assumes we will be hosting Redmine under http://localhost/redmine:_

# Open C:\webserver\apache\conf\httpd.conf

# At the bottom of this file add the following line: <pre>

Include conf/httpd-proxy-mongrel.conf

</pre>

# Create a file C:\webserver\apache\conf\httpd-proxy-mongrel.conf

# Enter the following: <pre>

LoadModule proxy_module modules/mod_proxy.so

LoadModule proxy_http_module modules/mod_proxy_http.so

LoadModule proxy_balancer_module modules/mod_proxy_balancer.so

ProxyPass /redmine balancer://redmine_cluster

ProxyPassReverse /redmine balancer://redmine_cluster

<Proxy balancer://redmine_cluster>

	BalancerMember http://127.0.0.1:3001

	BalancerMember http://127.0.0.1:3002

	BalancerMember http://127.0.0.1:3003

</Proxy>

</pre>

# Restart the apache service.

*+DONE!+*

h3. Apendix

* Check if you have all the necessary gems installed for Redmine 0.8.7

** in command window, execute: <pre>

gem list

</pre>

*** expected output:<pre>

actionmailer (2.1.2)

actionpack (2.1.2)

activerecord (2.1.2)

activeresource (2.1.2)

activesupport (2.1.2)

cgi_multipart_eof_fix (2.5.0)

gem_plugin (0.2.3)

mongrel (1.1.5)

mongrel_service (0.3.4)

mysql (2.8.1)

rails (2.1.2)

rake (0.8.7)

win32-service (0.5.2)

</pre>

* Check if you have all the necessary gems installed for Redmine revision r3235 +

** in command window, execute: <pre>

gem list

</pre>

*** expected output:<pre>

actionmailer (2.3.5)

actionpack (2.3.5)

activerecord (2.3.5)

activeresource (2.3.5)

activesupport (2.3.5)

cgi_multipart_eof_fix (2.5.0)

gem_plugin (0.2.3)

mongrel (1.1.5)

mongrel_service (0.3.4)

mysql (2.8.1)

rack (1.0.1)

rails (2.3.5)

rake (0.8.7)

win32-service (0.5.2)

</pre>