/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/http_smart_server.txt

  • Committer: mbp at sourcefrog
  • Date: 2006-11-21 01:08:52 UTC
  • mfrom: (2004.1.42 bzr.urllib.keepalive)
  • mto: This revision was merged to the branch mainline in revision 2146.
  • Revision ID: mbp@sourcefrog.net-20061121010852-838b560632acc36c
merge urllib keepalive etc

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/http_smart_server.txt
1
 
Serving Bazaar with Apache
2
 
==========================
3
 
 
4
 
This document describes one way to set up a Bazaar HTTP smart server,
5
 
using Apache 2.0 and FastCGI or mod_python or mod_wsgi.
6
 
 
7
 
For more information on the smart server, and other ways to configure it
8
 
see the main `smart server documentation`_.
9
 
 
10
 
.. _smart server documentation: #running-a-smart-server
 
1
===========================
 
2
Serving Bazaar with FastCGI
 
3
===========================
 
4
 
 
5
**This feature is EXPERIMENTAL and is NOT SECURE.  It will allow access to
 
6
arbitrary files on your server.**
 
7
 
 
8
This document describes one way to setup a Bazaar HTTP smart server, using
 
9
Apache 2.0 and FastCGI.
11
10
 
12
11
Example
13
 
-------
 
12
=======
14
13
 
15
14
You have a webserver already publishing `/srv/example.com/www/code` as
16
15
`http://example.com/code/...` with plain HTTP.  It contains bzr branches and
22
21
Configuring Apache 2.0
23
22
----------------------
24
23
 
25
 
FastCGI
26
 
~~~~~~~
27
 
 
28
24
First, configure mod_fastcgi, e.g. by adding lines like these to your
29
25
httpd.conf::
30
26
 
31
27
    LoadModule fastcgi_module /usr/lib/apache2/modules/mod_fastcgi.so
32
28
    FastCgiIpcDir /var/lib/apache2/fastcgi
33
 
 
 
29
    
34
30
In our example, we're already serving `/srv/example.com/www/code` at
35
31
`http://example.com/code`, so our existing Apache configuration would look
36
32
like::
46
42
 
47
43
    Alias /code /srv/example.com/www/code
48
44
    <Directory /srv/example.com/www/code>
49
 
        Options Indexes FollowSymLinks
 
45
        Options Indexes, FollowSymLinks
50
46
        RewriteEngine On
51
47
        RewriteBase /code
52
 
        RewriteRule ^(.*/|)\.bzr/smart$ /srv/example.com/scripts/bzr-smart.fcgi
 
48
        RewriteRule ^(.*)/\.bzr/smart$ /srv/example.com/scripts/bzr-smart.fcgi
53
49
    </Directory>
54
 
 
 
50
    
55
51
    # bzr-smart.fcgi isn't under the DocumentRoot, so Alias it into the URL
56
52
    # namespace so it can be executed.
57
53
    Alias /srv/example.com/scripts/bzr-smart.fcgi /srv/example.com/scripts/bzr-smart.fcgi
61
57
            SetHandler fastcgi-script
62
58
        </Files>
63
59
    </Directory>
64
 
 
 
60
    
65
61
This instructs Apache to hand requests for any URL ending with `/.bzr/smart`
66
62
inside `/code` to a Bazaar smart server via FastCGI.
67
63
 
71
67
.. _mod_rewrite: http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html
72
68
.. _mod_fastcgi: http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html
73
69
 
74
 
mod_python
75
 
~~~~~~~~~~
76
 
 
77
 
First, configure mod_python, e.g. by adding lines like these to your
78
 
httpd.conf::
79
 
 
80
 
    LoadModule python_module /usr/lib/apache2/modules/mod_python.so
81
 
 
82
 
Define the rewrite rules with mod_rewrite the same way as for FastCGI, except
83
 
change::
84
 
 
85
 
    RewriteRule ^(.*/|)\.bzr/smart$ /srv/example.com/scripts/bzr-smart.fcgi
86
 
 
87
 
to::
88
 
 
89
 
    RewriteRule ^(.*/|)\.bzr/smart$ /srv/example.com/scripts/bzr-smart.py
90
 
 
91
 
