Difference between revisions of "Redmine"

From ArchWiki
Jump to: navigation, search
(→‎Stub)
(→‎Configure Redmine)
(30 intermediate revisions by 2 users not shown)
Line 33: Line 33:
 
</tr>
 
</tr>
 
<tr>
 
<tr>
−
<td rowspan="2">2.2.3</td>
+
<td rowspan="2">2.3.0</td>
−
<td>ruby 1.8.7, 1.9.2, 1.9.3</td>
+
<td>ruby 1.8.7, 1.9.2, 1.9.3, 2.0.0</td>
−
<td rowspan="2">Rails 3.2.12</td>
+
<td rowspan="2">Rails 3.2.13</td>
 
<td rowspan="2">RubyGems <= 1.8</td>
 
<td rowspan="2">RubyGems <= 1.8</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
−
<td>jruby-1.6.7</td>
+
<td>jruby 1.6.7, 1.7.2</td>
 
</tr>
 
</tr>
 
</table>
 
</table>
Line 54: Line 54:
  
 
To install {{Pkg|mariadb}} simply refer to [[MariaDB]].
 
To install {{Pkg|mariadb}} simply refer to [[MariaDB]].
−
 
−
And make sure to install the C bindings for Ruby that dramatically improve performance. You can get them by running:
 
−
# gem install mysql2
 
  
 
====MySQL 5.0 or higher====
 
====MySQL 5.0 or higher====
 
To install {{Pkg|mysql}} simply refer to [[MySQL]].
 
To install {{Pkg|mysql}} simply refer to [[MySQL]].
−
 
−
And make sure to install the C bindings for Ruby that dramatically improve performance. You can get them by running:
 
−
# gem install mysql2
 
  
 
====PostgreSQL 8.2 or higher====
 
====PostgreSQL 8.2 or higher====
Line 74: Line 68:
  
 
====Microsoft SQL Server====
 
====Microsoft SQL Server====
−
Support is planned for 2.3.0 release (but is already available on trunk for early adopters).
+
{{Warning|Support is temporarily broken (with ruby 2.0.0 under Windows because of database adapter gems incompatibilities).}}
  
 
====SQLite 3====
 
====SQLite 3====
 
Not supported for multi-user production use. So, it will not be detailed how to install and configure it for use with Redmine.
 
Not supported for multi-user production use. So, it will not be detailed how to install and configure it for use with Redmine.
 +
 +
{{Warning|Support is temporarily broken (with ruby 2.0.0 under Windows because of database adapter gems incompatibilities).}}
  
 
===Web Server===
 
===Web Server===
Line 120: Line 116:
 
Download the package {{AUR|redmine}} from the [[Arch User Repository|AUR]].
 
Download the package {{AUR|redmine}} from the [[Arch User Repository|AUR]].
  
