Project

General

Profile

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

Hung Nguyen Vu, 2012-08-31 06:14
added "The Goals"

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