Installing Redmine on Windows in production

This is a very simple step by step guide to install Redmine on Windows server in production. This guide is applicable to IIS 7+ based servers, which include Windows Server 2008, 2008 R2, Windows Vista and Windows 7. Latter two should not be used for production solutions. Please follow these steps:

1. Download Microsoft Web Platform Installer, and install it.

2. Run Web Platform Installer and click “Options”.

3. Add Helicon Zoo feed into “Display additional scenarios” field: http://www.helicontech.com/zoo/feed Select “IIS” as a target web server.

A new tab named “Zoo” should appear on the main page of Platform Installer.

4. Go to Zoo → Applications and add Redmine, then click install.

This will automatically download and install all required components, including Ruby 1.8.7, Rails 2.3, Helicon Zoo Module and Redmine itself.

5. Setup new web-site dialog will appear. Fill it with your server specific values.

6. Go to the /admin/ folder on this web-site. Use login “admin” and password “admin” to enter Redmine Administration panel.

When you install Redmine into a sub-directory additional configuration is required. Please open config/environment.rb file and add the following line at the bottom:

Redmine::Utils::relative_url_root = ENV[ 'APPL_VIRTUAL_PATH' ]

See http://www.redmine.org/projects/redmine/wiki/HowTo_Install_Redmine_in_a_sub-URI for more information.

Custom database

Redmine supports multiple database engines. By default SQLite is installed, however there are example configuration files for MySQL and PostgreSQL within “config” folder of Redmine application. If you wish to use MySQL, for an instance, take “database.yml.mysql” file; name it as “database.yml” and alter according to your MySQL database settings. Then restart IIS application which contains your Redmine application. All required database migrations will be executed automatically by deploy.rb script.

Manual installation

If you need to install some specific or modified version of Redmine here you can find manual installation instructions.

First you will need to run Web Platform Installer, go to Zoo –> Packages and install Ruby Hosting Package. This will install basic requirement to run Ruby Rack applications on IIS plus some useful modules. Create an empty IIS web site or application. Download and unpack Redmine package to the root folder of this IIS application. Official Redmine download page is here: http://www.redmine.org/projects/redmine/wiki/Download

Generic instructions how to run Ruby on Rails applications using Helicon Zoo can be found here: http://www.helicontech.com/zoo/usage/ruby-on-rails.htm

You can use generic web.config file example from this usage page as shown below:

web.config:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>

    <heliconZoo>
      <application name="rails.project" >
        <environmentVariables>
          <!-- 
          Deploy file includes the most common commands required to prepare application before launch (bundle install, migrations etc.)
          Redmine installation requires deploy file.
          -->
          <add name="DEPLOY_FILE" value="deploy.rb" />
          <add name="DEPLOY_LOG" value="log\zoo-deploy.log" />
          
          <!-- By default we run Rails in production mode -->
          <add name="RACK_ENV" value="development" />
        </environmentVariables>
      </application>
     </heliconZoo>


    <handlers>
      <!-- All transports below support Rails 2.3, 3.0 and 3.1 as well as any Rack-based application. Uncomment the one you wish to use. -->
      
      <!-- Ruby 1.9 over FastCGI -->
      <add name="rails.project#x86" scriptProcessor="ruby.1.9.rack" 
        path="*" verb="*" modules="HeliconZoo_x86" 
        preCondition="bitness32" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="rails.project#x64" scriptProcessor="ruby.1.9.rack"  
        path="*" verb="*" modules="HeliconZoo_x64" 
        preCondition="bitness64" resourceType="Unspecified" 
        requireAccess="Script" />

      <!-- Ruby 1.8 over FastCGI -->
      <!--
      <add name="rails.project#x86" scriptProcessor="ruby.1.8.rack" 
        path="*" verb="*" modules="HeliconZoo_x86" 
        preCondition="bitness32" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="rails.project#x64" scriptProcessor="ruby.1.8.rack"  
        path="*" verb="*" modules="HeliconZoo_x64" 
        preCondition="bitness64" resourceType="Unspecified" 
        requireAccess="Script" />
      -->

      <!-- Ruby 1.9 over HTTP, using Thin as a back-end application server -->
      <!--
      <add name="rails.project#x86" scriptProcessor="ruby.1.9.thin" 
        path="*" verb="*" modules="HeliconZoo_x86" 
        preCondition="bitness32" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="rails.project#x64" scriptProcessor="ruby.1.9.thin" 
        path="*" verb="*" modules="HeliconZoo_x64" 
        preCondition="bitness64" resourceType="Unspecified" 
        requireAccess="Script" />
      -->
    </handlers>


    <!-- Send static files through IIS -->
    <rewrite>
      <rules>

        <rule name="Rewrite to Zoo index if that's an empty application" stopProcessing="true">
          <match url=".?" ignoreCase="false" />
          <conditions logicalGrouping="MatchAll" trackAllCaptures="true">
            <add input="{APPL_PHYSICAL_PATH}" pattern="(.*)" ignoreCase="false" />
            <add input="{C:1}config\environment.rb" matchType="IsFile" negate="true" />
          </conditions>

          <action type="Rewrite" url="public\zoo-index.html" />
        </rule>

        <rule name="index" stopProcessing="true">
          <match url="^$" ignoreCase="false" />
          <conditions logicalGrouping="MatchAll" trackAllCaptures="true">
            <add input="{APPL_PHYSICAL_PATH}" pattern="(.*)" ignoreCase="false" />
            <add input="{C:1}public\index.html" matchType="IsFile" />
          </conditions>
          <action type="Rewrite" url="public/index.html" />
        </rule>

        <rule name="Static Files" stopProcessing="true">
          <match url="^(?!public)(.*)$" ignoreCase="false" />
          <conditions logicalGrouping="MatchAll" trackAllCaptures="true">
            <add input="{APPL_PHYSICAL_PATH}" pattern="(.*)" ignoreCase="false" />
            <add input="{C:1}public\{R:1}" matchType="IsFile" />
          </conditions>
          <action type="Rewrite" url="public/{R:1}" />
        </rule>

        <rule name="Rails 3.1 assets" stopProcessing="true">
          <match url="^assets/(.*)$" ignoreCase="true" />
          <conditions logicalGrouping="MatchAll" trackAllCaptures="true">
            <add input="{APPL_PHYSICAL_PATH}" pattern="(.*)" ignoreCase="false" />
            <add input="{C:1}app\assets\{R:1}" matchType="IsFile" />
          </conditions>
          <action type="Rewrite" url="app/assets/{R:1}" />
        </rule>
        
      </rules>    
    </rewrite>

  </system.webServer>