Like with mod_fastcgi, we also define how our script is to be handled::
92
 
 
93
 
    Alias /srv/example.com/scripts/bzr-smart.py /srv/example.com/scripts/bzr-smart.py
94
 
    <Directory /srv/example.com/scripts>
95
 
        <Files bzr-smart.py>
96
 
            PythonPath "sys.path+['/srv/example.com/scripts']"
97
 
            AddHandler python-program .py
98
 
            PythonHandler bzr-smart::handler
99
 
        </Files>
100
 
    </Directory>
101
 
 
102
 
This instructs Apache to hand requests for any URL ending with `/.bzr/smart`
103
 
inside `/code` to a Bazaar smart server via mod_python.
104
 
 
105
 
NOTE: If you don't have bzrlib in your PATH, you will be need to change the
106
 
following line::
107
 
 
108
 
            PythonPath "sys.path+['/srv/example.com/scripts']"
109
 
 
110
 
To::
111
 
 
112
 
            PythonPath "['/path/to/bzr']+sys.path+['/srv/example.com/scripts']"
113
 
 
114
 
 
115
 
Refer to the mod_python_ documentation for further information.
116
 
 
117
 
.. _mod_python: http://www.modpython.org/
118
 
 
119
 
 
120
 
mod_wsgi
121
 
~~~~~~~~
122
 
 
123
 
First, configure mod_wsgi, e.g. enabling the mod with a2enmod wsgi.
124
 
We need to change it to handle all requests for URLs ending in `.bzr/smart`.  It
125
 
will look like::
126
 
 
127
 
    WSGIScriptAliasMatch ^/code/.*/\.bzr/smart$ /srv/example.com/scripts/bzr.wsgi
128
 
 
129
 
    #The three next lines allow regular GETs to work too
130
 
    RewriteEngine On
131
 
    RewriteCond %{REQUEST_URI} !^/code/.*/\.bzr/smart$
132
 
    RewriteRule ^/code/(.*/\.bzr/.*)$ /srv/example.com/www/code/$1 [L]
133
 
 
134
 
    <Directory /srv/example.com/www/code>
135
 
        WSGIApplicationGroup %{GLOBAL}
136
 
    </Directory>
137
 
 
138
 
This instructs Apache to hand requests for any URL ending with `/.bzr/smart`
139
 
inside `/code` to a Bazaar smart server via WSGI, and any other URL inside
140
 
`/code` to be served directly by Apache.
141
 
 
142
 
Refer to the mod_wsgi_ documentation for further information.
143
 
 
144
 
.. _mod_wsgi: http://code.google.com/p/modwsgi/
145
 
 
146
70
Configuring Bazaar
147
71
------------------
148
72
 
149
 
FastCGI
150
 
~~~~~~~
151
 
 
152
73
We've configured Apache to run the smart server at
153
74
`/srv/example.com/scripts/bzr-smart.fcgi`.  This is just a simple script we need
154
75
to write to configure a smart server, and glue it to the FastCGI gateway.
158
79
    from bzrlib.transport.http import wsgi
159
80
 
160
81
    smart_server_app = wsgi.make_app(
161
 
        root='/srv/example.com/www/code',
 
82
        root='/srv/example.com/code',
162
83
        prefix='/code/',
163
 
        path_var='REQUEST_URI',
164
 
        readonly=True,
165
 
        load_plugins=True,
166
 
        enable_logging=True)
 
84
        path_var='REQUEST_URI')
167
85
 
168
86
    fcgi.WSGIServer(smart_server_app).run()
169
 
 
 
87
        
170
88
The `fcgi` module can be found at http://svn.saddi.com/py-lib/trunk/fcgi.py.  It
171
89
is part of flup_.
172
90
 
173
91
.. _flup: http://www.saddi.com/software/flup/
174
92
 
175
 
mod_python
176
 
~~~~~~~~~~
177
 
 
178
 
We've configured Apache to run the smart server at
179
 
`/srv/example.com/scripts/bzr-smart.py`.  This is just a simple script we need
180
 
to write to configure a smart server, and glue it to the mod_python gateway.
181
 
Here's what it looks like::
182
 
 
183
 
    import modpywsgi
184
 
    from bzrlib.transport.http import wsgi
