Project

General

Profile

Redmine 203 with Subversion and LDAP Authentication (for Redmine and Subversion through Redmine) on Centos 6 i386 - detailed » History » Version 24

Hung Nguyen Vu, 2012-08-31 06:29
Sutble changes

1 24 Hung Nguyen Vu
h1. Install Redmine 2.0.3 on Centos 6.3
2 2 Sven Nosse
3 20 Hung Nguyen Vu
{{>toc}} 
4 1 Sven Nosse
5 21 Hung Nguyen Vu
6 20 Hung Nguyen Vu
h2. The Goals
7 21 Hung Nguyen Vu
8 20 Hung Nguyen Vu
* Setup Redmine 2.0.3 running on CentOS 6.3;
9
* with MySQL backend, FastCGI to connect Redmine and Apache;
10
* integrate Redmine with Subversion;
11
* Single sign-on between Apache, Subversion and Redmine using LDAP
12 1 Sven Nosse
13 20 Hung Nguyen Vu
h2. Backgrounds
14
15 1 Sven Nosse
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. 
16
17
I've tried to avoid webrick but rather use the fastCGI Module for Apache2. 
18
19 20 Hung Nguyen Vu
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. 
20 6 Hung Nguyen Vu
21 20 Hung Nguyen Vu
"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...
22 1 Sven Nosse
23
h2. Assumptions
24 2 Sven Nosse
25 20 Hung Nguyen Vu
* You have a CentOS 6.3 installation (minimum install) working and SSH access to your Redmine box;
26
* You can access the Internet;
27
* You are logged in as root.
28 6 Hung Nguyen Vu
29 2 Sven Nosse
h2. Redmine Installation Instruction
30
31
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.
32 6 Hung Nguyen Vu
33 20 Hung Nguyen Vu
h3. Turn off SELinux
34 6 Hung Nguyen Vu
35 2 Sven Nosse
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.
36
<pre>
37
vi /etc/selinux/config
38
</pre>
39 1 Sven Nosse
40 2 Sven Nosse
find the line with SELINUX and set it to
41
<pre>
42
...
43
SELINUX=disabled
44
...
45
</pre>
46
Do a reboot *NOW*
47 6 Hung Nguyen Vu
48 2 Sven Nosse
h3. Install basic services (Apache, mySQL, and several tools...)
49 9 Hung Nguyen Vu
50
Now we are good to go to install some tools that might be useful during our installation... 
51
52 1 Sven Nosse
First of all, update your system, make sure it is up to date,
53
<pre>
54 9 Hung Nguyen Vu
yum update
55
</pre>
56
57
and then install some prerequisite packages to the setup,
58
<pre>
59
yum -y install wget vim \\
60
       system-config-network system-config-firewall vim openssh-clients
61
</pre>
62
63
anhd some packages needed for Redmine
64 2 Sven Nosse
<pre>
65 1 Sven Nosse
yum -y install httpd mysql mysql-server 
66 2 Sven Nosse
</pre>
67
After that continue and install all packages that might be necessary during the ruby and redmine installation.
68
<pre>
69 6 Hung Nguyen Vu
yum -y install ruby rubygems 
70
yum -y install zlib-devel curl-devel openssl-devel httpd-devel apr-devel apr-util-devel mysql-devel gcc ruby-devel \\
71 2 Sven Nosse
      gcc-c++ make postgresql-devel ImageMagick-devel sqlite-devel perl-LDAP mod_perl perl-Digest-SHA