−
{{Note|It's '''HIGHLY''' recommended to read all the [[Arch User Repository|AUR]] page to understand what are you doing. Although nothing dangerous are being done, it doesn't hurt to read this.}}
+
{{Note|Detailed build instructions at [[Arch User Repository#Build the package]]. It's '''HIGHLY''' recommended to read all the [[Arch User Repository|AUR]] page to understand what are you doing. }}
  
−
 
+
===Database Configuration===
−
Build the package as follow (more detailed build instructions at [[Arch User Repository#Build the package]]).
 
−
 
 
−
Enter the folder that you are using to build packages, unpack the file and enter the package folder:
 
−
 
 
−
$ cd ~/builds
 
−
$ tar -zxvf redmine-2.2.3.tar.gz
 
−
$ cd redmine-2.2.3
 
−
 
 
−
Inspect the [[PKGBUILD]] file, to certify that is everything ok:
 
−
$ nano PKGBUILD
 
−
 
 
−
And then, build the package:
 
−
$ makepkg -s
 
−
 
 
−
{{Warning|Never run the above command using the {{ic|root}} user!}}
 
−
 
 
−
Then install the built package using pacman:
 
−
# pacman -U redmine-2.2.3-1-any.pkg.tar.xz
 
−
 
 
−
 
 
−
===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 simpler to mange and maintain up to date gems, this will be preferable and used as default bellow.}}
 
−
 
 
−
Redmine uses Bundler to manage gems dependencies. So, you need to install Bundler first:
 
−
# gem install bundler
 
−
 
 
−
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
 
−
 
 
−
To install only the gem of the database you are using (example, only using {{Pkg|mariadb}}), use this command instead:
 
−
# bundle install --without development test postgresql sqlite
 
−
 
 
−
{{Note|You can include/exclude environments and databases using the above syntax.}}
 
−
 
 
−
Although it is highly recommend to enjoy all the features of Redmine, if you really does not want to use {{Pkg|ImageMagick}}, you should skip the installation of the {{ic|rmagick}} gem using:
 
−
 
 
−
# bundle install --without rmagick
 
−
 
 
−
===Additional Gems===
 
−
If you need to load gems that are not required by Redmine core (eg. Puma, fcgi), create a file named {{ic|Gemfile.local}} at the root of your redmine directory. It will be loaded automatically when running bundle install:
 
−
 
 
−
{{hc|# nano Gemfile.local|
 
−
gem 'puma'}}
 
−
 
 
−
==Database Configuration==
 
  
 
Now, we will need to create the database that the Redmine will use to store your data. For now on, the database and its user will be named {{ic|redmine}}. But this names can be changed to anything else.
 
Now, we will need to create the database that the Redmine will use to store your data. For now on, the database and its user will be named {{ic|redmine}}. But this names can be changed to anything else.
  
 
{{Note|The configuration for [[MariaDB]] and [[MySQL]] will be the same since both are binary compatible.}}
 
{{Note|The configuration for [[MariaDB]] and [[MySQL]] will be the same since both are binary compatible.}}
 +
 +
====Database Creation====
  
 
To create the database, the user and set privileges (MariaDB and MySQL >= 5.0.2):
 
To create the database, the user and set privileges (MariaDB and MySQL >= 5.0.2):
−
{{bc|create database redmine character set utf8;
+
{{hc|# mysql -u root -p|
−
create user 'redmine'@'localhost' identified by 'my_password';
+
CREATE DATABASE redmine CHARACTER SET UTF8;
−
grant all privileges on redmine.* to 'redmine'@'localhost';}}
+
CREATE USER 'redmine'@'localhost' IDENTIFIED BY 'my_password';
 +
GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';}}
  
 
For versions of MariaDB and MySQL prior to 5.0.2:
 
For versions of MariaDB and MySQL prior to 5.0.2:
−
{{bc|create database redmine character set utf8;
+
{{hc|# mysql -u root -p|
−
grant all privileges on redmine.* to 'redmine'@'localhost' identified by 'my_password';}}
+
CREATE DATABASE redmine CHARACTER SET UTF8;
 +
GRANT ALL PRIVILEGES ON redmine.* TO'redmine'@'localhost' IDENTIFIED BY 'my_password';}}
  
 
For PostgreSQL:
 
For PostgreSQL:
 
{{bc|1=CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD 'my_password' NOINHERIT VALID UNTIL 'infinity';
 
{{bc|1=CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD 'my_password' NOINHERIT VALID UNTIL 'infinity';
 
CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;}}
 
CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;}}
 +
 +
For SQLServer:
 +
 +
Although the database, login and user can be created within SQL Server Management Studio with a few clicks, you can always use the command line with {{ic|SQLCMD}}:
 +
{{bc|1=USE [master]
 +
GO
 +
-- Very basic DB creation
 +
CREATE DATABASE [REDMINE]
 +
GO
 +
-- Creation of a login with SQL Server login/password authentication and no password expiration policy
 +
CREATE LOGIN [REDMINE] WITH PASSWORD=N'redminepassword', DEFAULT_DATABASE=[REDMINE], CHECK_EXPIRATION=OFF, CHECK_POLICY=OFF
 +
GO
 +
-- User creation using previously created login authentication
 +
USE [REDMINE]
 +
GO
 +
CREATE USER [REDMINE] FOR LOGIN [REDMINE]
 +
GO
 +
-- User permissions set via roles
 +
EXEC sp_addrolemember N'db_datareader', N'REDMINE'
 +
GO
 +
EXEC sp_addrolemember N'db_datawriter', N'REDMINE'
 +
GO}}
 +
 +
{{Note|If you want to use additional environments, you must create separate databases for each one (for example: ''development'' and ''test'').}}
 +
 +
====Database Access Configuration====
  
 
Now you need to configure Redmine to access the database we just created. To do that you have to copy {{ic|/usr/share/webapps/redmine/config/database.yml.example}} to {{ic|database.yml}}:
 
Now you need to configure Redmine to access the database we just created. To do that you have to copy {{ic|/usr/share/webapps/redmine/config/database.yml.example}} to {{ic|database.yml}}:
Line 221: Line 197:
 
   schema_search_path: <database_schema> (default - public)}}
 
   schema_search_path: <database_schema> (default - public)}}
  
−
==Session Store Secret Generation==
+
Example for a SQL Server database:
 +
{{hc|nano database.yml|
 +
production:
 +
  adapter: sqlserver
 +
  database: redmine
 +
  host: localhost '''#Set not default host (localhost) here, otherwise this line is unnecessary.'''
 +
  port: 1433 '''#Set not standard port (1433) here, otherwise this line is unnecessary.'''
 +
  username: redmine
 +
  password: my_password
 +
}}
 +
 
 +
