Project

General

Profile

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

Gregory Bartholomew, 2012-09-20 17:18

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
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. 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.
8
9 7 Felix Schäfer
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. This is a wiki page, feel free to correct or amend anything you find lacking :-) You can also "drop me a line":/users/3866.
10
11
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.
12 1 Felix Schäfer
13
h2. Prerequisites
14
15
* Apache with mod_perl (access control)
16
* git (version at least 1.6.6)
17
* A way to serve git-smart-http
18
** 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
19 10 Hallison Vasconcelos Batista
** a rack server if you want to use "grack":http://github.com/schacon/grack (basically a rack wrapper around the right git commands) or
20
"git-webby":http://git.io/BU7twg (another implementation based on grack but written in Sinatra).
21 1 Felix Schäfer
22 6 Felix Schäfer
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. 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).
23 2 Felix Schäfer
24
h2. Install grack
25 1 Felix Schäfer
26 3 Felix Schäfer
h3. Get the sources
27 2 Felix Schäfer
28
Fetch grack from its "github repository":http://github.com/schacon/grack, I checked out mine to @/var/www/git.myhost.com@:
29
30 5 Holger Just
<pre><code class="bash">git clone http://github.com/schacon/grack.git /var/www/git.myhost.com</code></pre>
31 1 Felix Schäfer
32 3 Felix Schäfer
h3. Configuration
33
34 2 Felix Schäfer
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):
35
36
<pre><code class="ruby">$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/lib')
37
38
use Rack::ShowExceptions
39
40
require 'lib/git_http'
41
42
config = {
43
  :project_root => "/var/git/git.myhost.com",
44
  :git_path => '/usr/libexec/git-core/git',
45
  :upload_pack => true,
46
  :receive_pack => true,
47
}
48
49
run GitHttp::App.new(config)</code></pre>
50 1 Felix Schäfer
51 3 Felix Schäfer
h3. Integrate with Apache
52
53
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. 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. 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.
54
55 2 Felix Schäfer
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. 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!
56
57
The last step is to configure an apache vhost to serve the application:
58
59
<pre><code class="apache"><VirtualHost yo.ur.i.p:80>
60
    ServerName git.myhost.com
61
62
    ServerAdmin root@myhost.com
63
    DocumentRoot "/var/www/git.myhost.com/public"
64
65
    <Directory "/var/www/git.myhost.com/public">
66
        Options None
67
        AllowOverride None
68
        Order allow,deny
69
        Allow from all
70
    </Directory>
71
</VirtualHost></code></pre>
72
73 1 Felix Schäfer
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.
74 10 Hallison Vasconcelos Batista
75
h2. Install git-webby
76
77
Follow the instructions available in "repository page":http://git.io/BU7twg that use basically the same instructions described above.
78 3 Felix Schäfer
79
h2. Access control
80
81
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.
82
83
h3. Applying the patch
84
85 11 Gregory Bartholomew
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).
86 3 Felix Schäfer
87 8 Felix Schäfer
-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.
88 3 Felix Schäfer
89
h3. Configuring Apache
90
91 9 Loren Sands-Ramshaw
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). 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/@).
92 3 Felix Schäfer
93
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):
94
95
<pre><code class="apache"><VirtualHost yo.ur.i.p:80>
96
    ServerName git.myhost.com
97
98
    ServerAdmin root@myhost.com
99
    DocumentRoot "/var/www/git.myhost.com/public"
100
101
    PerlLoadModule Apache::Redmine
102
103
    <Directory "/var/www/git.myhost.com/public">
104
        Options None
105
        AllowOverride None
106
        Order allow,deny
107
        Allow from all
108
    </Directory>
109
110
    <Location "/">
111
        AuthType Basic
112
        AuthName "Redmine git repositories"
113
        Require valid-user
114
115
        PerlAccessHandler Apache::Authn::Redmine::access_handler
116
        PerlAuthenHandler Apache::Authn::Redmine::authen_handler
117
118
        ## for mysql
119
        RedmineDSN "DBI:mysql:database=databasename;host=my.db.server"
120
        ## for postgres
121
        # RedmineDSN "DBI:Pg:dbname=databasename;host=my.db.server"
122
        ## for SQLite3
123
        # RedmineDSN "DBI:SQLite:dbname=database.db"
124
125
        RedmineDbUser "redmine"
126
        RedmineDbPass "password"
127
        RedmineGitSmartHttp yes
128
    </Location>
129
</VirtualHost></code></pre>
130
131
Reload your apache, and everything should be good and well :-)
132
133
h2. Known issues
134 1 Felix Schäfer
135 13 Gregory Bartholomew
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.  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.
136
137
In httpd.conf:
138
139
<pre><code class="apache">Listen xxx.xxx.xxx.xxx:80
140
<VirtualHost xxx.xxx.xxx.xxx:80>
141
   DocumentRoot /var/www/redmine/public
