Monday, December 1, 2014

Installing Redmine (2.6.0) on Fedora Linux (Fedora Linux 20)

I have been running Redmine in Fedora Linux from Fedora Linux 16 to Fedora Linux 20. The instruction I am using to install and upgrade Redmine is from a Redmine's wiki page. In this post, I would like to first briefly document the steps to install Redmine on Feodra Linux, at present Fedora Linux 20, integrate Redmine with the Apache HTTP server, and then discuss a few issues that we would probably need to deal with when upgrading Fedora Linux and  in turn when upgrading Redmine.

Note that the process described below can be automated by a shell script I wrote. See this post for more detail.

Installing Redmine on Fedora Linux 20

The instruction is generally a copy of a Redmine's wiki page with more detailed steps on Fedora Linux and with intention to answer the questions raised in the page here.

Meeting Prerequisites

Before we begin, we will make sure that the Fedora Linux systems has the following software installed,
  • Ruby and Ruby bundler
  • Apache HTTP Server
  • Phusion Passenger.
    Although Redmine can run as a standalone server, it is recommended to integrate it with a HTTP server. One may use Phusion Passenger, FCGI or a Rack server (Unicorn, Thin, Puma, hellip;) to integrate with the Apache HTTP Server. In this post, we use Phusion Passenger.
  • PostgreSQL database server and PostgreSQL development package.
    Among two relational database management system that Redmine supports, MySQL and PostgreSQL, I personally prefer PostgreSQL to MySQL as a result that PostgreSQL's license is less restricted than MySQL's.
  • The GNU C complier. 
  • The image display and manipulation tool ImageMagick and its development package
  • The non-interactive network downloader wget
  • The archiver tool tar
In addition, we assume that a user has an username what is in the "Administrator" group, i.e., the user can switch to user "root" using via <code>sudo</code>.

In this section, we show the steps to meet the prerequisites. If the prerequisites are already met, the following steps are expected not to have any impact on the system.
  1. Installing Ruby and Ruby bundler. 
    
  # install the Ruby package
  sudo yum install ruby

  # install the Ruby development package
  sudo yum install ruby-devel

  # install Ruby's bundler
  sudo yum install rubygem-bundler
  2. Installing Apache HTTP Server. 
    
  # install the Apache HTTP Server
  sudo yum install httpd

  # enable the HTTPD service at system boot time
  sudo systemctl enable httpd.service

  # start the HTTPD service
  sudo systemctl start httpd.service
  3. Installing Phusion Passenger for Apache HTTP Server. 
    
  sudo yum install mod_passenger
  4. Installing PostgreSQL database server and PostgreSQL development package. 
    
  # install the PostgreSQL database server package
  sudo yum install postgresql-server postgresql-devel

  # enable postgresql's start during the boot using following command
  sudo systemctl enable postgresql.service

  # initialize the postgresql database
  sudo postgresql-setup initdb

  # start the postgresql service. 
  sudo systemctl start postgresql.service
  5. Installing the GNU C complier. 
    
  sudo yum install gcc
  6. Installing the image display and manipulation tool ImageMagick 
    
  sudo yum install ImageMagick ImageMagick-devel
  7. Installing the non-interactive network downloader wget. 
    
  sudo yum install wget
  8. Install the archiver tool tar.
    
  sudo yum install tar
  9. Install a few additional packages to work with subversion. 
    
  yum install perl-DBI perl-Digest-SHA mod_dav_svn