</configuration>

It is recommended to install Microsoft URL Rewriter in order to activate rules for processing static files with IIS. This may significantly improve performance of your Redmine application.

You will need to uncomment lines that configure deploy file execution, as Redmine installation implies running of deploy file. Generic deploy file, available on Ruby on Rails usage page will not work with Redmine. Please use this deploy.rb file instead:

deploy.rb:

require 'rbconfig'

APP_ROOT = File.dirname( __FILE__ ).freeze
RUBY_BIN = RbConfig::CONFIG[ 'bindir' ].freeze
RACK_ENV = ( ENV[ 'RACK_ENV' ] || 'production' ).freeze

Dir.chdir( APP_ROOT )

def deploy( env, &block )
  ENV[ 'REDMINE_LANG' ] = 'en'
  return unless RACK_ENV == env.to_s
  block.call
end


def run( task, wrap = true )
  args = task.split
  cmd = args.shift

  ARGV.clear
  ARGV.unshift( *args )

  # We use 'load' because it doesn't spawn child ruby process,
  # which might be problematic in hosting environment.
  exe = File.join( RUBY_BIN, cmd )
  puts ">> #{exe} #{ARGV.inspect}"
  load( exe, wrap )
rescue Errno::EACCES => e
  puts 'Insufficient file system permissions.' +
    'Please make sure IIS application pool user has enough rights to access application files.' +
    "Usually Write permission isn't granted where it's needed. Exception: #{e}"
rescue Object => e
  puts e.to_s
  # Deploy tries to run all tasks. Some exceptions aren't relevant. See log if it matters.
end


deploy :development do
	run 'bundle install --path vendor/gems --without rmagick'

	run 'rake generate_secret_token'
	run 'rake db:create'
	run 'rake db:migrate'
	run 'rake redmine:load_default_data'

	# TODO: add more development tasks here
end


deploy :production do
	run 'bundle install --path vendor/gems --without development test rmagick'

	run 'rake generate_secret_token'
	run 'rake RAILS_ENV=production db:create'
	run 'rake RAILS_ENV=production db:migrate'
	run 'rake RAILS_ENV=production redmine:load_default_data'	

	# TODO: add more production tasks here
end

Now we need to set up database for use with Redmine. You can follow recommendations to create database on this official page: http://www.redmine.org/projects/redmine/wiki/RedmineInstall

The simplest way is to use SQLite as a database. To use it you just need to create a config\database.yml file in the Redmine installation with the following content:

config\database.yml:

# SQLite version 3.x
development:
  adapter: <%= "jdbc" if defined?(JRUBY_PLATFORM) %>sqlite3
  database: db/development.sqlite3
  timeout: 5000

# Warning: The database defined as 'test' will be erased and
# re-generated from your development database when you run 'rake'.
# Do not set this db to the same as development or production.
test:
  adapter: <%= "jdbc" if defined?(JRUBY_PLATFORM) %>sqlite3
  database: db/test.sqlite3
  timeout: 5000

# Warning: The database defined as 'cucumber' will be erased and
# re-generated from your development database when you run 'rake'.
# Do not set this db to the same as development or production.
cucumber:
  adapter: <%= "jdbc" if defined?(JRUBY_PLATFORM) %>sqlite3
  database: db/cucumber.sqlite3
  timeout: 5000

production:
  adapter: <%= "jdbc" if defined?(JRUBY_PLATFORM) %>sqlite3
  database: db/production.sqlite3
  timeout: 5000

Now you can point your browser to the IIS web application with Redmine installed. First start may take time as it will run deployment process, which may include components download, database initialization and other time consuming operations.

That’s it, enjoy!