Sep 7, 2012

Install Redmine 2.0.3 on Centos 6.3


The Goals

  • Setup Redmine 2.0.3 running on CentOS 6.3;
  • with MySQL backend, FastCGI to connect Redmine and Apache;
  • integrate Redmine with Subversion;
  • Single sign-on between Apache, Subversion and Redmine using LDAP

Backgrounds

Our company was using the BITNAMI stack with Redmine and Subversion for our production environment. So the goal was about changing the server and migrating the data from Redmine 1.4 to Redmine 2.0.3 including getting all repositories and permissions preserved.

I've tried to avoid webrick but rather use the fastCGI Module for Apache2.

Second was converting the built-in accounts from the database to LDAP (ActiveDirectory). This is the result of 2 days of work and googling is this little tutorial for setting up a mentioned box doing exactly this stuff. We are using CentOS 6 for that task.

"vi/vim" is the editor used this in this tutorial but you can you any editor you want. If my instruction tells you to edit a file, you can find the sequence "..." which means, there is something above or below that line of text, that needs to be edited. Do not include those dots...

Assumptions

  • You have a CentOS 6.3 installation (minimum install) working and SSH access to your Redmine box;
  • You can access the Internet;
  • You are logged in as root.

Redmine Installation Instruction

My personal flavour is to use as less self compiled packages as necessary to get the package up and runnning. So I try to use as many repository packages as possible.

Turn off SELinux

I spent a lot of time to find out, that selinux can be a real party pooper. So I strongly recommend to disable that first before installing anything else. You can find a tutorial inside the howto section describing how to enable SELinux for your installation.

vi /etc/selinux/config  

find the line with SELINUX and set it to

...  SELINUX=disabled  ...  

Do a reboot NOW

Install basic services (Apache, mySQL, and several tools...)

Now we are good to go to install some tools that might be useful during our installation...

First of all, update your system, make sure it is up to date,

yum update  

and then install some prerequisite packages to the setup,

yum -y install wget vim \\         system-config-network system-config-firewall vim openssh-clients  

anhd some packages needed for Redmine

yum -y install httpd mysql mysql-server   

After that continue and install all packages that might be necessary during the ruby and redmine installation.
yum -y install ruby rubygems   yum -y install zlib-devel curl-devel openssl-devel httpd-devel apr-devel apr-util-devel mysql-devel gcc ruby-devel \\        gcc-c++ make postgresql-devel ImageMagick-devel sqlite-devel perl-LDAP mod_perl perl-Digest-SHA  

Configure basic services

Let's configure the basic services, first of all, make mySQL and Apache to start at boot

chkconfig httpd on --level 35  chkconfig mysqld on --level 35  

After configuring these, start them up
service httpd start  service mysqld start  

Now configure your new mySQL Installation and follow the instructions. Please note/write down administrator password to MySQL you've just installed.
/usr/bin/mysql_secure_installation  

Configure passenger for Apache

You need to install Passenger for Apache using gem. Do the following on the command line

gem install passenger  passenger-install-apache2-module  

Please notice the installation messages! The next .conf file might use another path or version!
After this you need to generate a conf file with the displayed content
vi /etc/httpd/conf.d/ruby.conf  

During my installation the following content was displayed and needs to be entered in that file:
   LoadModule passenger_module /usr/lib/ruby/gems/1.8/gems/passenger-3.0.15/ext/apache2/mod_passenger.so     PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-3.0.15     PassengerRuby /usr/bin/ruby  

Restart your apache with
service httpd restart  

Get Redmine and install it

change to your home directory and download the latest version, expand it and copy it to the right place.

cd  wget http://rubyforge.org/frs/download.php/76259/redmine-2.0.3.tar.gz  tar xvfz redmine-2.0.3.tar.gz  mkdir -p /var/www/redmine  cp redmine-2.0.3/* /var/www/redmine  

or you can do

cd /var/www  wget http://rubyforge.org/frs/download.php/76259/redmine-2.0.3.tar.gz  tar xvfz redmine-2.0.3.tar.gz  ln -s redmine-2.0 redmine  

Next is to install bundler and let it install the production environment (with automatic resolve)
Now change to this directory - this is your new Redmine application directory!

