Project

General

Profile

HowTo configure Redmine for advanced git integration » History » Version 20

Mr. DTTH, 2013-08-08 04:47

1 1 Felix Schäfer
h1. HowTo configure Redmine for advanced git integration
2
3 3 Felix Schäfer
{{>TOC}}
4
5 1 Felix Schäfer
h2. Scope
6
7 17 Mr. DTTH
This HowTo explains how to serve git repositories on apache through the http-based "git-smart-http protocol":http://progit.org/2010/03/04/smart-http.html introduced in git 1.6.6. 
8 1 Felix Schäfer
9 17 Mr. DTTH
The git-smart-http offers various advantages over ssh or git-based access: you can use redmine access control as-is, no need for extra ssh keys or whatnot, you can secure it through SSL as needed, and there's generally less problems with firewalls and https/https ports than exist with ssh and git ports. git-smart-http also doesn't have some of the drawbacks of its "dumb" predecessor, as it doesn't require any complex DAV setup.
10 1 Felix Schäfer
11 17 Mr. DTTH
This HowTo is mainly written from memory and was conducted on a setup which was already serving [[Repositories_access_control_with_apache_mod_dav_svn_and_mod_perl|svn repositories integrated with redmine]], so it might be possible that I forgot some things or take them for granted. 
12
13
This is a wiki page, feel free to correct or amend anything you find lacking :-) You can also "drop me a line":/users/3866.
14
15 7 Felix Schäfer
Another option to integrate grack with redmine is the "modified grack+redmine plugin":http://github.com/friflaj/redmine_grack or "any other grack modified for redmine":http://github.com/search?q=grack&type=Everything&repo=&langOverride=&start_value=1, though those ones lack documentation and I haven't tried them, so I can't say much about those.
16 1 Felix Schäfer
17
h2. Prerequisites
18
19
* Apache with mod_perl (access control)
20
* git (version at least 1.6.6)
21
* A way to serve git-smart-http
22 10 Hallison Vasconcelos Batista
** mod_cgi (or mod_cgid) if you want to use the stock "git-http-backend":http://www.kernel.org/pub/software/scm/git/docs/git-http-backend.html
23 1 Felix Schäfer
** a rack server if you want to use "grack":http://github.com/schacon/grack (basically a rack wrapper around the right git commands) or
24 10 Hallison Vasconcelos Batista
"git-webby":http://git.io/BU7twg (another implementation based on grack but written in Sinatra).
25 1 Felix Schäfer
26 17 Mr. DTTH
You should already have a rack server to run redmine, and that's why I chose grack as the backend and which I will describe in this tutorial. 
27 1 Felix Schäfer
28 17 Mr. DTTH
Using the stock git-http-backend should be quite straightforward though (skip the [[HowTo_configure_Redmine_for_advanced_git_integration#Install-grack|grack installation]] part and get your install with the git-http-backend going (the "git-http-backend manpage":http://www.kernel.org/pub/software/scm/git/docs/git-http-backend.html has some examples), when that's done go on with the [[HowTo_configure_Redmine_for_advanced_git_integration#Access-control|access control]] part).
29
30 20 Mr. DTTH
h2. Install Git
31
32
<pre><code class="bash">
33
yum install git
34
</code></pre>
35
36 2 Felix Schäfer
h2. Install grack
37 1 Felix Schäfer
38 3 Felix Schäfer
h3. Get the sources
39 2 Felix Schäfer
40 19 Mr. DTTH
Fetch grack from its "github repository":http://github.com/schacon/grack, I checked out mine to @/var/www/grack@
41 1 Felix Schäfer
42 19 Mr. DTTH
<pre><code class="bash">
43
cd /var/www
44
git clone http://github.com/schacon/grack.git
45
</code></pre>
46 1 Felix Schäfer
47 18 Mr. DTTH
And create a directory for repositories :
48
49
<pre><code class="bash">
50
mkdir /opt/repositories
51
mkfir /opt/repositories/git
52
chown -R apache:apache /opt/repositories/git
53
</code></pre>
54
55 2 Felix Schäfer
h3. Configuration
56
57
Edit the @config.ru@ file and adapt it to your local configuration. @project_root@ must contain the path to the directory containing your git repositories, @git_path@ must obviously contain the path to the git, mine looks like this (on gentoo):
58
59
<pre><code class="ruby">$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/lib')
60 1 Felix Schäfer
61 2 Felix Schäfer
use Rack::ShowExceptions
62 1 Felix Schäfer
63 18 Mr. DTTH
require 'grack'
64 1 Felix Schäfer
65 18 Mr. DTTH
require 'git_adapter'
66
67 2 Felix Schäfer
config = {
68 18 Mr. DTTH
  :project_root => "/opt/repositories/git",
69
  :git_path => '/usr/bin/git',
70 2 Felix Schäfer
  :upload_pack => true,
71
  :receive_pack => true,
72 1 Felix Schäfer
}
73
74
run GitHttp::App.new(config)</code></pre>
75 3 Felix Schäfer
76 1 Felix Schäfer
h3. Integrate with Apache
77 17 Mr. DTTH
78 1 Felix Schäfer
You could obviously use any rack server you like at this point, but the access control mechanism @Redmine.pm@ is written for apache with mod_perl, so you will at least need to reverse proxy your rack server through apache. 
79 17 Mr. DTTH
80 1 Felix Schäfer
My rack server of choice is "passenger":http://modrails.com/ (solid performance, apache module, mostly simple configuration) and it is already configured on my system. 
81 17 Mr. DTTH
82
As passenger installation and configuration is not within the scope of this HowTo, please refer to the "passenger documentation":http://modrails.com/documentation.html or to the passenger installation guide from your distribution.
83
84
There's a little more work to do here to get passenger to work with this, you will need to create the directories @public@ and @tmp@ in the grack directory. 
85
86
Please also be aware that in the standard configuration, passenger will run the grack application with the same user and group owning the @config.ru@ file. This user must have read- and write-access as needed to the git repositories!
87 2 Felix Schäfer
88
The last step is to configure an apache vhost to serve the application:
89
90
<pre><code class="apache"><VirtualHost yo.ur.i.p:80>
91
    ServerName git.myhost.com
92
93
    ServerAdmin root@myhost.com
94
    DocumentRoot "/var/www/git.myhost.com/public"
95
96
    <Directory "/var/www/git.myhost.com/public">
97
        Options None
98
        AllowOverride None
99
        Order allow,deny
100
        Allow from all
101
    </Directory>
102
</VirtualHost></code></pre>
103 1 Felix Schäfer
104 10 Hallison Vasconcelos Batista
At this point, if you have a repository in @/var/git/git.myhost.com/myrepo@, you should be able to access it through @http://git.myhost.com/myrepo@, for example @git ls-remote http://git.myhost.com/myrepo@ should show you some information about the repository.
105
106
h2. Install git-webby
107 3 Felix Schäfer
108
Follow the instructions available in "repository page":http://git.io/BU7twg that use basically the same instructions described above.
109
110
h2. Access control
111
112
You now have a working git server, albeit with no access control. Currently, the shipped perl module for access control @Redmine.pm@ (in @extra/svn/@ in your redmine directory) does not support access control for the git-smart-http protocol, the patch in #4905 aims to implement that.
113
114 11 Gregory Bartholomew
h3. Applying the patch
115 1 Felix Schäfer
116 3 Felix Schäfer
Download the latest (or better: correct) version of the patch from #4905 to your redmine directory. In the redmine directory, apply the patch: @patch -p1 < the-patch-file.patch@ should work (if it tells you stuff about being unable to apply a hunk, the patch is incompatible with your @Redmine.pm@ version, if it says other stuff, try @patch -p0 < the-patch-file.patch@ or @patch Redmine.pm < the-patch-file.patch@, if it still borks, ask for advice on #4905).
117 1 Felix Schäfer
118
-You will possibly still need to edit the file from here, because the current version of the patch only works for repositories served from @http://git.myhost.com/git/myrepo@ though the above example uses @http://git.myhost.com/myrepo@.- This step isn't needed anymore, the patch has been updated to take the information from the @Location@ block from apache into account.
119 8 Felix Schäfer
120 3 Felix Schäfer
h3. Configuring Apache
121 17 Mr. DTTH
122 3 Felix Schäfer
You now have to make Apache aware of your new authentication module (if you already had done this step for subversion integration, you can go to the @Location@ directives directly). 
123 17 Mr. DTTH
124
Copy or link @Redmine.pm@ (from your @extra/svn/@ directory) to @/usr/lib/perl5/Apache/Redmine.pm@ (ubuntu) or wherever your distribution puts its apache perl modules (e.g. gentoo puts them in @/usr/lib64/perl5/vendor_perl/5.8.8/Apache/@, fedora puts them in @/usr/lib64/perl5/vendor_perl/Apache/@).
125 3 Felix Schäfer
126
Having done that, reload apache to make sure everything in the patching phase went well (if not, remove the link or the file create in the step just before and restart apache to get apache back up, try to find the error in your Redmine.pm file). Now edit your vhost configuration to look somewhat like (same as above but with more stuff):
127
128
<pre><code class="apache"><VirtualHost yo.ur.i.p:80>
129
    ServerName git.myhost.com
130
131
    ServerAdmin root@myhost.com
132
    DocumentRoot "/var/www/git.myhost.com/public"
133
134
    PerlLoadModule Apache::Redmine
135
136
    <Directory "/var/www/git.myhost.com/public">
137
        Options None
138
        AllowOverride None
139
        Order allow,deny
140
        Allow from all
141
    </Directory>
142
143
    <Location "/">
144
        AuthType Basic
145
        AuthName "Redmine git repositories"
146
        Require valid-user
147
148
        PerlAccessHandler Apache::Authn::Redmine::access_handler
149
        PerlAuthenHandler Apache::Authn::Redmine::authen_handler
150
151
        ## for mysql
152
        RedmineDSN "DBI:mysql:database=databasename;host=my.db.server"
153
        ## for postgres
154
        # RedmineDSN "DBI:Pg:dbname=databasename;host=my.db.server"
155
        ## for SQLite3
156
        # RedmineDSN "DBI:SQLite:dbname=database.db"
157
158
        RedmineDbUser "redmine"
159
        RedmineDbPass "password"
160 1 Felix Schäfer
        RedmineGitSmartHttp yes
161 3 Felix Schäfer
    </Location>
162 1 Felix Schäfer
</VirtualHost></code></pre>
163
164 3 Felix Schäfer
Reload your apache, and everything should be good and well :-)
165
166
h2. Known issues
167 17 Mr. DTTH
168 1 Felix Schäfer
If you are using the stock git-http-backend directly under apache and you are finding errors like "Request not supported: '/git/your-git-repo'" in your apache error log, you may need to add "SetEnv REMOTE_USER=$REDIRECT_REMOTE_USER" to the to the list of environment variables that you are setting in your apache configuration.  
169 17 Mr. DTTH
170
Unfortionately, this setting may cause redmine to borke.  If so, you will need to set the variable for only the requests that are passed through git-http-backend.  One way to accomplish this is with mod_rewrite.  Below is a sample apache configuration from a Fedora 17 system that uses git-http-backend and mod_rewrite.
171 13 Gregory Bartholomew
172
In httpd.conf:
173
174
<pre><code class="apache">Listen xxx.xxx.xxx.xxx:80
175
<VirtualHost xxx.xxx.xxx.xxx:80>
176
   DocumentRoot /var/www/redmine/public
177
   ServerName servername.domain:80
178
   Include conf/servername.conf
179
</VirtualHost>
180
181
Listen xxx.xxx.xxx.xxx:443
182
<VirtualHost xxx.xxx.xxx.xxx:443>
183
   DocumentRoot /var/www/redmine/public
184
   ServerName servername.domain:443
185
   Include conf/servername.conf
186
   Include conf/ssl.conf
187
</VirtualHost></code></pre>
188
189
In servername.conf:
190
191
<pre><code class="apache">PerlLoadModule Apache::Authn::Redmine
192
193
SetEnv GIT_PROJECT_ROOT /git-1/repositories
194
SetEnv GIT_HTTP_EXPORT_ALL
195
196
<IfModule mod_rewrite.c>
197
   RewriteEngine On
198
199
   RewriteCond %{HTTPS} ^off$
200
   RewriteCond %{REQUEST_URI} !^/git-private/
201
   RewriteRule ^.*$ https://servername.domain$0 [R=301,L]
202
   RewriteRule ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$ /git-1/repositories/$1 [L]
203
   RewriteRule ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /git-1/repositories/$1 [L]
204
   RewriteRule ^/git/(.*)$ /usr/libexec/git-core/git-http-backend/$1 [E=REMOTE_USER:$REDIRECT_REMOTE_USER,H=cgi-script,L]
205
</IfModule>
206
207 15 Gregory Bartholomew
<Directory /usr/libexec/git-core>
208
   <Files "git-http-backend">
209
      Options +ExecCGI
210 13 Gregory Bartholomew
   </Files>
211
</Directory>
212
213
<Location /git>
214
   AuthType Basic
215
   AuthName "CAMPUS"
216
   AuthBasicProvider external
217
   AuthExternal pwauth
218
   Require valid-user
219
220
   PerlAccessHandler Apache::Authn::Redmine::access_handler
221
   PerlAuthenHandler Apache::Authn::Redmine::authen_handler
222
 
223
   RedmineDSN "DBI:mysql:database=redmine;host=localhost" 
224 14 Gregory Bartholomew
   RedmineDbUser "redmine" 
225 13 Gregory Bartholomew
   # RedmineDbPass "password"
226
   RedmineGitSmartHttp yes
227
</Location>
228
229
Alias /git-private /git-1/repositories
230
231
<Location /git-private>
232
   Order deny,allow
233
   Deny from all
234
   <Limit GET PROPFIND OPTIONS REPORT>
235
      Options Indexes FollowSymLinks MultiViews
236
      Allow from 127.0.0.1
237
      Allow from localhost
238
   </Limit>
239
</Location>
240
241
<Directory "/var/www/redmine/public">
242
   RailsEnv production
243
   RailsBaseURI /
244
245
   Options -MultiViews
246
   AllowOverride All
247
</Directory></code></pre>
248
249
In conf/ssl.conf:
250
251
<pre><code class="apache">LogLevel warn
252
SSLEngine on
253
SSLProtocol all -SSLv2
254
SSLCipherSuite RC4-SHA:AES128-SHA:ALL:!ADH:!EXP:!LOW:!MD5:!SSLV2:!NULL
255
SSLCertificateFile /etc/pki/tls/certs/your-server.crt
256
SSLCertificateKeyFile /etc/pki/tls/private/your-server.key
257
SSLCertificateChainFile /etc/pki/tls/certs/server-chain.crt
258
SSLCACertificateFile /etc/pki/tls/certs/ca-bundle.crt
259
260
<Files ~ "\.(cgi|shtml|phtml|php3?)$">
261
    SSLOptions +StdEnvVars
262
</Files>
263
<Directory "/var/www/cgi-bin">
264
    SSLOptions +StdEnvVars
265
</Directory>
266
267
SetEnvIf User-Agent ".*MSIE.*" \
268
         nokeepalive ssl-unclean-shutdown \
269
         downgrade-1.0 force-response-1.0
270
</code></pre>
271
272
In conf.d/ssl.conf:
273
274
<pre><code class="apache">LoadModule ssl_module modules/mod_ssl.so
275 1 Felix Schäfer
SSLPassPhraseDialog exec:/usr/libexec/httpd-ssl-pass-dialog
276
SSLSessionCache         shmcb:/var/cache/mod_ssl/scache(512000)
277
SSLSessionCacheTimeout  300
278 13 Gregory Bartholomew
SSLMutex default
279
SSLRandomSeed startup file:/dev/urandom  256
280
SSLRandomSeed connect builtin
281
SSLCryptoDevice builtin
282
</code></pre>
283 17 Mr. DTTH
284
You will also need to have the perl modules Net::LDAP, Authen::Simple, and Authen::Simple::LDAP installed.  The first two are available in Fedora's default package repositories.  
285
286 13 Gregory Bartholomew
The third must be installed after the other two and it must be obtained directly from cpan.  Below are the commands that I used to install these packages on Fedora 17.
287 15 Gregory Bartholomew
288 13 Gregory Bartholomew
yum -y install gcc make perl-LDAP perl-Authen-Simple
289
cpan
290 1 Felix Schäfer
cpan> install Authen::Simple::LDAP