Installing Redmine

  1. Download and extract Redmine source.

    The URL of Redmine sources are available in this page.

    Assume that we are to download Redmine 2.6.0 (released on 2014-10-21) and plan to install it at the directory /var/www/redmine. 
    
  cd /var/www/
  sudo wget -q http://www.redmine.org/releases/redmine-2.6.0.tar.gz
  sudo tar -xzf redmine-2.6.0.tar.gz
    We can now verify that we have successfully downloaded and extracted the Redmine source. 
    
  $ ls -l redmine-2.6.0
  total 76
  drwxrwxr-x. 7 1000 1000 4096 Oct 21 15:13 app
  drwxrwxr-x. 5 1000 1000 4096 Oct 21 15:13 config
  -rw-rw-r--. 1 1000 1000  160 Oct 21 15:13 config.ru
  -rw-rw-r--. 1 1000 1000  240 Oct 21 15:13 CONTRIBUTING.md
  drwxrwxr-x. 3 1000 1000 4096 Oct 21 15:13 db
  drwxrwxr-x. 2 1000 1000 4096 Oct 21 15:13 doc
  drwxrwxr-x. 5 1000 1000 4096 Oct 21 15:13 extra
  drwxrwxr-x. 2 1000 1000 4096 Oct 21 15:13 files
  -rw-rw-r--. 1 1000 1000 3555 Oct 21 15:13 Gemfile
  drwxrwxr-x. 8 1000 1000 4096 Oct 21 15:13 lib
  drwxrwxr-x. 2 1000 1000 4096 Oct 21 15:13 log
  drwxrwxr-x. 2 1000 1000 4096 Oct 21 15:13 plugins
  drwxrwxr-x. 7 1000 1000 4096 Oct 21 15:13 public
  -rw-rw-r--. 1 1000 1000  275 Oct 21 15:13 Rakefile
  -rw-rw-r--. 1 1000 1000  205 Oct 21 15:13 README.rdoc
  drwxrwxr-x. 2 1000 1000 4096 Oct 21 15:13 script
  drwxrwxr-x. 9 1000 1000 4096 Oct 21 15:13 test
  drwxrwxr-x. 8 1000 1000 4096 Oct 21 15:13 tmp
  drwxrwxr-x. 2 1000 1000 4096 Oct 21 15:13 vendor
  2. Creating an empty database and accompanying user for Redmine.

    We now create a PostgreSQL database for Redmine. In the commands below, we assume the password is "my_password" for demonstration and should choose a more thoughtful one.

    Also, we also name the database for Redmine as "redmine". It does not have to be and can be any valid PostgreSQL database name. 
    
  # switch to user postgres
  sudo su - postgres

  # create database role redmine
  echo \
    "CREATE ROLE redmine LOGIN ENCRYPTED
     PASSWORD 'my_password' NOINHERIT VALID UNTIL 'infinity';" | \
    psql

  # create database named redmine for Redmine
  echo \
    "CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;" | \
    psql

  # edit PostgreSQL Client Authentication Configuration File
  sed -e \
    "/host.*all.*all.*::1\/128.*ident/i host redmine redmine ::1/128 md5" \
    --in-place=.bu /var/lib/pgsql/data/pg_hba.conf  

  # restart PostgreSQL database server
  sudo systemctl restart postgresql.service

  # exit from user postgres
  exit
    The change to the PostgreSQL client authentication configuration file, by default at /var/lib/pgsql/data/pg_hba.conf is necessary to Redmine to establish a connection to the database. The working configuration depends on a few factors and can be an issue. More discussion is available. However, the above configuration works on a Fedora Linux distribution with IPv6 enabled, which is the default setting.
  3. Configuring database connection.

    We will follow the instruction of Step 3 in the Redmine wiki page. We will copy ${REDMINE}/config/database.yml.example to ${REDMINE}/config/database.yml and edit the file in order to configure the database settings for "production" environment. In this example, ${REDMINE} is /var/www/redmine-2.6.0.

    With the PostgreSQL database parameters used in the above step, the "production" section of ${REDMINE}/config/database.yml should be replaced as follows, 
    
  production:
    adapter: postgresql
    database: redmine
    host: localhost
    username: redmine
    password: my_password
    encoding: utf8
    If you do not wish to use the MySQL database management system at all, comment out any sections that refers to the MySQL database management system in the configuration file. In this post, we assume that you do not use the MySQL database management system and your system many not have the MySQL client library and development head files installed. To make the point clear, we list the content of a desired database configuration file as follows, 
    
  $ cat ${REDMINE}/config/database.yml
  production:
    adapter: postgresql
    database: redmine
    host: localhost
    username: redmine
    password: my_password
    encoding: utf8
    where ${REDMINE} is /var/www/redmine-2.6.0 in this example. More discussion on potential dependency issue caused by the configuration file is available.
  4. Installing Redmine Ruby dependencies using the Ruby Dependency Management tool bundle.

    Following the generic instruction in the Redmine wiki page, We shall install Redmine's ruby dependencies using bundle.

    There are some subtle issues to install Redmine's Ruby dependencies using the tool. We use a workaround to circumvent the issues, that is, we run bundle under a non-root user with login permission and specify the path in which the dependencies will be installed. In this example, we assume that the non-root username is your username foouser and the directory to install the dependencies is ${REDMINE}/.bundle/ruby where ${REDMINE} is /var/www/redmine-2.6.0 in this example. Replace foouser with your actual username.
    
  # give your user userfoo read and write permission to ${REDMINE}
  sudo chown -R userfoo ${REDMINE}

  # make sure that the working directory is ${REDMINE}
  # in this example, ${REDMINE} is /var/www/redmine-2.6.0
  cd ${REDMINE} 
 
  # install Redmine's Ruby dependencies 
  /usr/bin/bundle install \
      --path /var/www/redmine-2.6.0/.bundle \
      --without development test
    If success, the output of the above steps will be something similar to the following, 
    
  $ /usr/bin/bundle install \
      --path /var/www/redmine-2.6.0/.bundle \
      --without development test
  Fetching gem metadata from https://rubygems.org/.........
  Resolving dependencies...
  Using rake 10.4.0
  Using i18n 0.6.11
  ......
  Your bundle is complete!
  Gems in the groups development and test were not installed.
  It was installed into ./.bundle
  Post-install message from rdoc:
  Depending on your version of ruby, you may need to install ruby rdoc/ri data:

  <= 1.8.6 : unsupported
   = 1.8.7 : gem install rdoc-data; rdoc-data --install
   = 1.9.1 : gem install rdoc-data; rdoc-data --install
  >= 1.9.2 : nothing to do! Yay!
  ......
    Since on Fedora Linux 20, the version of Ruby is 2.0 or higher, there is nothing else to do for the Ruby dependencies.

    During the above process, a configuration file ${REDMINE}/.bundle/config will be created. The following shows an example of the configuration file created during the process. 
    
  $ cat ${REDMINE}/.bundle/config
  ---
  BUNDLE_PATH: /var/www/redmine-2.6.0/.bundle
  BUNDLE_WITHOUT: development:test
  BUNDLE_DISABLE_SHARED_GEMS: '1'
    The configuration file informs Redmine where the Ruby dependencies is as indicated by the BUNDLE_PATH variable in the configuraiton file.
  5. Generating session store secret.

    We simply follow the instruction in the Redmine wiki page. Note that in this example, ${REDMINE} is /var/www/redmine-2.6.0.
    
  /usr/bin/bundle exec \
      "${REDMINE}/.bundle/ruby/bin/rake generate_secret_token"
  6. Loading Redmine database default data set.

    Again, we simply follow the instruction in the Redmine wiki page. 
    
  /usr/bin/bundle exec "RAILS_ENV=production rake db:migrate"
  7. Setting up file system permissions.
    Again, we simply follow the instruction in the Redmine wiki page. However, there is a minor deviation since we set up Redmine using your username. We will make necessary changes to integrate it with the Apache HTTP Server in next section. Again ${REDMINE}$ in this example is /var/www/redmine-2.6.0.
    
  mkdir -p ${REDMINE}/tmp ${REDMINE}/tmp/pdf ${REDMINE}/public/plugin_assets
  chmod 755 ${REDMINE}/tmp ${REDMINE}/tmp/pdf ${REDMINE}/public/plugin_assets
    Again, in this example, ${REDMINE} is /var/www/redmine-2.6.0.
  8. Testing the Redmine installation.

    We follow the instrucion in the Redmine wiki page. 
    
  $ ruby script/rails server webrick -e production
  => Booting WEBrick
  => Rails 3.2.19 application starting in production on http://0.0.0.0:3000
  => Call with -d to detach
  => Ctrl-C to shutdown server
  [2014-11-30 19:05:45] INFO  WEBrick 1.3.1
  [2014-11-30 19:05:45] INFO  ruby 2.0.0 (2013-11-22) [x86_64-linux]
  [2014-11-30 19:05:45] INFO  WEBrick::HTTPServer#start: pid=6454 port=3000
    Pointing a browser to http://localhost:3000, you will see Redmine's welcome page, which indicates that Redmine runs OK. However, as indicated in the Redmine wiki page, this is not intended means of running Redmine.