cd /var/www/redmine  gem install bundler  bundle install --without development test  

fetch some coffee... this might take some time...

Create Redmine database

Next to generate a new database for redmine
Log on to your database with the following command. If prompted for a password, enter it.

mysql -u root -p  

I tend to create a local only user for that database, change the password 'very_secret' to a better one :)
create database redmine character set utf8;  create user 'redmine'@'localhost' identified by 'very_secret';  grant all privileges on redmine.* to 'redmine'@'localhost';   quit;  

Note: If you are going to store Redmine's database to a machine that is not the server you are going to install Redmine - whose IP address is 192.168.10.100, the settings should be:

create database redmine character set utf8;  create user 'redmine'@'192.168.10.100' identified by 'very_secret';  grant all privileges on redmine.* to 'redmine'@'192.168.10.100';   quit;  

Configure Redmine

First of all, copy the example config to a productive one and edit the config for your needs

cd /var/www/redmine/config  cp database.yml.example database.yml  vi /var/www/redmine/config/database.yml  

Now find the production section inside this file and edit it like that
...  production:  # adapter = mysql2 is newer and proven to be more better than mysql  # adapter: mysql2    adapter: mysql    database: redmine    host: localhost    username: redmine    password: very_secret    encoding: utf8  ...  

Head back to your application directory and generate a secret token
cd /var/www/redmine/  rake generate_secret_token  

Now it is about time to generate the database structure (application directory!)
cd /var/www/redmine/  RAILS_ENV=production rake db:migrate  

fill the database with default values...
cd /var/www/redmine/  RAILS_ENV=production rake redmine:load_default_data  

follow the instructions to select your language.

Mind the firewall!

Be aware that the firewall is enabled by default (which is good!). So if you know which ports to open, do it now or disable the firewall (just for testing purposes). I'd really recommend disabling the firewall during installation and enable it (opening ports) after you are sure that everything works.

system-config-firewall  

use the onscreen menu to disable it or adjust the values.

or simply disable iptables during Redmine's setup

service iptables stop  

Do a testdrive!

I mentioned that I wanted not to use webrick, but for a testdrive, it'll work. This helps finding bugs and errors that might have occured before.

cd /var/www/redmine/  ruby script/rails server webrick -e production  

Open up a browser and point it to: http://yoursystemname.yourdomain.com:3000 - the default username and password is 'admin'.
If everything is working, you are good to go! Kill webrick by hitting Ctrl+C.

Activate FCGI and generate plugin directory

To activate the fcgi module you need to copy the example file and edit the very first line. During this step it is recommended to generate the default .htaccess config as well.

cd /var/www/redmine/public  mkdir plugin_assets  cp dispatch.fcgi.example dispatch.fcgi  cp htaccess.fcgi.example .htaccess  vi /var/www/redmine/public/dispatch.fcgi  

now edit dispatch.fcgi and change it like this...
#!/usr/bin/ruby  ...  

Apache permissions!

this one is important, so don't miss that one...

chown -R apache:apache /var/www/redmine/  

Note: "apache" is the user that runs httpd (apache) service, as defined in /etc/password and /etc/httpd/conf/httpd.conf

Getting Apache to work with FastCGI

Unfortunately the default Repo from CentOS cannot deliver the fcgid module so it is important to include a replo, that can deliver this package. I use the Fedora Repo so it is time to activate this... Again - this can change so please take care which repository to use.

rpm --import https://fedoraproject.org/static/0608B895.txt  wget http://dl.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-7.noarch.rpm  rpm -ivh epel-release-6-7.noarch.rpm  yum -y install mod_fcgid  

Set the file path for Redmine

I wanted to move the files to another location, so I decided to move them to /opt/redmine

mkdir -p /opt/redmine/files  chown -R apache:apache /opt/redmine  

now edit the configuration
cd /var/www/redmine/config  cp configuration.yml.example configuration.yml  vi /var/www/redmine/config/configuration.yml  

edit the path settings inside this file...
...    attachments_storage_path: /opt/redmine/files  ...  

Telling Apache to serve REDMINE

