Redmine

h1. Installing Redmine

{{>TOC}}

h2. Requirements

h3. Operating system

Redmine should run on most Unix, Linux, Mac and Windows systems as long as Ruby is available on this platform.

h3. Ruby & Ruby on Rails

The required Ruby and Ruby on Rails versions for a given Redmine version is:

*(BUT: if you download the packaged distribution .zip file, the correct Rails version is INCLUDED and you have not to worry about this - just learned that this can be confusing for people less experienced with rails and the vendor libs by seing a colleague having problems...)*

|_. Redmine version|_. Supported Ruby versions|_. Required Rails version|_. Required Rack version|

|current trunk|ruby 1.8.6, 1.8.7|Rails 2.3.5|Rack 1.0.1|

|trunk from r2493 to r2886|ruby 1.8.6, 1.8.7|Rails 2.2.2||

|trunk before r2493|ruby 1.8.6, 1.8.7|Rails 2.1.2||

|0.9.x|ruby 1.8.6, 1.8.7|Rails 2.3.5|Rack 1.0.1|

|0.8.x|ruby 1.8.6, 1.8.7|Rails 2.1.2||

|0.7.x|ruby 1.8.6|Rails 2.0.2||

Official releases include the appropriate Rails version in their @vendor@ directory. So no particular action is needed.

If you checkout the source from the Redmine repository, you can install a specific Rails version on your machine by running:

  gem install rails -v=2.3.5

Notes:

* RubyGems 1.3.1 is required

* Rake 0.8.3 is required

h3. Database

* MySQL 4.1 or higher (recommended)

 * make sure to install the C bindings for Ruby that dramatically improve performance. You can get them by running @gem install mysql@.

 * the Ruby MySQL gem currently does not support MySQL 5.1

* PostgreSQL 8

 * make sure your database datestyle is set to ISO (Postgresql default setting). You can set it using: @ALTER DATABASE "redmine_db" SET datestyle="ISO,MDY";@

 * some bugs in PostgreSQL 8.4.0 and 8.4.1 affect Redmine behaviour (#4259, #4314), they are fixed in PostgreSQL 8.4.2

 * make sure to install the PosgreSQL adapter for Ruby. You can get it by running (**one** of the following):

 **  @gem install postgres-pr@

 **  @gem install pg@ (works with SSL connections, may need development libraries/packages for your OS before it will compile)

 *** Ubuntu OS: development libraries can be installed with (or similiar): @sudo aptitude install libdbd-pg-ruby1.8@

* SQLite 3

h3. Optional components

      * SCM binaries (eg. @svn@), for repository browsing (must be available in your PATH). See [[RedmineRepositories]] for SCM compatibility and requirements.

      * "RMagick":http://rmagick.rubyforge.org/ (to enable Gantt export to png image)

      * "Ruby OpenID Library":http://openidenabled.com/ruby-openid/ (to enable OpenID support) [only on Redmine trunk / 0.9-dev]  Version 2 or greater is required.

h2. Installation

1. [[Download]] and extract the archive or [[CheckingoutRedmine|checkout]] Redmine.

2. Create an empty database and accompanying user named @redmine@ for example.

For MySQL:

<pre>

create database redmine character set utf8;

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

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

</pre>

For PostgreSQL:

<pre>

CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD 'my_password' NOINHERIT VALID UNTIL 'infinity';

CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;

</pre>

3. Copy @config/database.yml.example@ to @config/database.yml@ and edit this file in order to configure your database settings for "production" environment.

Example for a MySQL database:

<pre>

production:

  adapter: mysql

  database: redmine

  host: localhost

  username: redmine

  password: my_password

</pre>

If your server is not running on the standard port (3306), use this configuration instead:

<pre>

production:

  adapter: mysql

  database: redmine

  host: localhost

  port: 3307

  username: redmine

  password: my_password

</pre>

Example for a PostgreSQL database (default port):

<pre>

production:

  adapter: postgresql

  database: <your_database_name>

  host: <postgres_host>

  username: <postgres_user>

  password: <postgres_user_password>

  encoding: utf8

  schema_search_path: <database_schema> (default - public)

</pre>

4. Generate a session store secret. This is required on the *trunk* version of Redmine at r2493 or above and the released 0.8.7 version or above.

Redmine stores session data in cookies by default, which requires a secret to be generated. This can be done by running:

   RAILS_ENV=production rake config/initializers/session_store.rb

If you're using an SVN version of Redmine post r3055, the above file will no longer exist; it was deprecated as of r3054.  On these versions, run

   rake generate_session_store

5. Create the database structure, by running the following command under the application root directory:

  RAILS_ENV=production rake db:migrate

It will create tables and an administrator account.

6. Insert default configuration data in database, by running the following command:

  RAILS_ENV=production rake redmine:load_default_data

This step is optional but *highly recommended*, as you can define your own configuration from scratch. It will load default roles, trackers, statuses, workflows and enumerations.

7. Setting up permissions

NB: _Windows users have to skip this section._

The user who runs Redmine must have write permission on the following subdirectories: @files@, @log@, @tmp@ (create the last one if not present).

Assuming you run Redmine with a @redmine@ user:

<pre>

mkdir tmp public/plugin_assets

sudo chown -R redmine:redmine files log tmp public/plugin_assets

sudo chmod -R 755 files log tmp public/plugin_assets

</pre>

8. Test the installation by running WEBrick web server:

  ruby script/server webrick -e production

Once WEBrick has started, point your browser to http://localhost:3000/. You should now see the application welcome page.

9. Use default administrator account to log in:

    * login: admin

    * password: admin

You can go to @Admin & Settings@ to modify application settings.

h2. SMTP server Configuration

Copy @config/email.yml.example@ to @config/email.yml@ and edit this file to adjust your SMTP settings.

See the [[Email Configuration|email configuration]] examples.

Don't forget to restart the application after any change.

h2. Backups

Redmine backups should include:

* data (stored in your redmine database)

* attachments (stored in the @files@ directory of your Redmine install)

Here is a simple shell script that can be used for daily backups (assuming you're using a mysql database):

<pre>

# Database

/usr/bin/mysqldump -u <username> -p<password> <redmine_database> | gzip > /path/to/backup/db/redmine_`date +%y_%m_%d`.gz

# Attachments

rsync -a /path/to/redmine/files /path/to/backup/files

</pre>

h2. Notes on Windows installation

Get and install rubyinstaller from http://rubyforge.org. Form start menu select _Start Command Prompt with Ruby_

In the prompt follow the instruction given before

The commands:

<pre>

RAILS_ENV=production rake db:migrate

RAILS_ENV=production rake redmine:load_default_data

</pre>

has to be changed in 

<pre>

set RAILS_ENV=production

rake db:migrate

rake redmine:load_default_data

</pre>  

You may need to install install the mysql gem, with the command

<pre>

gem install mysql

</pre>

And in some case is required to copy the libmysql.dll file in your ruby/bin directory.

Not all libmysql.dll are ok this seem to works http://instantrails.rubyforge.org/svn/trunk/InstantRails-win/InstantRails/mysql/bin/libmySQL.dll

h2. Alternative to manual installation

Some users may prefer to skip manual installation by using one of the [[Download#Third-party-Redmine-bundles|third-party Redmine bundles]] on the download page.