Changing Redmine Admin User's Initial Password

Redmine's has an Admin user "admin" with initial password "admin". Before we make the Redmine available to the outside world, we should change the password of the Admin user "admin". When we test the Redmine in previous step, log in as admin and reset the password.

Integrating Redmine with Apache HTTP Server via Phusion Passenger


    We shall integrate Redmine with the Apache HTTP Server via Phusion Passenger. Fedora Linux by default has SeLinux enabled. SeLinux can be a source of problems. We will defer configuration for SeLinux in next section. Then, we will temporarily disable SeLinux.

  1. Temporarily disabling SeLinux 
    
  sudo setenforce false
  2. Change Redmine installaiton's ownership
    To create a workaround to install Redmine's Ruby dependencies using bundle, we changed the ownership of the Redmine installation to your username. We now change the ownership to the user as whom the Apache HTTP Server, i.e., user apache is running and remove access to the installation from any users but user apache and group apache. 
    
  sudo chown -R apache:apache ${REDMINE}
  sudo chmod o-rwx ${REDMINE}
    Note that ${REDMINE} is /var/www/redmine-2.6.0 in this example.
  3. Configuring the Phusion Passenger module to integrate Redmine with the Apache Web server.

    When the Phusion Passenger module package is installed, an Apache HTTP Server configuration file will be installed at /etc/httpd/conf.d/. The configuration file is /etc/httpd/conf.d/passenger.conf. We will append the following lines to the configuration file. 
          
      <VirtualHost *:80>
        SetEnv GEM_HOME /var/www/redmine-2.6.0/.bundle/ruby
        ServerName localhost.localdomain
        DocumentRoot /var/www/redmine-2.6.0/public
        <Directory /var/www/redmine-2.6.0/public>
          AllowOverride all
          Options -MultiViews
        </Directory>
      </VirtualHost>
    In the above, the environment variable GEM_HOME is important. Without its pointing to the location of the Gem files installed by bundle, i.e., /var/www/redmine-2.6.0/.bundle/ruby, Redmine will complains that it cannot find the required Gem files. More discussion on this issue is available.