The final step is to tell apache, where to find Redmine and what to do with it. Generate a new conf file for your virtual host to serve redmine...

vi /etc/httpd/conf.d/redmine.conf  

and enter the following config (adjust to your needs ;) )
<VirtualHost *:80>          ServerName yoursystemname.yourdomain.com          ServerAdmin yourmail@yourdomain.com          DocumentRoot /var/www/redmine/public/          ErrorLog logs/redmine_error_log            MaxRequestLen 20971520            <Directory "/var/www/redmine/public/">                    Options Indexes ExecCGI FollowSymLinks                  Order allow,deny                  Allow from all                  AllowOverride all          </Directory>  </VirtualHost>  

Restart Apache and cross your fingers, wheter you can access http://yoursystemname.yourdomain.com - redmine should be available right now...
service httpd restart  

Additional Config: E-Mail System

in order to get emails sent to your clients, edit the configuration.yml and enter your server settings...

vi /var/www/redmine/config/configuration.yml  

now find the settings for your server... the following settings describe an anonymous relay on an internal server. You need to remove the username and password line if you use anonymous sign on.
...  default:    # Outgoing emails configuration (see examples above)    email_delivery:      delivery_method: :smtp      smtp_settings:        address: mailserver.yourdomain.com        port: 25        domain: yourdomain.com  ...  

Here is the configration if you use Google's SMTP server

production:    email_delivery:      delivery_method: :smtp      smtp_settings:  #      tls: true        enable_starttls_auto: true        address: "smtp.gmail.com"         port: '587'        domain: "smtp.gmail.com"         authentication: :plain        user_name: "google-account-name@domain-name.domain-extension"         password: "password"   

Getting Subversion working

After getting Redmine working, it is time to get Subversion working... The goal is to integrate the repositories inside Redmine and host them on the same server...

Installing Packages for Subversion

Install the following packages

yum -y install mod_dav_svn subversion subversion-ruby  

Linking authentication for Redmine

Redmine provides a perl module to handle Apache authentication on SVN DAV repositories. First step is to link that module into the search path

mkdir /usr/lib/perl5/vendor_perl/Apache  ln -s /var/www/redmine/extra/svn/Redmine.pm /usr/lib/perl5/vendor_perl/Apache/Redmine.pm  

Creating a path for subversion repositories

create a path and set permissions for your SVN repo...

mkdir /opt/subversion  chown -R apache:apache /opt/subversion  

Edit virtual host for apache to serve SVN with redmine

to get Apache working with subversion, you need to adjust (create) the virtual host file

vi /etc/httpd/conf.d/subversion.conf  

now enter/edit the following
PerlLoadModule Apache::Redmine  <Location /svn>          DAV svn          SVNParentPath "/opt/subversion"           SVNListParentPath on          Order deny,allow          Deny from all          Satisfy any          LimitXMLRequestBody 0          SVNPathAuthz off            PerlAccessHandler Apache::Authn::Redmine::access_handler          PerlAuthenHandler Apache::Authn::Redmine::authen_handler          AuthType Basic          AuthName "Redmine SVN Repository"             Require valid-user          RedmineDSN "DBI:mysql:database=redmine;host=localhost:3306"           RedmineDbUser "redmine"           RedmineDbPass "very_secret"             # cache max. 50 passwords          RedmineCacheCredsMax 50  </Location>  

Achievements

What we've done at this point:
  • A running Redmine v2.0.3 installation using Apache Passenger
  • Working authentication with Redmine's built-in database
  • Working Subversion with Apache's WebDav
  • Subversion authentication against redmine's built-in database

Authentication against Active Directory