===Adding Additional Gems (Optional)===
 +
If you need to load gems that are not required by Redmine core (eg. Puma, fcgi), create a file named {{ic|Gemfile.local}} at the root of your redmine directory. It will be loaded automatically when running {{ic|bundle install}}:
 +
 
 +
{{hc|# nano Gemfile.local|
 +
gem 'puma'}}
 +
 
 +
===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.}}
 +
 
 +
Redmine uses Bundler to manage gems dependencies. So, you need to install Bundler first:
 +
# gem install bundler
 +
 
 +
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 it is highly recommend to enjoy all the features of Redmine, if you really does not want to use {{Pkg|ImageMagick}}, you should skip the installation of the {{ic|rmagick}} gem using:
 +
 
 +
# bundle install --without rmagick
 +
 
 +
{{Note|Only the gems that are needed by the adapters you've specified in your database configuration file are actually installed (eg. if your {{ic|config/database.yml}} uses the ''mysql2'' adapter, then only the mysql2 gem will be installed). Don't forget to re-run {{ic|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:
 
Now you must generate a random key that will be used by Rails to encode cookies that stores session data thus preventing their tampering:
  
Line 230: Line 245:
 
{{Warning|Generating a new secret token invalidates all existing sessions after restart.}}
 
{{Warning|Generating a new secret token invalidates all existing sessions after restart.}}
  
−
==Database Population==
+
===Database Structure Creation===
 
With the database created and the access configured for Redmine, now it's time to create the database structure. This is done by running the following command under the application root directory:
 
With the database created and the access configured for Redmine, now it's time to create the database structure. This is done by running the following command under the application root directory:
  
Line 238: Line 253:
 
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.
 
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.
  
−
==Stub==
+
===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 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:
  
−
===User accounts===
+
# RAILS_ENV=production REDMINE_LANG=pt-BR rake redmine:load_default_data
−
Add {{ic|redmine}} user and append redmine2 to git group.
+
 
 +
{{Note|This step is not mandatory, but it certainly will save you a lot of work to start using Redmine. And for a first time it can be very instructive.}}
  
−
# useradd --user-group --shell /bin/bash --comment 'redmine2 system' --create-home --groups git redmine2
+
===File System Permissions===
 +
The user account running the application '''must''' have write permission on the following subdirectories:
  
−
===MySQL user and databases===
+
'''files''': storage of attachments.
−
Create {{ic|redmine2}} user in MySQL server.
+
'''log''': application log file production.log.
 +
'''tmp''' and '''tmp/pdf''': used to generate PDF documents among other things (create these ones if not present).
  
−
# mysql -u root -p
+
Assuming you run the application with a the default Apache user {{ic|http}} account:
−
CREATE USER 'redmine2'@'%' IDENTIFIED BY  'MY_PASSWORD';
 
−
GRANT USAGE ON *.* TO  'redmine2'@'%' IDENTIFIED BY  'MY_PASSWORD';
 
−
GRANT ALL PRIVILEGES ON  `redmine2\_%`.* TO 'redmine2'@'%';
 
−
create database redmine2 character set utf8;
 
−
create database redmine2_production character set utf8;
 
−
create database redmine2_development character set utf8;
 
−
create database redmine2_test character set utf8;
 
  
 +
# mkdir tmp tmp/pdf public/plugin_assets
 +
# chown -R http:http files log tmp public/plugin_assets
 +
# chmod -R 755 files log tmp tmp/pdf public/plugin_assets
  
 +
===Test the installation===
 +
To test your new installation using WEBrick web server run the following in the Redmine folder:
  
−
===Install gems===
+
# ruby script/rails server webrick -e production
−
This could take a while as it installs all required libraries.
 
  
−
# sudo -u redmine2 -H sh -c 'echo "export PATH=$(ruby -rubygems -e "puts Gem.user_dir")/bin:$PATH" >> /home/redmine2/.bash_profile'
+
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.
−
# sudo -u redmine2 -H gem install bundler
 
−
# cd /home/redmine2/redmine-2.2
 
−
# source /home/redmine2/.bash_profile
 
−
# sudo -u redmine2 -H bundle install
 
  
−
{{Note|1= In order to install ruby bundle, you may be need add user redmine2 for /etc/sudoers. Another option is to first do {{ic|1=export GEM_HOME=/home/redmine2/.gem/}}. }}
+
{{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 Redmine==
+
==Updating (ToDo)==
  
−
===Application Settings===
+
Backup the files used in Redmine:
−
Copy default configuration and adjust settings for your needs.
+
# cd /usr/share/webapps/redmine/files
 +
# tar -czvf redmine_files.tar.gz *
 +
# mv redmine_files.tar.gz /path/to/your/secure/location
  
−
  # cd /home/redmine2/redmine-2.2/config
+
Backup the plugins installed in Redmine:
−
  # sudo -u redmine2 cp configuration.yml.example configuration.yml
+
  # cd /usr/share/webapps/redmine/plugins
−
  # sudo -u redmine2 cp database.yml.example database.yml
+
  # tar -czvf redmine_plugins.tar.gz *
 +
  # mv redmine_plugins.tar.gz /path/to/your/secure/location
  
−
====Minimal configuration.yml====
+
Backup the database:
−
For rapid reference.
+
# mysqldump -u root -p<password> <redmine_database> | gzip > /path/to/backup/db/redmine_`date +%y_%m_%d`.gz
  
−
<pre>
+
Update the package as normal (through [[AUR]]):
−
default:
+
# wget https://aur.archlinux.org/packages/re/redmine/redmine.tar.gz
−
  email_delivery:
+
# tar -zxpvf redmine.tar.gz
−
    delivery_method: :sendmail
+
# cd redmine
  
−
  attachments_storage_path:
+
Inspect the downloaded files, mainly the [[PKGBUILD]], and then build:
 +
# makepkg -s
 +
# pacman -U redmine-2.3.0-2-any.pkg.tar.gz
  
−
  autologin_cookie_name:
+
{{Note|To simplify all this [[AUR]] install and update process, you can always use the [[AUR Helpers]], although this isn't a supported way.}}
−
  autologin_cookie_path:
 
−
  autologin_cookie_secure:
 
  
−
  scm_subversion_command:
+
Update the gems requirements:
−
  scm_mercurial_command:
+
#  bundle update
−
  scm_git_command:
 
−
  scm_cvs_command:
 
−
  scm_bazaar_command:
 
−
  scm_darcs_command:
 
  
−
  database_cipher_key:
+
For a clean gems environment, you may want to remove all the gems and reinstall them. To go through this, do:
 +
# for x in `gem list --no-versions`; do gem uninstall $x -a -x -I; done
  
−
production:
+
{{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.}}
  
−
development:
+
If you did the last step all remove all the gems, now you will need to reinstal them all:
−
</pre>
+
# gem install bundler
 +
# bundle install --without development test
  
−
====Minimal database.yml====
+
Copy the saved files:
−
For rapid reference. Remember to replace MY_PASSWORD for yours.
+
# cd /path/to/your/secure/location
 +
# mv redmine_files.tar.gz /usr/share/webapps/redmine/files
 +
# cd /usr/share/webapps/redmine/files
 +
# tar -zxpvf redmine_files.tar.gz
  
−
{{Note|1= Notice that adapter is mysql2 and not mysql.}}
+
Copy the installed plugins
 +
# cd /path/to/your/secure/location
 +
# mv redmine_plugins.tar.gz /usr/share/webapps/redmine/plugins
 +
# cd /usr/share/webapps/redmine/plugins
 +
# tar -zxpvf redmine_plugins.tar.gz
  
−
<pre>
+
Regenerate the secret token:
−
production:
+
# cd /usr/share/webapps/redmine
−
  adapter: mysql2
+
# rake generate_secret_token
−
  database: redmine2_production
 
−
  host: localhost
 
−
  username: redmine2
 
−
  password: MY_PASSWORD
 
−
  encoding: utf8
 
  
−
development:
+
Check for any themes that you may have installed in the {{ic|public/themes}} directory. You can copy them over but checking for updated version is ideal.
−
  adapter: mysql2
 
−
  database: redmine2_development
 
−
  host: localhost
 
−
  username: redmine2
 
−
  password: MY_PASSWORD
 
−
  encoding: utf8
 
  
−
test:
+
{{Warning|Do NOT overwrite config/settings.yml with the old one.}}
−
  adapter: mysql2
 
−
  database: redmine2_test
 
−
  host: localhost
 
−
  username: redmine2
 
−
  password: MY_PASSWORD
 
−
  encoding: utf8
 
−
</pre>
 
  
−
===Permissions===
+
Update the database. This step is the one that could change the contents of your database. Go to your new redmine directory, then migrate your database:
−
Set permissions for redmine directories.
+
# RAILS_ENV=production REDMINE_LANG=pt-BR rake db:migrate
  
−
# cd /home/redmine2/redmine-2.2
+
If you have installed any plugins, you should also run their database migrations:
−
  # mkdir -pv tmp tmp/pdf public/plugin/assets
+
  # RAILS_ENV=production REDMINE_LANG=pt-BR rake redmine:plugins:migrate
−
# sudo chown -R redmine2:redmine2 files log tmp public/plugin/assets
 
−
# sudo chmod -R 755 files log tmp public/plugin/assets
 
  
−
===Generate secret token===
+
Now, it's time to clean the cache and the existing sessions:
−
Generate new unique secret token
+
# rake tmp:cache:clear
 +
# rake tmp:sessions:clear
  
−
# sudo -u redmine2 rake generate_secret_token
+
Restart the application server (e.g. puma, thin, passenger, etc). And finally go to "Admin -> Roles & permissions" to check/set permissions for the new features, if any.
  
−
===Migrate/install database===
+
==Troubleshooting==
  
−
Create/update database schemas
 
−
# sudo -u redmine2 RAILS_ENV=production rake db:migrate
 
  
−
Populate database with default data.
 
−
# sudo -u redmine2 RAILS_ENV=production rake redmine:load_default_data
 
  
−
==Test server==
+
===User accounts===
−
===Ruby on Rails embedded server===
+
Add {{ic|redmine}} user and append redmine2 to git group.
−
Using Ruby on Rails embedded server
 
  
−
  # ruby script/rails server webrick -e production
+
  # useradd --user-group --shell /bin/bash --comment 'redmine2 system' --create-home --groups git redmine2
  
−
Test it http://localhost:3000
+
==Test server==
−
Use login=admin and password=admin
 
  
 
===Unicorn server===
 
===Unicorn server===

Revision as of 18:18, 25 March 2013

Template:Article summary start Template:Article summary text Template:Article summary heading Template:Article summary wiki Template:Article summary wiki Template:Article summary wiki Template:Article summary end

Tango-document-new.pngThis article is a stub.Tango-document-new.png

Notes: This wiki is under development, so it can contain errors or incomplete information. If you don't feel confident, please wait the wiki to be completed. (Discuss in Talk:Redmine#)


Redmine is a free and open source, web-based project management and bug-tracking tool. It includes a calendar and Gantt charts to aid visual representation of projects and their deadlines. It handles multiple projects. Redmine provides integrated project management features, issue tracking, and support for various version control systems.

Redmine is written using the Ruby on Rails framework. It is cross-platform and cross-database.

Prerequisites

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

Although this guide will go through all the installation process, this isn't a one way path. So Redmine can use different versions of the other softwares (mariaDB, mySQL, postgreSQL, etc, as your database).

Note: At this time is important to note that this guide is an default suggestion, feel free to use other of the prerequisites mentioned on this wiki.

Ruby

Redmine version Supported Ruby versions Rails version used Supported RubyGems versions
2.3.0 ruby 1.8.7, 1.9.2, 1.9.3, 2.0.0 Rails 3.2.13 RubyGems <= 1.8
jruby 1.6.7, 1.7.2


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

Note: 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.

Database

MariaDB 5.0 or higher (recommended)

MariaDB is a drop-in replacement for MySQL, in fact it was a fork of it and maintain binarie compatibility.

To install mariadb simply refer to MariaDB.

MySQL 5.0 or higher

To install mysql simply refer to MySQL.

PostgreSQL 8.2 or higher

To install postgresql PostgreSQL simply refer to Postgresql.

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";
Note: Some bugs in PostgreSQL 8.4.0 and 8.4.1 affect Redmine behavior ([#4259], [#4314]), they are fixed in PostgreSQL 8.4.2

Microsoft SQL Server

Warning: Support is temporarily broken (with ruby 2.0.0 under Windows because of database adapter gems incompatibilities).

SQLite 3

Not supported for multi-user production use. So, it will not be detailed how to install and configure it for use with Redmine.

Warning: Support is temporarily broken (with ruby 2.0.0 under Windows because of database adapter gems incompatibilities).

Web Server

Phusion Passenger (recommended)

TODO

Apache

TODO

Mongrel

TODO

nginx

TODO

Apache Tomcat

TODO

Optional Prerequisites

SCM (Source Code Management)

TODO: list all scm supported and how to install them...

ImageMagick

TODO: to enable Gantt export to png image. link: http://www.imagemagick.org/

Ruby OpenID Library

TODO: to enable OpenID support (version 2 or greater is required). link: http://openidenabled.com/ruby-openid/

Installation

Build and Installation

Download the package redmineAUR from the AUR.

Note: Detailed build instructions at Arch User Repository#Build the package. It's HIGHLY recommended to read all the AUR page to understand what are you doing.

Database Configuration

Now, we will need to create the database that the Redmine will use to store your data. For now on, the database and its user will be named redmine. But this names can be changed to anything else.

Note: The configuration for MariaDB and MySQL will be the same since both are binary compatible.

Database Creation

To create the database, the user and set privileges (MariaDB and MySQL >= 5.0.2): 

# mysql -u root -p
CREATE DATABASE redmine CHARACTER SET UTF8;
CREATE USER 'redmine'@'localhost' IDENTIFIED BY 'my_password';
GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';

For versions of MariaDB and MySQL prior to 5.0.2: 

# mysql -u root -p
CREATE DATABASE redmine CHARACTER SET UTF8;
GRANT ALL PRIVILEGES ON redmine.* TO'redmine'@'localhost' IDENTIFIED BY 'my_password';

For PostgreSQL: 

CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD 'my_password' NOINHERIT VALID UNTIL 'infinity';
CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;

For SQLServer:

Although the database, login and user can be created within SQL Server Management Studio with a few clicks, you can always use the command line with SQLCMD: 

USE [master]
GO
-- Very basic DB creation
CREATE DATABASE [REDMINE]
GO
-- Creation of a login with SQL Server login/password authentication and no password expiration policy
CREATE LOGIN [REDMINE] WITH PASSWORD=N'redminepassword', DEFAULT_DATABASE=[REDMINE], CHECK_EXPIRATION=OFF, CHECK_POLICY=OFF
GO
-- User creation using previously created login authentication
USE [REDMINE]
GO
CREATE USER [REDMINE] FOR LOGIN [REDMINE]
GO
-- User permissions set via roles
EXEC sp_addrolemember N'db_datareader', N'REDMINE'
GO
EXEC sp_addrolemember N'db_datawriter', N'REDMINE'
GO
Note: If you want to use additional environments, you must create separate databases for each one (for example: development and test).

Database Access Configuration

Now you need to configure Redmine to access the database we just created. To do that you have to copy /usr/share/webapps/redmine/config/database.yml.example to database.yml: 

# cd /usr/share/webapps/redmine/config
# cp database.yml.example database.yml

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).

Example for MariaDB and MySQL database: 

nano database.yml
production:
  adapter: mysql2
  database: redmine
  host: localhost
  port: 3307   #If your server is not running on the standard port (3306), set it here, otherwise this line is unnecessary.
  username: redmine
  password: my_password
Note: For ruby1.9 the "adapter" value must be set to mysql2, and for ruby1.8 or jruby, it must be set to mysql.

Example for PostgreSQL database: 

nano database.yml
production:
  adapter: postgresql
  database: redmine
  host: localhost
  username: redmine
  password: my_password
  encoding: utf8
  schema_search_path: <database_schema> (default - public)

Example for a SQL Server database: 

nano database.yml
production:
  adapter: sqlserver
  database: redmine
  host: localhost #Set not default host (localhost) here, otherwise this line is unnecessary.
  port: 1433 #Set not standard port (1433) here, otherwise this line is unnecessary.
  username: redmine
  password: my_password

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'

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.

Redmine uses Bundler to manage gems dependencies. So, you need to install Bundler first: 

# gem install bundler

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 it is highly recommend to enjoy all the features of Redmine, if you really does not want to use ImageMagick, 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've 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). Don't 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: 

# rake generate_secret_token
Note: For Redmine prior to 2.x this step is done by executing # rake generate_session_store.
Warning: Generating a new secret token invalidates all existing sessions after restart.

Database Structure Creation

With the database created and the access configured for Redmine, now it's time to create the database structure. This is done by running the following command under the application root directory: 

# cd /usr/share/webapps/redmine
# RAILS_ENV=production rake db:migrate

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 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: 

# RAILS_ENV=production REDMINE_LANG=pt-BR rake redmine:load_default_data
Note: This step is not mandatory, but it certainly will save you a lot of work to start using Redmine. And for a first time it can be very instructive.

File System Permissions

The user account running the application must have write permission on the following subdirectories: 

files: storage of attachments.
log: application log file production.log.
tmp and tmp/pdf: used to generate PDF documents among other things (create these ones if not present).

Assuming you run the application with a the default Apache user http account: 

# mkdir tmp tmp/pdf public/plugin_assets
# chown -R http:http files log tmp public/plugin_assets
# chmod -R 755 files log tmp tmp/pdf public/plugin_assets

Test the installation

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

# ruby script/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.

Updating (ToDo)

Backup the files used in Redmine: 

# cd /usr/share/webapps/redmine/files
# tar -czvf redmine_files.tar.gz *
# mv redmine_files.tar.gz /path/to/your/secure/location

Backup the plugins installed in Redmine: 

# cd /usr/share/webapps/redmine/plugins
# tar -czvf redmine_plugins.tar.gz *
# mv redmine_plugins.tar.gz /path/to/your/secure/location

Backup the database: 

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

Update the package as normal (through AUR): 

# wget https://aur.archlinux.org/packages/re/redmine/redmine.tar.gz
# tar -zxpvf redmine.tar.gz
# cd redmine

Inspect the downloaded files, mainly the PKGBUILD, and then build: 

# makepkg -s
# pacman -U redmine-2.3.0-2-any.pkg.tar.gz
Note: To simplify all this AUR install and update process, you can always use the AUR Helpers, although this isn't a supported way.

Update the gems requirements: 

#  bundle update

For a clean gems environment, you may want to remove all the gems and reinstall them. To go through this, do: 

# for x in `gem list --no-versions`; do gem uninstall $x -a -x -I; done
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 all remove all the gems, now you will need to reinstal them all: 

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

Copy the saved files: 

# cd /path/to/your/secure/location
# mv redmine_files.tar.gz /usr/share/webapps/redmine/files
# cd /usr/share/webapps/redmine/files
# tar -zxpvf redmine_files.tar.gz

Copy the installed plugins 

# cd /path/to/your/secure/location
# mv redmine_plugins.tar.gz /usr/share/webapps/redmine/plugins
# cd /usr/share/webapps/redmine/plugins
# tar -zxpvf redmine_plugins.tar.gz

Regenerate the secret token: 

# cd /usr/share/webapps/redmine
# rake generate_secret_token

Check for any themes that you may have installed in the public/themes directory. You can copy them over but checking for updated version is ideal.

Warning: Do NOT overwrite config/settings.yml with the old one.

Update the database. This step is the one that could change the contents of your database. Go to your new redmine directory, then migrate your database: 

# RAILS_ENV=production REDMINE_LANG=pt-BR rake db:migrate

If you have installed any plugins, you should also run their database migrations: 

# RAILS_ENV=production REDMINE_LANG=pt-BR rake redmine:plugins:migrate

Now, it's time to clean the cache and the existing sessions: 

# rake tmp:cache:clear
# rake tmp:sessions:clear

Restart the application server (e.g. puma, thin, passenger, etc). And finally go to "Admin -> Roles & permissions" to check/set permissions for the new features, if any.

Troubleshooting

User accounts

Add redmine user and append redmine2 to git group. 

# useradd --user-group --shell /bin/bash --comment 'redmine2 system' --create-home --groups git redmine2

Test server

Unicorn server

# sudo -u redmine2 unicorn -D -E production -c config/unicorn.rb

Start redmine on boot

Append follow command at end of your /etc/rc.local 

# sudo -u redmine2 bash -c "source /home/redmine2/.bash_profile && cd /home/redmine2/redmine-2.2 && unicorn -D -E production -c config/unicorn.rb"

Resources

Retrieved from "https://wiki.archlinux.org/index.php?title=Redmine&oldid=251931"