Configuring SeLinux for Redmine

Redmine has a wiki page Redmine, Phusion Passenger, Ruby Enterprise Edition, Apache and ... SELinux that is our beginning point. Fedora Linux 20 has a SeLinux policy module that properly set up SeLinux permissions for Phusion Passenger, which makes the steps simpler than the Redmine's wiki page. The following steps is a minor revision of the RedmineAndSELinux script in the Redmine wiki page. 


  APACHE_USER=apache
  REDMINE=/var/www/redmine-2.6.0
  GEM_HOME=${REDMINE}/.bundle

  # Base permissions.
  sudo chown -R ${APACHE_USER}:${APACHE_USER} ${REDMINE}
  sudo chmod -R u=rw,g=r,o-rwx ${REDMINE}
  sudo chmod -R ug+X ${REDMINE}
  sudo chcon -R -u system_u -t httpd_sys_content_t ${REDMINE}

  # Writable directories.
  sudo chown -R ${APACHE_USER}:${APACHE_USER} ${REDMINE}/log
  sudo chcon -R -t httpd_log_t ${REDMINE}/log

  sudo chown -R ${APACHE_USER}:${APACHE_USER} ${REDMINE}/tmp
  sudo chcon -R -t httpd_tmpfs_t ${REDMINE}/tmp

  sudo chown -R ${APACHE_USER}:${APACHE_USER} ${REDMINE}/files
  sudo chcon -R -t httpd_sys_script_rw_t ${REDMINE}/files

  sudo chown -R ${APACHE_USER}:${APACHE_USER} ${REDMINE}/public/plugin_assets
  sudo chcon -R -t httpd_sys_script_rw_t ${REDMINE}/public/plugin_assets

  # Set permission to the shared objects used by Ruby GEM files
  sudo find -P ${GEM_HOME} -type f -name "*.so*" -exec chcon -t lib_t {} \;

  # enable SeLinux
  sudo setenforce 1

  # allow Apache to connect to database
  sudo setsebool -P httpd_can_network_connect_db 1

  # restart the Apache HTTP Server
  sudo systemctl restart httpd.service
Alternatively, you may download and execute the shell script selinuxforredmine.sh at Github, for instance, 

  sudo ./selinuxforredmine.sh /var/www/redmine-2.6.0
  sudo setenforce 1
  sudo systemctl restart httpd.service

Configuring Firewall

To allow the outside world to connect to the Redmine instance on the Fedora Linux system, we will have to configure the firewall to allow incoming connection at TCP port 80. One of my previous post discusses how we can add an allowed port in Fedora's firewalld.

This is final step, we are now done.


Common Issues During Redmine Installation on Fedora Linux

Authentication with PostgreSQL Database

In the above, the PostgreSQL client authentication configuration file works for a Fedora Linux system with IPv6 enabled since ::1/128 is an IPv6 address. IPv6 is enabled on Fedora Linux 20 by default.

If the IPv6 is disabled, then the line to be added to the configuration file, by default at /var/lib/pgsql/data/hg_hba.conf should be, 

  host    redmine    redmine    127.0.0.1/32  md5
Be aware that the order of such configuration lines in the configuration file matters. The line must appear before a more generic configuration line, as such, the segment of the configuration upon addition of the line should resemble the following, 

  host    redmine    redmine    127.0.0.1/32  md5
  host    all        all        127.0.0.1/32  ident
If you place the line after the more generic configuration line, the more restrictive line wil have no effect. For instance, the segment of configuration is as follows, a database client program will attempt to connect to the datbase using the "ident" method and fail to establish the connection. 

  host    all        all        127.0.0.1/32  ident
  host    redmine    redmine    127.0.0.1/32  md5

Potential Dependency Issues Caused by database.yml

The configuration file ${REDMINE}/config/database.yml specifies what database management system and databases that Redmine relies on. For instance, the configuration file has a section as follows, 

  development:
    adapter: mysql2
    database: redmine_development
    host: localhost
    username: root
    password: ""
    encoding: utf8
The configuration file creates a dependency on the MySQL database management system and the Ruby Dependency Management Tool bundle will attempt to install the MySQL Gem file. If the system does not have required the MySQL client library and the MySQL development header files, the bundle installation process will fail as shown in the example below, 

$ /usr/bin/bundle install \
  --path /var/www/redmine-2.6.0/.bundle \
  --without development test
Fetching gem metadata from https://rubygems.org/.........
Resolving dependencies...
Using rake 10.4.0
Using i18n 0.6.11
Using multi_json 1.10.1
......
Using jquery-rails 3.1.2

Gem::Installer::ExtensionBuildError: ERROR: Failed to build gem native extension.

    /usr/bin/ruby extconf.rb
checking for ruby/thread.h... yes
checking for rb_thread_call_without_gvl() in ruby/thread.h... yes
......
checking for mysql_query() in -lmysqlclient... no
......
*** extconf.rb failed ***
Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers.  Check the mkmf.log file for more details.  You may
need configuration options.

Provided configuration options:
        --with-opt-dir
          .....
        --without-mysqlclientlib
        --with-mygcclib
        --without-mygcclib
        --with-mysqlclientlib
        --without-mysqlclientlib


Gem files will remain installed in /var/www/redmine-2.6.0/.bundle/ruby/gems/mysql2-0.3.17 for inspection.
Results logged to /var/www/redmine-2.6.0/.bundle/ruby/gems/mysql2-0.3.17/ext/mysql2/gem_make.out

An error occurred while installing mysql2 (0.3.17), and Bundler cannot continue.
Make sure that `gem install mysql2 -v '0.3.17'` succeeds before bundling.
The existence of such a dependency is a fact. Therefore, the error remains even if you instruct bundle explicitly not to install MySQL Gem files, e.g., 

  $ /usr/bin/bundle install \
    --path /var/www/redmine-2.6.0/.bundle \
    --without development test mysql mysql2

Using Ruby Dependency Management Tool

We install Redmine's ruby dependencies using bundle. The instruction in the Redmine wiki page is a generic description that some appear to be confused with what to do.

