Prerequisites

This document will guide you through the installation process of Redmine and all of its prerequisites, including the optional ones. If desired, however, you may install Redmine and its prerequisites separately, simply referring to the relevant sections below.

Although this guide will go through the entire installation process, this is not a one way path. Redmine can use different versions of the requisite software. For example the database requirement can be provided by mariaDB, mySQL, postgreSQL, etc.

Note: This guide is a default suggestion, feel free to substitute any of the prerequisites mentioned on this page.

Ruby

Redmine version

Supported Ruby Versions

Rails version used

3.0.2

ruby 1.9.33, 2.0.02, 2.1, 2.21

Rails 4.20

There are two simple ways to install Ruby: installing the ruby package as described in ruby or installing RVM as described in RVM(recommended).

Warning: If you use RVM, pay attention to the single and multiple user differences! If you are not creating a hosting service, the multiple user (available for all users on the machine) should be the choice for simpler debuging.

And then edit this file in order to configure your database settings for "production" environment (you can configure for the "development" and "test" environments too, just change the appropriate sections).

Ruby gems

Redmine requires some RubyGems to be installed and there are multiple ways of installing them (as listed on the referenced page).

prototype-rails

unicorn (an application-server)

mysql2 (high-performance Ruby bindings for MySQL)

coderay

erubis

fastercsv

rdoc

net-ldap

rack-openid

Obviously, if you choose a different database-server, or want to use a different application-server you should replace mysql2 and unicorn to your liking.

Adding Additional Gems (Optional)

If you need to load gems that are not required by Redmine core (eg. Puma, fcgi), create a file named Gemfile.local at the root of your redmine directory. It will be loaded automatically when running bundle install:

# nano Gemfile.local

gem 'puma'

Check previously installed gems

The Redmine devs included Bundler in Redmine, which can manage Gems just like pacman manages packages. Run the following command to assure that all Redmine dependencies are met:

# bundle install --without development test

This should output a list of gems Redmine needs.

Gems Installation

Note: If you prefer, you can install all the gems as pacman packages. You have only to search for the gem package and install them as usual. As of using Ruby gem is much simpler to manage and maintain up to date gems, this will be preferable and used as default bellow.

Then you can install all the gems required by Redmine using the following command:

# cd /usr/share/webapps/redmine
# bundle install

To install without the ruby development and test environments use this instead of the last command:

# bundle install --without development test

Note: You can include/exclude environments using the above syntax.

Although imagemagick is highly recommended, if you do not use it, you should skip the installation of the rmagick gem using:

# bundle install --without rmagick

Note: Only the gems that are needed by the adapters you have specified in your database configuration file are actually installed (eg. if your config/database.yml uses the mysql2 adapter, then only the mysql2 gem will be installed). Do not forget to re-run bundle install when you change or add adapters in this file.

Session Store Secret Generation

Now you must generate a random key that will be used by Rails to encode cookies that stores session data thus preventing their tampering:

These command will create tables by running all migrations one by one then create the set of the permissions and the application administrator account, named admin.

Database Population with Default Data

Now you may want to insert the default configuration data in database, like basic types of task, task states, groups, etc. To do so execute the following:

# RAILS_ENV=production bundle exec rake redmine:load_default_data

Redmine will prompt for the data set language that should be loaded; you can also define the REDMINE_LANG environment variable before running the command to a value which will be automatically and silently picked up by the task:

Test the installation

To test your new installation using WEBrick web server run the following in the Redmine folder:

# ruby bin/rails server webrick -e production

Once WEBrick has started, point your browser to http://localhost:3000/. You should now see the application welcome page. Use default administrator account to log in: admin/admin. You can go to Administration menu and choose Settings to modify most of the application settings.

Warning: Webrick is not suitable for production use, please only use webrick for testing that the installation up to this point is functional. Use one of the many other guides in this wiki to setup redmine to use either Passenger (aka mod_rails), FCGI or a Rack server (Unicorn, Thin, Puma or hellip) to serve up your redmine.

Configure the production server

For Apache and Nginx, it is recommended to use Phusion Passenger. Passenger, also known as mod_rails, is a module available for Nginx and Apache.

Start by installing the 'passenger' gem:

# gem install passenger

Now you have to look at your passenger gem installation directory to continue. If you do not known where it is, type:

# gem env

And look at the GEM PATHS to find where the gems are installed. If you followed this guide and installed RVM, you can have more than one path, look at the one you are using.

For this guide so far, the gem path is /usr/local/rvm/gems/ruby-2.0.0-p247@global.

And finally, the installer will provide you with further information regarding the installation (such as installing additional libraries). So, to setup your server, simply follow the output from the passenger installer.

Warning: The command above will delete ALL the gems in your system or user, depending of what type of Ruby installation you did in the prerequisites step. You must take care or you can stop working another applications that rely on Ruby gems.

If you did the last step and removed all the gems, now you will need to reinstall them all:

# gem install bundler
# bundle install --without development test

Note: If you removed ALL the gems as above, and used a server that uses a gem, remember to reinstall the server gem: passenger (for Apache and Nginx), Mongrel or Unicorn. To do this, just follow the steps in the installation tutorial above.

Note: It will show some complains like unable to convert "\xE0" from ASCII-8BIT to UTF-8 for ext/RMagick/RMagick2.so, skipping, but you can safelly ignore it.

Runtime error complaining that RMagick was configured with older version

If you get the following runtime error after upgrading ImageMagick This installation of RMagick was configured with ImageMagick 6.8.7 but ImageMagick 6.8.8-1 is in use. then you only need to reinstall (or rebuild as shown above if is the case).

Note: This is due to that when you install the RMagick gem it compiles some native extensions and they may need to be rebuilt after some ImageMagick upgrades.

OpenSSL error about "SSLv3_client"

After thel latest OpenSSL release (version 1.0.2.g-3) the ruby stop to work and you cannot build some ruby versions. You have two way to fix it:

1. Use ruby-head (if using RVM) or 2.3.0or above (if using Arch package).

Error when installing gems: Cannot load such file -- mysql2/mysql2

If you see an error like cannot load such file -- mysql2/mysql2, you are having a problem with the installation of the database gem. Probably a misconfiguration in the Database Access Configuration step.
In this case you should verify the database.yml file.

If no success, you can manually install the database gem by:

# gem install mysql2

In last case, as suggested by Bobdog, you can try to comment the line of the database gem and add a new one as bellow: