Redmine

h1. HowTo Install Redmine 2.5.x on Fedora 20

{{toc}}

h2. System Requirements

No assumptions are made about the initial state of the system in this guide. The guide can be followed for either 32-bit or 64-bit systems - though all testing and the original installation was performed on a 64-bit system.

The hardware requirements are not significant, so a small VM with 10gb storage and 1GB ram and 1GB swap file should be sufficient.

This guide can be used on top of an already existing system or, from scratch, downloading from the Fedora website.

An ISO for installation can be downloaded from "here":http://fedoraproject.org/en/get-fedora.

The rest of the guide assumes that you have created a user account with wheel/administrator access and are logged in to the terminal directly or through SSH.

h2. Updating the System

Before beginning, you should ensure all of your installed packages are up-to-date. This can be done by issuing the following command:

<pre>

$ sudo yum update

</pre>

If the kernel was updated as part of this command, you should perform a restart to begin using it:

<pre>

$ sudo shutdown -r now

</pre>

h2. Installing Dependencies

Before beginning the installation of Redmine, there are a number of dependencies which need to be installed.

Depending on your needs, some of these may not be necessary. Depending on your preferences, you may choose alternatives to some of these.

<pre>

apr-devel         - For Passenger

apr-util-devel    - For Passenger

curl-devel        - For Passenger

gcc               - For JSON

gcc-c++           - For Passenger

git               - (Optional) For SCM Integration

httpd             - Web Server

httpd-devel       - For Passenger

ImageMagick-devel - For RMagick

mariadb-devel     - For Redmine

mariadb-server    - For Redmine

nano              - Configuration Editor

ruby-devel        - For Redmine

tar               - For Decompression

wget              - For Download

</pre>

All of these can be installed prior to starting with a single command:

<pre>

$ sudo yum install apr-devel apr-util-devel curl-devel gcc gcc-c++ git httpd httpd-devel ImageMagick-devel mariadb-devel mariadb-server nano ruby-devel tar wget

</pre>

h2. Disable SELinux

Some users have noted issues installing Redmine with SELinux active. This can be disabled via the following command:

<pre>

# sudo setenforce 0

</pre>

Steps will be taken throughout the remainder of the guide to ensure that, if desired, SELinux can be re-enabled after and still maintain a fully functional Redmine installation.

h2. Enable Server Environment

With all of the dependencies installed, we need to ensure that the servers are setup, ready for use, and accessible external to the OS installation.

The first step is to open the standard port 80 in the firewall for the web server:

<pre>

$ sudo firewall-cmd --zone=public --add-service=http

$ sudo firewall-cmd --permanent --zone=public --add-service=http

</pre>

The first line opens the port in the current configuration. The second line ensures that, after a restart, that port will remain open and available.

The second step is to start the web server and database server:

<pre>

$ sudo systemctl start httpd mariadb

$ sudo systemctl enable httpd mariadb

</pre>

Similar to the firewall commands, the first line starts the servers in the current configuration. The second line ensures that, after a restart, both servers come back online.

h2. Configuring MariaDB

Now that you have a database server up and running, it needs to be configured for use. The initial setup can be performed with the following command:

<pre>

$ mysql_secure_installation

</pre>

This will prompt you to create a password for the root account as well as a number of other choices. For a standard setup, the default choice for each question is acceptable.

Advanced usages or installations may opt for different answers; however, that is beyond the scope of this guide.

h3. Creating a Redmine Database and Account

Now that you have MariaDB configured, it is time to create a database and user for use with your Redmine installation.

First, connect to the server:

<pre>

$ mysql -u root -p

</pre>

You will be prompted to enter the root password. Once provided, you will be able to issue the following commands:

<pre><code class="sql">

CREATE DATABASE redmine CHARACTER SET utf8;

CREATE USER 'redmine'@'localhost' IDENTIFIED BY '<user_password>';

GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';

</code></pre>

The above commands will create the database, create a user with a defined password, and ensure the created user has full access on the newly created database.

Once those commands have been entered, issue the following command to return to the command line:

<pre>

quit

</pre>

h2. Obtaining Redmine

Now that all the dependencies are installed and the servers are up and running it's time to get the stable release of Redmine and begin its installation.

In this example, we'll use wget to download the file from the Redmine server and tar to extract its contents:

<pre>

$ wget http://www.redmine.org/releases/redmine-2.5.2.tar.gz

$ tar xfzv redmine-2.5.2.tar.gz