185
 
 
186
 
    smart_server_app = wsgi.make_app(
187
 
        root='/srv/example.com/www/code',
188
 
        prefix='/code/',
189
 
        path_var='REQUEST_URI',
190
 
        readonly=True,
191
 
        load_plugins=True,
192
 
        enable_logging=True)
193
 
 
194
 
    def handler(request):
195
 
        """Handle a single request."""
196
 
        wsgi_server = modpywsgi.WSGIServer(smart_server_app)
197
 
        return wsgi_server.run(request)
198
 
 
199
 
The `modpywsgi` module can be found at
200
 
http://ice.usq.edu.au/svn/ice/trunk/apps/ice-server/modpywsgi.py. It was
201
 
part of pocoo_. You sould make sure you place modpywsgi.py in the same
202
 
directory as bzr-smart.py (ie. /srv/example.com/scripts/).
203
 
 
204
 
.. _pocoo: http://dev.pocoo.org/projects/pocoo/
205
 
 
206
 
 
207
 
mod_wsgi
208
 
~~~~~~~~
209
 
 
210
 
We've configured Apache to run the smart server at
211
 
`/srv/example.com/scripts/bzr.wsgi`.  This is just a simple script we need
212
 
to write to configure a smart server, and glue it to the WSGI gateway.
213
 
Here's what it looks like::
214
 
 
215
 
    from bzrlib.transport.http import wsgi
216
 
 
217
 
    def application(environ, start_response):
218
 
        app = wsgi.make_app(
219
 
            root="/srv/example.com/www/code/",
220
 
            prefix="/code",
221
 
            readonly=True,
222
 
            enable_logging=False)
223
 
        return app(environ, start_response)
224
 
 
225
93
Clients
226
94
-------
227
95
 
228
 
Now you can use `bzr+http://` URLs or just `http://` URLs, e.g.::
 
96
Now you can use `bzr+http://` URLs, e.g.::
229
97
 
230
98
    bzr log bzr+http://example.com/code/my-branch
231
99
 
233
101
 
234
102
    bzr log http://example.com/code/my-branch
235
103
 
 
104
 
236
105
Advanced configuration
237
 
----------------------
 
106
======================
238
107
 
239
108
Because the Bazaar HTTP smart server is a WSGI application, it can be used with
240
109
any 3rd-party WSGI middleware or server that conforms the WSGI standard.  The
259
128
 
260
129
.. _WSGI standard: http://www.python.org/dev/peps/pep-0333/
261
130
 
262
 
 
263
 
Pushing over the http smart server
264
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
265
 
 
266
 
It is possible to allow pushing data over the http smart server. The
267
 
easiest way to do this, is to just supply ``readonly=False`` to the
268
 
``wsgi.make_app()`` call. But be careful, because the smart protocol does
269
 
not contain any Authentication. So if you enable write support, you will
270
 
want to restrict access to ``.bzr/smart`` URLs to restrict who can
271
 
actually write data on your system, e.g. in apache it looks like::
272
 
 
273
 
    <Location /code>
274
 
        AuthType Basic
275
 
        AuthName "example"
276
 
        AuthUserFile /srv/example.com/conf/auth.passwd
277
 
        <LimitExcept GET>
278
 
            Require valid-user
279
 
        </LimitExcept>
280
 
    </Location>
281
 
 
282
 
At this time, it is not possible to allow some people to have read-only
283
 
access and others to have read-write access to the same urls. Because at
284
 
the HTTP layer (which is doing the Authenticating), everything is just a
285
 
POST request.  However, it would certainly be possible to have HTTPS
286
 
require authentication and use a writable server, and plain HTTP allow
287
 
read-only access.
288
 
 
289
 
If bzr gives an error like this when accessing your HTTPS site::
290
 
 
291
 
  bzr: ERROR: Connection error: curl connection error (server certificate verification failed.
292
 
  CAfile:/etc/ssl/certs/ca-certificates.crt CRLfile: none)
293
 
 
294
 
You can workaround it by using ``https+urllib`` rather than ``http`` in your
295
 
URL, or by uninstalling pycurl.  See `bug 82086`_ for more details.
296
 
 
297
 
.. _bug 82086: https://bugs.launchpad.net/bzr/+bug/82086
298
 
 
299
 
..
300
 
   vim: ft=rst tw=74 et