The last step requires some knowledge how to authenticate against your Active directory. First of all, open up Redmine in a web interface and enter the Administration dialogue. Select LDAP-Authentication adn create a new authentication entry.

  • Name: Enter a NAME for your entry, this can be anything...
  • Host: Enter the IP address of a domain controler unless you are really sure, that DNS is working correctly
  • Port: 389
  • Account: This one is kind of a pitfall. Enter the DN of the user object that can authenticate against the Active Directory.
    EXAMPLE: Assume that you have a domain that is called: mynetwork.local and an organizational unit that is named: myUsers. The DN of this organizational unit is: OU=myUsers, DC=mynetwork, DC=local If you create a user, which Display name is like ldap authentication user then the Account you need to enter is: CN=ldap authentication user, OU=myUsers, DC=mynetwork, DC=local. I'd recommend using a tool like Sysinternals ADExplorer if you are unsure about the distinguished name of your authentication user.
  • Base DN: This is the entry point, where Redmine tries to find users. In the example above you want to enter: OU=myUsers, DC=mynetwork, DC=local
  • LDAP Filter: You can enter any filter you like here, a valid filter for finding users is: (&(objectClass=user)(objectCategory=person)).
  • On-the-fly Usercreation: I tend to check this.. This allows the initial creation of a new user when the user logs on redmine.
Attributes: (I am not sure, whether the fields below are correctly tranlsated... please correct if necessary)
  • member name: sAMAccountName
  • first name: givenname
  • surname: sn
  • E-Mail: mail

Save it, try it :)

You should be able to log on with your Windows logon name and your Windows passwort. If you've never logged on a new account should have been created within the Redmine's built-in database.

Authenticate Subversion against Active Directory

Note: Using the built-in database provided by Redmine.

This one is tricky, you want the authentication data from Active Directory but you also want the group permissions from Redmine. So you need to tell the logon mechanism to authenticate against AD and check inside the database, whether the user is SVN editor or not. Finally most of the work is done here with the redmine.pm script (remember, we've linked that already).

Fortunatelly the CentOS Perl implementation includes no module for Simple::LDAP. So we need to do some compiler work...

First of all, fetch the packages needed for building the necessary Perl modules.

yum -y install perl-CPAN perl-YAML  

There are a lot of dependencies when trying to build the module, so I recommend to turn on automatic dependency handling inside the CPAN shell....
Start up the shell:

perl -MCPAN -e shell  

and then run the following two commands:
o conf prerequisites_policy follow  o conf commit  

Now it is time, to install the module, still inside the shell. Enter
install Authen::Simple::LDAP  

This takes some time... If queried for any dependencies or defaults, just acknowledge them with their default values - this should work.
Close the shell after everything is done by entering
exit  

Now we need to tell Apache where to find the authentication data, this is simple by editing the subversion.conf

vi /etc/httpd/conf.d/subversion.conf  

just add the Simple::LDAP Perl module by editing it this way:
   ...     PerlLoadModule Apache::Redmine     PerlLoadModule  Authen::Simple::LDAP     <Location /svn>       DAV svn       ...  

Restart Apache and LDAP Authentication should work now

service httpd restart    http://www.redmine.org/projects/redmine/wiki/Redmine_203_with_Subversion_and_LDAP_Authentication_%28for_Redmine_and_Subversion_through_Redmine%29_on_Centos_6_i386_-_detailed?version=24   
--   Best Regards,  Nguyen Hung Vu [aka: NVH] ( in Vietnamese: Nguyễn Vũ Hưng )  vuhung16plus{remove}@gmail.dot.com , YIM: vuhung16 , Skype:  vuhung16plus, twitter: vuhung, MSN: vuhung16.  http://www.facebook.com/nguyenvuhung  Nguyễn Vũ Hưng's blog on Free and Open Source:  http://nguyenvuhungvietnam.wordpress.com/  Học tiếng Nhật: http://hoc-tiengnhat.blogspot.com/  Vietnamese LibreOffice: http://libo-vi.blogspot.com/  Mozilla & Firefox tiếng Việt: http://mozilla-vi.blogspot.com/    Disclaimer: When posted to social networking groups include, but not limited Linux Users' Groups,  Free and Open Sources forums, mailing lists, the above is my personal opinion and is *not*  the opinion of my employer(s), associations and/or groups I join.

2 comments:

Anonymous said...

Hi Guy,
your post help me so much! Thank you.

Fernando

Anonymous said...

ωonԁеrful poіnts altogether, you juѕt gаined a nеw rеadeг.
Whаt could you гecommend about yοur put up that you
sіmplу made ѕome dаys in the pаst?
Any ѕuгe?

Alsο ѵіѕit my web blοg ... unlock iphone for Verizon