</pre>

h2. Redmine Database Configuration

To ensure proper functionality, the Redmine installation will need to communicate with the database that has just been created. This can be done by performing the following:

<pre>

$ cd redmine-2.5.2/config

$ cp database.yml.example database.yml

$ nano -w database.yml

</pre>

Once the file has been opened, the @production@ definition needs to be updated to match the database and account used above. It should look as follows:

<pre><code class="yaml">

production:

  adapter: mysql2

  database: redmine

  host: localhost

  username: redmine

  password: "<user_password>"

  encoding: utf8

</code></pre>

This replaces the user @root@ and the blank password in the example configuration file.

h2. Redmine Installation Directory

With most of the precursor work completed, it's time to move the installation to a folder more accessible than a user's home directory.

For the purposes of this guide, Redmine will be moved to @/var/www/redmine@; however, this could be moved to a variety of over locations based on personal needs.

This can be don with the following commands:

<pre>

$ cd /var/www

$ sudo cp -R ~/redmine-2.5.2 redmine

$ cd redmine

</pre>

To ensure proper functionality and access rights, the @public/plugin_assets@ folder needs to be created:

<pre>

$ sudo mkdir public/plugin_assets

</pre>

To allow read/write access to the folders, the user @apache@ needs to have access:

<pre>

$ sudo chown apache:apache -R files log public/plugin_assets tmp

</pre>

h3. Optional SELinux Configuration

If you plan to re-enable SELinux after installation, the following steps should be taken to ensure smooth execution.

<pre>

$ sudo chcon -R --reference=/var/www/html /var/www/redmine

</pre>

This command applies SELinux directory permissions typically for a web server to all sub-directories under the redmine top-level folder.

<pre>

$ sudo chcon -t httpd_sys_content_rw_t -R files log public/plugin_assets tmp

</pre>

This command enables the specific folders listed to have read/write access while SELinux is active. Under a normal configuration with SELinux, all web directories are read-only.

h2. Ruby Gem Installation

The ruby dependencies for Redmine are managed by bundler, so that must be installed first to determine what else must be downloaded and installed.

<pre>

$ sudo gem install bundler

</pre>

With bundler installed, the Redmine ruby dependencies can be sorted:

<pre>

$ sudo /usr/local/bin/bundle install --without development test

</pre>

*Note 1:* By default @/usr/local/bin@ is not on @$PATH@ for the @root@ user, so the absolute path must be provided.

*Note 2:* Bundle will complain about installing gems via sudo making them only usable by @root@. This is not true - by installing as @root@, these gems are available to all users.

h2. Native Extension Fixes

When running @bundler@ as root, the @mysql2@ and @rmagick@ native extensions get installed, but to a folder not on ruby's path. To correct this, the following steps should be taken:

<pre>

$ sudo mkdir -p /usr/local/lib64/ruby/site_ruby/mysql2

</pre>

This creates the path that ruby expects to find the @mysql2.so@ file at.

<pre>

$ cd /usr/local/share/gems/gems/mysql2-0.3.16/ext/mysql2

$ sudo ruby extconf.rb

$ sudo make

$ sudo make install

</pre>

The above steps complete the install to the expected directory using default compile options. Special options are beyond the scope of this guide.

The same should now be performed for the @rmagick@ native extension:

<pre>

$ cd /usr/local/share/gems/gems/rmagick-2.13.3/ext/RMagick

$ sudo ruby extconf.rb

$ sudo make

$ sudo make install

</pre>

Once again, the above steps complete the install to the expected directory using default compile options.

Finally, return to the installation directory to finish the remaining steps:

<pre>

$ cd /var/www/redmine

</pre>

h2. Redmine Database Initialization

We're on to the final steps of completing the Redmine installation now that everything else has been taken care of.

The first step is to generate the secret key for session management:

<pre>

$ sudo /usr/local/bin/rake generate_secret_token

</pre>

Next, the database needs to be setup:

<pre>

$ sudo RAILS_ENV=production /usr/local/bin/rake db:migrate

</pre>

Finally, the database needs to be populated with default data:

<pre>

$ sudo RAILS_ENV=production /usr/local/bin/rake redmine:load_default_data

</pre>

This will prompt you to pick your language, which defaults to [en].

h3. WEBRick Test Execution

Once this step has been completed, you have a fully functional Redmine installation and can run this for testing via WEBRick:

<pre>

$ sudo ruby script/rails server webrick -e production

</pre>