How to Install Redmine on CentOS (Detailed) » History » Version 2

Nick Shel, 2012-03-05 11:50

1 1 Nick Shel
h1. How to Install Redmine on CentOS (Detailed)
2 1 Nick Shel
3 1 Nick Shel
{{>toc}}
4 1 Nick Shel
5 1 Nick Shel
h2. Introduction
6 1 Nick Shel
7 2 Nick Shel
I spent a fair bit of time looking for a good issue tracking / project management solution.  Having considered extensively both open source and commercial solutions (up to about $200/month price range like Jira+Confluence and Zoho Projects) I decided to go with Redmine as it offers a good mix of issue tracking and project management capability, most specifically status workflows, sub-tasking and task dependencies and everything else we need.
8 2 Nick Shel
9 2 Nick Shel
However, when I decided to deploy Redmine I encountered numerous difficulties, as at my workplace we use PHP and are not familiar with Ruby on Rails and setting up Ruby on Rails for anyone not familiar with it is rather difficult, largely due to the various version dependencies and incompatibilities and lack of decent detailed documentation on how to do it.  I managed to setup Redmine on Windows XP using MySQL, Apache and Mongrel, but when I tried to install the same setup on Windows Server 2008 I encountered all sorts of issues with RoR and MySQL, so I decided to setup on CentOS, which is what we use for our production web hosting anyway.
10 2 Nick Shel
11 1 Nick Shel
CentOS is one of the most frequently chosen Linux operating systems for Linux based production environments. There is extensive documentation available on setting up CentOS and it is arguably the best choice for deploying and running production Linux servers for organisation with all levels of in-house Linux server deployment and administration capability.
12 1 Nick Shel
13 1 Nick Shel
Redmine is one of the best (if not THE best) open source issue tracking and project management applications, but because it is developed using Ruby on Rails it can be rather complex to deploy for anyone not familiar with the Ruby on Rails environment.
14 1 Nick Shel
15 1 Nick Shel
This How-To provides detailed steps required to get Redmine up and running on a CentOS operating system using the following components:
16 1 Nick Shel
* Apache web server
17 1 Nick Shel
* MySQL database management system
18 1 Nick Shel
* Ruby on Rails
19 1 Nick Shel
* Mod Passenger Apache module
20 1 Nick Shel
21 1 Nick Shel
The How-To provides detailed instructions on the installation and explains what each step does, so that it can be easily follows by people experienced and new to the Ruby on Rails environment.
22 1 Nick Shel
23 1 Nick Shel
h2. Assumptions
24 1 Nick Shel
25 1 Nick Shel
* CentOS is installed and works
26 1 Nick Shel
* Apache is installed and works 
27 1 Nick Shel
* MySQL is installed and works
28 1 Nick Shel
* Your are logged as root
29 1 Nick Shel
* The next steps are done successively without errors
30 1 Nick Shel
31 1 Nick Shel
h2. Installation Instructions
32 1 Nick Shel
33 1 Nick Shel
h3. Install gem and passenger dependencies
34 1 Nick Shel
35 1 Nick Shel
36 1 Nick Shel
37 1 Nick Shel
<pre>
38 1 Nick Shel
yum -y install zlib-devel curl-devel openssl-devel httpd-devel apr-devel apr-util-devel mysql-devel
39 1 Nick Shel
</pre>
40 1 Nick Shel
41 1 Nick Shel
h3. Get Ruby
42 1 Nick Shel
43 1 Nick Shel
<pre>
44 1 Nick Shel
# Create the directory where you will store the Downloads
45 1 Nick Shel
mkdir ~/Downloads # This can be any directory.
46 1 Nick Shel
47 1 Nick Shel
# Change to directory where you will store the download
48 1 Nick Shel
cd ~/Downloads # This can be any directory.
49 1 Nick Shel
50 1 Nick Shel
# FTP to where you will download ruby from.
51 1 Nick Shel
# When asked to login use user/password of anonymous/anonymous
52 1 Nick Shel
ftp ftp.ruby-lang.org 
53 1 Nick Shel
Name (ftp.ruby-lang.org:root): anonymous
54 1 Nick Shel
Password: anonymous
55 1 Nick Shel
56 1 Nick Shel
ftp> cd /pub/ruby
57 1 Nick Shel
ftp> get ruby-1.8.7-pXXX.tar.gz
58 1 Nick Shel
ftp> quit
59 1 Nick Shel
60 1 Nick Shel
# You have now downloaded ruby and need to untar it
61 1 Nick Shel
tar zxvf ruby-1.8.7-pXXX.tar.gz
62 1 Nick Shel
63 1 Nick Shel
# Compile ruby
64 1 Nick Shel
cd ruby-1.8.7-pXXX
65 1 Nick Shel
./configure
66 1 Nick Shel
make
67 1 Nick Shel
make install
68 1 Nick Shel
69 1 Nick Shel
# Verify ruby installation
70 1 Nick Shel
ruby -v
71 1 Nick Shel
which ruby
72 1 Nick Shel
73 1 Nick Shel
# Change back into your downloads directory
74 1 Nick Shel
cd ..
75 1 Nick Shel
</pre>
76 1 Nick Shel
77 1 Nick Shel
h3. Get Gems 1.4.2 (does not work with Gems 1.5)
78 1 Nick Shel
79 1 Nick Shel
<pre>
80 1 Nick Shel
wget http://production.cf.rubygems.org/rubygems/rubygems-1.4.2.tgz
81 1 Nick Shel
tar zxvf rubygems-1.4.2.tgz
82 1 Nick Shel
cd rubygems-1.4.2
83 1 Nick Shel
ruby setup.rb
84 1 Nick Shel
gem -v
85 1 Nick Shel
which gem
86 1 Nick Shel
cd ..
87 1 Nick Shel
</pre>
88 1 Nick Shel
89 1 Nick Shel
h3. Install Passenger (requires gcc)
90 1 Nick Shel
91 1 Nick Shel
<pre>
92 1 Nick Shel
gem install passenger
93 1 Nick Shel
passenger-install-apache2-module
94 1 Nick Shel
</pre>
95 1 Nick Shel
96 1 Nick Shel
An alternate method is to install mod_passenger RPM for Apache from the following location: 
97 1 Nick Shel
http://passenger.stealthymonkeys.com/
98 1 Nick Shel
99 1 Nick Shel
RHEL/CentOS 5
100 1 Nick Shel
<pre>
101 1 Nick Shel
rpm -Uvh http://passenger.stealthymonkeys.com/rhel/5/passenger-release.noarch.rpm
102 1 Nick Shel
yum install mod_passenger
103 1 Nick Shel
</pre>
104 1 Nick Shel
105 1 Nick Shel
RHEL/CentOS 6
106 1 Nick Shel
<pre>
107 1 Nick Shel
rpm --import http://passenger.stealthymonkeys.com/RPM-GPG-KEY-stealthymonkeys.asc
108 1 Nick Shel
yum install http://passenger.stealthymonkeys.com/rhel/6/passenger-release.noarch.rpm
109 1 Nick Shel
yum install mod_passenger
110 1 Nick Shel
</pre>
111 1 Nick Shel
112 1 Nick Shel
h3. Restart Apache
113 1 Nick Shel
114 1 Nick Shel
<pre>service httpd restart</pre>
115 1 Nick Shel
116 1 Nick Shel
h3. Download Redmine
117 1 Nick Shel
118 1 Nick Shel
Download page: http://rubyforge.org/frs/?group_id=1850
119 1 Nick Shel
120 1 Nick Shel
<pre>
121 1 Nick Shel
wget http://rubyforge.org/frs/download.php/75597/redmine-1.3.0.tar.gz  # GET LATEST VERSION ON RUBYFORGE
122 1 Nick Shel
tar zxvf redmine-1.3.0.tar.gz
123 1 Nick Shel
</pre>
124 1 Nick Shel
125 1 Nick Shel
h3. Copy the folder to its HTTP document root folder
126 1 Nick Shel
127 1 Nick Shel
<pre>cp -av redmine-1.3.0/* /var/www/redmine</pre>
128 1 Nick Shel
129 1 Nick Shel
h3. Configure Apache to host the documents
130 1 Nick Shel
131 1 Nick Shel
more information can be found here: [[HowTo configure Apache to run Redmine]]
132 1 Nick Shel
133 1 Nick Shel
h3. Install Bundler
134 1 Nick Shel
135 1 Nick Shel
<pre>gem install bundler</pre>
136 1 Nick Shel
137 1 Nick Shel
h3. Add the Bundler Boot and preinitializer code
138 1 Nick Shel
139 1 Nick Shel
For more info go to the "Bundler site":http://gembundler.com/.
140 1 Nick Shel
141 1 Nick Shel
h3. Create the Gemfile and register these gems in it
142 1 Nick Shel
143 1 Nick Shel
<pre>vi /var/www/redmine/Gemfile</pre>
144 1 Nick Shel
145 1 Nick Shel
<pre>
146 1 Nick Shel
# file: /var/www/redmine/Gemfile
147 1 Nick Shel
source "http://rubygems.org"
148 1 Nick Shel
gem "rake", "0.8.3"
149 1 Nick Shel
gem "rack", "1.1.0"
150 1 Nick Shel
gem "i18n", "0.4.2"
151 1 Nick Shel
gem "rubytree", "0.5.2", :require => "tree"
152 1 Nick Shel
gem "RedCloth", "~>4.2.3", :require => "redcloth" # for CodeRay
153 1 Nick Shel
gem "mysql"
154 1 Nick Shel
gem "coderay", "~>0.9.7"
155 1 Nick Shel
</pre>
156 1 Nick Shel
157 1 Nick Shel
<pre>bundle install</pre>
158 1 Nick Shel
159 1 Nick Shel
h3. Create the Redmine MySQL database
160 1 Nick Shel
161 1 Nick Shel
<pre>
162 1 Nick Shel
yum install mysql-server
163 1 Nick Shel
chkconfig mysqld on
164 1 Nick Shel
service mysqld start
165 1 Nick Shel
/usr/bin/mysql_secure_installation
166 1 Nick Shel
</pre>
167 1 Nick Shel
168 1 Nick Shel
> For MySQL:
169 1 Nick Shel
> start the mysql client (@mysql -u root -p@) and enter the following commands
170 1 Nick Shel
> > <pre>create database redmine character set utf8;
171 1 Nick Shel
create user 'redmine'@'localhost' identified by 'my_password';
172 1 Nick Shel
grant all privileges on redmine.* to 'redmine'@'localhost'; </pre>
173 1 Nick Shel
174 1 Nick Shel
> For versions of MySQL prior to 5.0.2 - skip the 'create user' step and instead:
175 1 Nick Shel
176 1 Nick Shel
> > <pre> grant all privileges on redmine.* to 'redmine'@'localhost' identified by 'my_password';</pre>
177 1 Nick Shel
178 1 Nick Shel
h3. Configure /var/www/redmine/config/database.yml (rename database.yml.example)
179 1 Nick Shel
180 1 Nick Shel
h3. Set the production environment (optional)
181 1 Nick Shel
182 1 Nick Shel
Uncomment the following line in file redmine/config/environment.rb:
183 1 Nick Shel
184 1 Nick Shel
<pre>ENV['RAILS_ENV'] ||= 'production'</pre>
185 1 Nick Shel
186 1 Nick Shel
h3. Generate the session store
187 1 Nick Shel
188 1 Nick Shel
<pre>RAILS_ENV=production bundle exec rake generate_session_store</pre>
189 1 Nick Shel
190 1 Nick Shel
h3. Migrate the database models
191 1 Nick Shel
192 1 Nick Shel
<pre>RAILS_ENV=production bundle exec rake db:migrate</pre>
193 1 Nick Shel
194 1 Nick Shel
h3. Load default data (optional)
195 1 Nick Shel
196 1 Nick Shel
<pre>RAILS_ENV=production bundle exec rake redmine:load_default_data</pre>
197 1 Nick Shel
198 1 Nick Shel
Follow instructions.
199 1 Nick Shel
200 1 Nick Shel
h3. Rename dispatch CGI files in /var/www/redmine/public/
201 1 Nick Shel
202 1 Nick Shel
<pre>
203 1 Nick Shel
mv dispatch.cgi.example dispatch.cgi
204 1 Nick Shel
mv dispatch.fcgi.example dispatch.fcgi
205 1 Nick Shel
mv dispatch.rb.example dispatch.rb
206 1 Nick Shel
</pre>
207 1 Nick Shel
208 1 Nick Shel
h3. Edit .htaccess file for CGI dispatch configuration
209 1 Nick Shel
210 1 Nick Shel
<pre>
211 1 Nick Shel
mv htaccess.fcgi.example .htaccess
212 1 Nick Shel
</pre>
213 1 Nick Shel
214 1 Nick Shel
h3. Chown and Chmod files for read/write access for the Apache user
215 1 Nick Shel
216 1 Nick Shel
<pre>
217 1 Nick Shel
cd ..
218 1 Nick Shel
chown -R apache:apache redmine-1.x
219 1 Nick Shel
chmod -R 755 redmine-1.x
220 1 Nick Shel
</pre>
221 1 Nick Shel
222 1 Nick Shel
h3. Redmine should be fully installed now and fully usable
223 1 Nick Shel
224 1 Nick Shel
Enjoy!