In the Redmine's wiki page, The Ruby bundle is installed via gem as in gem install bundler. However, it will install it in your local directory unless you run gem as root. When you install it as root, i.e., sudo gem install bundler. The bundler will be located in /usr/local. You will to make sure that /usr/local/bin in your search path. In the step above, I simplify it by installing Fedora Linux's bundler package, and then bundle will be in /usr/bin.

We need to first identify a user under whom the Redmine's ruby dependencies should be installed. In this post, we assume that we will integrate Redmine with the Apache web server. Then the user under whom Redmine's ruby dependencies should be installed is the user apache since in Fedora Linux, the Apache web server is run under user apache.

The challenge is that in a typical Fedora Linux installation, you cannot switch to user apache since the user is created without the login permission. Furthermore, if you attempt to install the Redmine's ruby dependencies under user root, you will observe an error as shown below, 

  $ sudo bundle install --without development test
  Don't run Bundler as root. Bundler can ask for sudo if it is needed, and
  installing your bundle as root will break this application for all 
  non-root users on this machine.
  Could not locate Gemfile
In the above, we use a workaround. Assume that your username is userfoo. We install Redmine's ruby dependencies under the username userfoo at a specific directory, in this example, ${REDMINE}/.bundle/ruby. Again, ${REDMINE} is /var/www/redmine-2.6.0.

Locating Gem Files

You may install Gem files to any directory using bundle. However, you will set the value of environmental variable GEM_HOME to the directory. In the above, we set the environment variable in the Apache HTTP Server's configuration file /etc/httpd/conf.d/passenger.conf. For instance, if we comment out the SetEnv line from the configuration file, we will observe an error with the error messages as follows, 

  You have already activated rake 10.0.4, but your Gemfile requires rake 10.4.0. 
  Prepending `bundle exec` to your command may solve this. (Gem::LoadError)
  /usr/share/gems/gems/bundler-1.7.6/lib/bundler/runtime.rb:34:in `block in setup'
  /usr/share/gems/gems/bundler-1.7.6/lib/bundler/runtime.rb:19:in `setup'
  /usr/share/gems/gems/bundler-1.7.6/lib/bundler.rb:121:in `setup'
  ......
The effect of the environment variable can be demonstrated using the two examples below, one without the environment variable's value being set, one with the value being set. 

  $ gem env
  RubyGems Environment:
  - RUBYGEMS VERSION: 2.1.11
  - RUBY VERSION: 2.0.0 (2013-11-22 patchlevel 353) [i386-linux]
  ......
  - GEM PATHS:
     - /home/foouser/.gem/ruby
     - /usr/share/gems
     - /usr/local/share/gems
  ......
  $ gem list
Note the above, GEM PATHS do not include the directory /var/www/redmine-2.6.0/.bundle/ruby. Then, Ruby will not be able to locate the Gem files installed using bundle. 

   $ gem list

   *** LOCAL GEMS ***

   bigdecimal (1.2.0)
   bundler (1.7.6)
   daemon_controller (1.1.8)
   io-console (0.4.2)
   json (1.7.7)
   net-http-persistent (2.9.4)
   passenger (4.0.18)
   psych (2.0.0)
   rack (1.5.2)
   rake (10.0.4)
   rdoc (4.0.1)
   thor (0.18.1)
We see from the above that the activated Rake is of version 10.0.4 that is indicated in the error message shown above. However, we will observe different results if we set the GEM_HOME directory to the directory where we install Gem files using bundle. 

   $ GEM_HOME=/var/www/redmine-2.6.0/.bundle/ruby gem env
   RubyGems Environment:
   ......
   - GEM PATHS:
     - /var/www/redmine-2.6.0/.bundle/ruby
     - /home/foouser/.gem/ruby
     - /usr/share/gems
     - /usr/local/share/gems
   .....
Now /var/www/redmine-2.6.0/.bundle/ruby is in GEM PATHS. 

   $ GEM_HOME=/var/www/redmine-2.6.0/.bundle/ruby gem list

   *** LOCAL GEMS ***

   actionmailer (3.2.19)
   ......
   rake (10.4.0, 10.0.4)
   ......
We now see that the Gem files installed using bundle are listed. It also shows that it finds two version of Rake.
Posted by at
Labels: , ,

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)