142
   ServerName servername.domain:80
143
   Include conf/servername.conf
144
</VirtualHost>
145
146
Listen xxx.xxx.xxx.xxx:443
147
<VirtualHost xxx.xxx.xxx.xxx:443>
148
   DocumentRoot /var/www/redmine/public
149
   ServerName servername.domain:443
150
   Include conf/servername.conf
151
   Include conf/ssl.conf
152
</VirtualHost></code></pre>
153
154
In servername.conf:
155
156
<pre><code class="apache">PerlLoadModule Apache::Authn::Redmine
157
158
SetEnv GIT_PROJECT_ROOT /git-1/repositories
159
SetEnv GIT_HTTP_EXPORT_ALL
160
161
<IfModule mod_rewrite.c>
162
   RewriteEngine On
163
164
   RewriteCond %{HTTPS} ^off$
165
   RewriteCond %{REQUEST_URI} !^/git-private/
166
   RewriteRule ^.*$ https://servername.domain$0 [R=301,L]
167
   RewriteRule ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$ /git-1/repositories/$1 [L]
168
   RewriteRule ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /git-1/repositories/$1 [L]
169
   RewriteRule ^/git/(.*)$ /usr/libexec/git-core/git-http-backend/$1 [E=REMOTE_USER:$REDIRECT_REMOTE_USER,H=cgi-script,L]
170
</IfModule>
171
172
<Directory /usr/libexec/git-core>
173 15 Gregory Bartholomew
   <Files "git-http-backend">
174
      Options +ExecCGI
175
   </Files>
176 13 Gregory Bartholomew
</Directory>
177
178
<Location /git>
179
   AuthType Basic
180
   AuthName "CAMPUS"
181
   AuthBasicProvider external
182
   AuthExternal pwauth
183
   Require valid-user
184
185
   PerlAccessHandler Apache::Authn::Redmine::access_handler
186
   PerlAuthenHandler Apache::Authn::Redmine::authen_handler
187
 
188
   RedmineDSN "DBI:mysql:database=redmine;host=localhost" 
189
   RedmineDbUser "redmine" 
190 14 Gregory Bartholomew
   # RedmineDbPass "password"
191 13 Gregory Bartholomew
   RedmineGitSmartHttp yes
192
</Location>
193
194
Alias /git-private /git-1/repositories
195
196
<Location /git-private>
197
   Order deny,allow
198
   Deny from all
199
   <Limit GET PROPFIND OPTIONS REPORT>
200
      Options Indexes FollowSymLinks MultiViews
201
      Allow from 127.0.0.1
202
      Allow from localhost
203
   </Limit>
204
</Location>
205
206
<Directory "/var/www/redmine/public">
207
   RailsEnv production
208
   RailsBaseURI /
209
210
   Options -MultiViews
211
   AllowOverride All
212
</Directory></code></pre>
213
214
In conf/ssl.conf:
215
216
<pre><code class="apache">LogLevel warn
217
SSLEngine on
218
SSLProtocol all -SSLv2
219
SSLCipherSuite RC4-SHA:AES128-SHA:ALL:!ADH:!EXP:!LOW:!MD5:!SSLV2:!NULL
220
SSLCertificateFile /etc/pki/tls/certs/your-server.crt
221
SSLCertificateKeyFile /etc/pki/tls/private/your-server.key
222
SSLCertificateChainFile /etc/pki/tls/certs/server-chain.crt
223
SSLCACertificateFile /etc/pki/tls/certs/ca-bundle.crt
224
225
<Files ~ "\.(cgi|shtml|phtml|php3?)$">
226
    SSLOptions +StdEnvVars
227
</Files>
228
<Directory "/var/www/cgi-bin">
229
    SSLOptions +StdEnvVars
230
</Directory>
231
232
SetEnvIf User-Agent ".*MSIE.*" \
233
         nokeepalive ssl-unclean-shutdown \
234
         downgrade-1.0 force-response-1.0
235
</code></pre>
236
237
In conf.d/ssl.conf:
238
239
<pre><code class="apache">LoadModule ssl_module modules/mod_ssl.so
240
SSLPassPhraseDialog exec:/usr/libexec/httpd-ssl-pass-dialog
241
SSLSessionCache         shmcb:/var/cache/mod_ssl/scache(512000)
242
SSLSessionCacheTimeout  300
243
SSLMutex default
244
SSLRandomSeed startup file:/dev/urandom  256
245
SSLRandomSeed connect builtin
246
SSLCryptoDevice builtin
247
</code></pre>
248 1 Felix Schäfer
249 13 Gregory Bartholomew
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.  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.
250
251 15 Gregory Bartholomew
yum -y install gcc make perl-LDAP perl-Authen-Simple
252 13 Gregory Bartholomew
cpan
253
cpan> install Authen::Simple::LDAP