72
</pre>
73
74
h3. Configure basic services
75 6 Hung Nguyen Vu
76 2 Sven Nosse
Let's configure the basic services, first of all, make mySQL and Apache to start at boot
77 18 Hung Nguyen Vu
<pre>
78
chkconfig httpd on --level 35
79 2 Sven Nosse
chkconfig mysqld on --level 35
80
</pre>
81 1 Sven Nosse
After configuring these, start them up
82 2 Sven Nosse
<pre>
83
service httpd start
84
service mysqld start
85 18 Hung Nguyen Vu
</pre>
86 2 Sven Nosse
Now configure your new mySQL Installation and follow the instructions. Please note/write down administrator password to MySQL you've just installed.
87
<pre>
88
/usr/bin/mysql_secure_installation
89
</pre>
90
91
h3. Configure passenger for Apache
92
93 20 Hung Nguyen Vu
You need to install Passenger for Apache using gem. Do the following on the command line
94 2 Sven Nosse
<pre>
95
gem install passenger
96
passenger-install-apache2-module
97
</pre>
98
Please notice the installation messages! The next .conf file might use another path or version! 
99
After this you need to generate a conf file with the displayed content
100
<pre>
101
vi /etc/httpd/conf.d/ruby.conf
102
</pre>
103
During my installation the following content was displayed and needs to be entered in that file:
104
<pre>
105
   LoadModule passenger_module /usr/lib/ruby/gems/1.8/gems/passenger-3.0.15/ext/apache2/mod_passenger.so
106
   PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-3.0.15
107
   PassengerRuby /usr/bin/ruby
108
</pre>
109
Restart your apache with
110
<pre>
111
service httpd restart
112
</pre>
113 1 Sven Nosse
114
h3. Get Redmine and install it
115
116
change to your home directory and download the latest version, expand it and copy it to the right place.
117
<pre>
118
cd
119
wget http://rubyforge.org/frs/download.php/76259/redmine-2.0.3.tar.gz
120 11 Hung Nguyen Vu
tar xvfz redmine-2.0.3.tar.gz
121 12 Hung Nguyen Vu
mkdir -p /var/www/redmine
122 1 Sven Nosse
cp redmine-2.0.3/* /var/www/redmine
123 6 Hung Nguyen Vu
</pre>
124
125
or you can do
126
127
<pre>
128
cd /var/www
129
wget http://rubyforge.org/frs/download.php/76259/redmine-2.0.3.tar.gz
130
tar xvfz redmine-2.0.3.tar.gz
131
ln -s redmine-2.0 redmine
132
</pre>
133 1 Sven Nosse
134
Next is to install bundler and let it install the production environment (with automatic resolve)
135 2 Sven Nosse
Now change to this directory - *this is your new Redmine application directory!*
136
<pre>
137
cd /var/www/redmine
138
gem install bundler
139 1 Sven Nosse
bundle install --without development test
140 10 Hung Nguyen Vu
</pre>
141 2 Sven Nosse
fetch some coffee... this might take some time...
142
143
h3. Create Redmine database
144 6 Hung Nguyen Vu
145 14 Sven Nosse
Next to generate a new database for redmine
146 2 Sven Nosse
Log on to your database with the following command. If prompted for a password, enter it.
147
<pre>
148
mysql -u root -p
149
</pre>
150
I tend to create a local only user for that database, change the password 'very_secret' to a better one :)
151
<pre>
152
create database redmine character set utf8;
153
create user 'redmine'@'localhost' identified by 'very_secret';
154
grant all privileges on redmine.* to 'redmine'@'localhost'; 
155
quit;
156
</pre>
157 19 Hung Nguyen Vu
158
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: 
159
<pre>
160
create database redmine character set utf8;
161
create user 'redmine'@'192.168.10.100' identified by 'very_secret';
162
grant all privileges on redmine.* to 'redmine'@'192.168.10.100'; 
163
quit;
164
</pre>
165
166 2 Sven Nosse
167
h3. Configure Redmine
168
169
First of all, copy the example config to a productive one and edit the config for your needs
170
<pre>
171
cd /var/www/redmine/config
172
cp database.yml.example database.yml
173
vi /var/www/redmine/config/database.yml
174
</pre>
175
Now find the production section inside this file and edit it like that
176
<pre>
177
...
178 13 Hung Nguyen Vu
production:
179
# adapter = mysql2 is newer and proven to be more better than mysql
180 2 Sven Nosse
# adapter: mysql2
181
  adapter: mysql
182
  database: redmine
183
  host: localhost
184
  username: redmine
185
  password: very_secret
186
  encoding: utf8
187
...
188
</pre>
189
Head back to your application directory and generate a secret token
190
<pre>
191
cd /var/www/redmine/
192
rake generate_secret_token
193 1 Sven Nosse
</pre>
194
Now it is about time to generate the database structure (application directory!)
195 2 Sven Nosse
<pre>
196
cd /var/www/redmine/
197
RAILS_ENV=production rake db:migrate
198
</pre>
199 1 Sven Nosse
fill the database with default values...
200 2 Sven Nosse
<pre>
201
cd /var/www/redmine/
202
RAILS_ENV=production rake redmine:load_default_data
203
</pre>
204
follow the instructions to select your language.
205 6 Hung Nguyen Vu
206 2 Sven Nosse
h3. Mind the firewall!
207 6 Hung Nguyen Vu
208 1 Sven Nosse
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.
209 2 Sven Nosse
<pre>
210
system-config-firewall
211
</pre>
212
use the onscreen menu to disable it or adjust the values.
213 8 Hung Nguyen Vu
214
or simply disable iptables during Redmine's setup
215
<pre>
216
service iptables stop
217
</pre>
218 6 Hung Nguyen Vu
219 2 Sven Nosse
h3. Do a testdrive!
220
221
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.
222
<pre>
223
cd /var/www/redmine/
224
ruby script/rails server webrick -e production
225
</pre>
226
Open up a browser and point it to: http://yoursystemname.yourdomain.com:3000 - the default username and password is 'admin'.
227
If everything is working, you are good to go! Kill webrick by hitting Ctrl+C.
228 6 Hung Nguyen Vu
229 2 Sven Nosse
h3. Activate FCGI and generate plugin directory
230
231
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.
232
<pre>
233
cd /var/www/redmine/public
234
mkdir plugin_assets
235
cp dispatch.fcgi.example dispatch.fcgi
236 1 Sven Nosse
cp htaccess.fcgi.example .htaccess
237
vi /var/www/redmine/public/dispatch.fcgi
238 2 Sven Nosse
</pre>
239
now edit dispatch.fcgi and change it like this...
240
<pre>
241
#!/usr/bin/ruby
242
...
243
</pre>
244
245
h3. Apache permissions!
246
247 1 Sven Nosse
this one is important, so don't miss that one... 
248 2 Sven Nosse
<pre>
249 1 Sven Nosse
chown -R apache:apache /var/www/redmine/
250 2 Sven Nosse
</pre>
251 6 Hung Nguyen Vu
252
Note: "apache" is the user that runs httpd (apache) service, as defined in /etc/password and /etc/httpd/conf/httpd.conf 
253 2 Sven Nosse
254
h3. Getting Apache to work with FastCGI
255
256
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.
257
<pre>
258
rpm --import https://fedoraproject.org/static/0608B895.txt
259
wget http://dl.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-7.noarch.rpm
260
rpm -ivh epel-release-6-7.noarch.rpm
261
yum -y install mod_fcgid
262
</pre>
263 6 Hung Nguyen Vu
264 2 Sven Nosse
h3. Set the file path for Redmine
265
266
I wanted to move the files to another location, so I decided to move them to /opt/redmine
267 6 Hung Nguyen Vu
<pre>
268 2 Sven Nosse
mkdir -p /opt/redmine/files
269
chown -R apache:apache /opt/redmine
270
</pre>
271
now edit the configuration
272
<pre>
273
cd /var/www/redmine/config
274
cp configuration.yml.example configuration.yml
275
vi /var/www/redmine/config/configuration.yml
276
</pre>
277
edit the path settings inside this file...
278
<pre>
279
...
280
  attachments_storage_path: /opt/redmine/files
281
...
282
</pre>
283
284
h3. Telling Apache to serve REDMINE
285
286
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...
287
<pre>
288
vi /etc/httpd/conf.d/redmine.conf
289
</pre>
290
and enter the following config (adjust to your needs ;) )
291
<pre>
292
<VirtualHost *:80>
293
        ServerName yoursystemname.yourdomain.com
294
        ServerAdmin yourmail@yourdomain.com
295
        DocumentRoot /var/www/redmine/public/
296
        ErrorLog logs/redmine_error_log
297
298
        MaxRequestLen 20971520
299
300
        <Directory "/var/www/redmine/public/">
301
302
                Options Indexes ExecCGI FollowSymLinks
303
                Order allow,deny
304
                Allow from all
305
                AllowOverride all
306
        </Directory>
307
</VirtualHost>
308
</pre>
309
Restart Apache and cross your fingers, wheter you can access http://yoursystemname.yourdomain.com - redmine should be available right now...
310
<pre>
311
service httpd restart
312
</pre>
313
314
h3. Additional Config: E-Mail System
315 1 Sven Nosse
316
in order to get emails sent to your clients, edit the configuration.yml and enter your server settings...
317
<pre>
318
vi /var/www/redmine/config/configuration.yml
319
</pre>
320
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.
321
<pre>
322
...
323
default:
324
  # Outgoing emails configuration (see examples above)
325
  email_delivery:
326
    delivery_method: :smtp
327
    smtp_settings:
328
      address: mailserver.yourdomain.com
329
      port: 25
330
      domain: yourdomain.com
331
...
332
</pre>
333 6 Hung Nguyen Vu
334
Here is the configration if you use Google's SMTP server
335
336
<pre>
337
production:
338
  email_delivery:
339
    delivery_method: :smtp
340
    smtp_settings:
341
#      tls: true
342
      enable_starttls_auto: true
343
      address: "smtp.gmail.com"
344
      port: '587'
345
      domain: "smtp.gmail.com"
346
      authentication: :plain
347
      user_name: "google-account-name@domain-name.domain-extension"
348
      password: "password"
349
</pre>
350 1 Sven Nosse
351 2 Sven Nosse
h2. Getting Subversion working
352
353
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...
354
355
h3. Installing Packages for Subversion
356
357 1 Sven Nosse
Install the following packages
358 2 Sven Nosse
<pre>
359
yum -y install mod_dav_svn subversion subversion-ruby
360
</pre>
361
362
h3. Linking authentication for Redmine
363
364
Redmine provides a perl module to handle Apache authentication on SVN DAV repositories. First step is to link that module into the search path
365
<pre>
366
mkdir /usr/lib/perl5/vendor_perl/Apache
367
ln -s /var/www/redmine/extra/svn/Redmine.pm /usr/lib/perl5/vendor_perl/Apache/Redmine.pm
368
</pre>
369 16 Sven Nosse
370 2 Sven Nosse
h3. Creating a path for subversion repositories
371
372
create a path and set permissions for your SVN repo...
373
<pre>
374
mkdir /opt/subversion
375
chown -R apache:apache /opt/subversion
376
</pre>
377 6 Hung Nguyen Vu
378 2 Sven Nosse
h3. Edit virtual host for apache to serve SVN with redmine
379
380
to get Apache working with subversion, you need to adjust (create) the virtual host file
381
<pre>
382
vi /etc/httpd/conf.d/subversion.conf
383
</pre>
384
now enter/edit the following
385
<pre>
386
PerlLoadModule Apache::Redmine
387
<Location /svn>
388
        DAV svn
389
        SVNParentPath "/opt/subversion"
390
        SVNListParentPath on
391
        Order deny,allow
392
        Deny from all
393
        Satisfy any
394
        LimitXMLRequestBody 0
395
        SVNPathAuthz off
396
397
        PerlAccessHandler Apache::Authn::Redmine::access_handler
398
        PerlAuthenHandler Apache::Authn::Redmine::authen_handler
399
        AuthType Basic
400
        AuthName "Redmine SVN Repository"
401
402
        Require valid-user
403
        RedmineDSN "DBI:mysql:database=redmine;host=localhost:3306"
404 15 Sven Nosse
        RedmineDbUser "redmine"
405 2 Sven Nosse
        RedmineDbPass "very_secret"
406
407 1 Sven Nosse
        # cache max. 50 passwords
408
        RedmineCacheCredsMax 50
409 14 Sven Nosse
</Location>
410
</pre>
411 17 Hung Nguyen Vu
412 14 Sven Nosse
h3. Achievements
413 17 Hung Nguyen Vu
414
What we've done at this point:
415
* A running Redmine v2.0.3 installation using Apache Passenger
416 24 Hung Nguyen Vu
* Working authentication with Redmine's built-in database
417 17 Hung Nguyen Vu
* Working Subversion with Apache's WebDav
418 24 Hung Nguyen Vu
* Subversion authentication against redmine's built-in database
419 14 Sven Nosse
420
h2. Authentication against Active Directory
421
422
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.
423
424
* Name: Enter a NAME for your entry, this can be anything... 
425
* Host: Enter the IP address of a domain controler unless you are really sure, that DNS is working correctly
426
* Port: 389
427
* Account: This one is kind of a pitfall. Enter the DN of the user object that can authenticate against the Active Directory.
428
??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.
429
* 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@
430
* LDAP Filter: You can enter any filter you like here, a valid filter for finding users is: @(&(objectClass=user)(objectCategory=person))@. 
431
* On-the-fly Usercreation: I tend to check this.. This allows the initial creation of a new user when the user logs on redmine.
432
433
Attributes: _(I am not sure, whether the fields below are correctly tranlsated... please correct if necessary)_
434
* member name: sAMAccountName
435
* first name: givenname
436
* surname: sn
437
* E-Mail: mail
438
439
Save it, try it :)
440
441 24 Hung Nguyen Vu
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.
442 14 Sven Nosse
443 22 Hung Nguyen Vu
h2. Authenticate Subversion against Active Directory 
444 14 Sven Nosse
445 24 Hung Nguyen Vu
Note: Using the built-in database provided by Redmine.
446 1 Sven Nosse
447 22 Hung Nguyen Vu
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). 
448
449
Fortunatelly the CentOS Perl implementation includes no module for Simple::LDAP. So we need to do some compiler work... 
450
451
First of all, fetch the packages needed for building the necessary Perl modules.
452 14 Sven Nosse
<pre>
453
yum -y install perl-CPAN perl-YAML
454
</pre>
455
456
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....
457
Start up the shell:
458
<pre>
459
perl -MCPAN -e shell
460
</pre>
461
and then run the following two commands:
462
<pre>
463
o conf prerequisites_policy follow
464
o conf commit
465
</pre>
466
Now it is time, to install the module, still inside the shell. Enter
467
<pre>
468
install Authen::Simple::LDAP
469
</pre>
470
This takes some time... If queried for any dependencies or defaults, just acknowledge them with their default values - this should work.
471
Close the shell after everything is done by entering
472
<pre>
473
exit
474
</pre>
475
476
Now we need to tell Apache where to find the authentication data, this is simple by editing the subversion.conf
477
<pre>
478
vi /etc/httpd/conf.d/subversion.conf
479
</pre>
480
just add the Simple::LDAP Perl module by editing it this way:
481
<pre>
482
   ...
483
   PerlLoadModule Apache::Redmine
484
   PerlLoadModule  Authen::Simple::LDAP
485
   <Location /svn>
486
     DAV svn
487
     ...
488
</pre>
489
490
Restart Apache and LDAP Authentication should work now
491
<pre>
492 2 Sven Nosse
service httpd restart
493 1 Sven Nosse
</pre>