1
Serving Bazaar with FastCGI
2
===========================
4
This document describes one way to set up a Bazaar HTTP smart server,
5
using Apache 2.0 and FastCGI or mod_python.
7
For more information on the smart server, and other ways to configure it
8
see the main `smart server documentation`_.
10
.. _smart server documentation: #running-a-smart-server
15
You have a webserver already publishing `/srv/example.com/www/code` as
16
`http://example.com/code/...` with plain HTTP. It contains bzr branches and
17
directories like `/srv/example.com/www/code/branch-one` and
18
`/srv/example.com/www/code/my-repo/branch-two`. You want to provide read-only
19
smart server access to these directories in addition to the existing HTTP
22
Configuring Apache 2.0
23
----------------------
28
First, configure mod_fastcgi, e.g. by adding lines like these to your
31
LoadModule fastcgi_module /usr/lib/apache2/modules/mod_fastcgi.so
32
FastCgiIpcDir /var/lib/apache2/fastcgi
34
In our example, we're already serving `/srv/example.com/www/code` at
35
`http://example.com/code`, so our existing Apache configuration would look
38
Alias /code /srv/example.com/www/code
39
<Directory /srv/example.com/www/code>
44
We need to change it to handle all requests for URLs ending in `.bzr/smart`. It
47
Alias /code /srv/example.com/www/code
48
<Directory /srv/example.com/www/code>
49
Options Indexes FollowSymLinks
52
RewriteRule ^(.*/|)\.bzr/smart$ /srv/example.com/scripts/bzr-smart.fcgi
55
# bzr-smart.fcgi isn't under the DocumentRoot, so Alias it into the URL
56
# namespace so it can be executed.
57
Alias /srv/example.com/scripts/bzr-smart.fcgi /srv/example.com/scripts/bzr-smart.fcgi
58
<Directory /srv/example.com/scripts>
60
<Files bzr-smart.fcgi>
61
SetHandler fastcgi-script
65
This instructs Apache to hand requests for any URL ending with `/.bzr/smart`
66
inside `/code` to a Bazaar smart server via FastCGI.
68
Refer to the mod_rewrite_ and mod_fastcgi_ documentation for further
71
.. _mod_rewrite: http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html
72
.. _mod_fastcgi: http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html
77
First, configure mod_python, e.g. by adding lines like these to your
80
LoadModule python_module /usr/lib/apache2/modules/mod_python.so
82
Define the rewrite rules with mod_rewrite the same way as for FastCGI, except
85
RewriteRule ^(.*/|)\.bzr/smart$ /srv/example.com/scripts/bzr-smart.fcgi
89
RewriteRule ^(.*/|)\.bzr/smart$ /srv/example.com/scripts/bzr-smart.py
91
Like with mod_fastcgi, we also define how our script is to be handled::
93
Alias /srv/example.com/scripts/bzr-smart.py /srv/example.com/scripts/bzr-smart.py
94
<Directory /srv/example.com/scripts>
96
PythonPath "sys.path+['/srv/example.com/scripts']"
97
AddHandler python-program .py
98
PythonHandler bzr-smart::handler
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.
105
NOTE: If you don't have bzrlib in your PATH, you will be need to change the
108
PythonPath "sys.path+['/srv/example.com/scripts']"
112
PythonPath "['/path/to/bzr']+sys.path+['/srv/example.com/scripts']"
115
Refer to the mod_python_ documentation for further information.
117
.. _mod_python: http://www.modpython.org/
126
We've configured Apache to run the smart server at
127
`/srv/example.com/scripts/bzr-smart.fcgi`. This is just a simple script we need
128
to write to configure a smart server, and glue it to the FastCGI gateway.
129
Here's what it looks like::
132
from bzrlib.transport.http import wsgi
134
smart_server_app = wsgi.make_app(
135
root='/srv/example.com/www/code',
137
path_var='REQUEST_URI',
142
fcgi.WSGIServer(smart_server_app).run()
144
The `fcgi` module can be found at http://svn.saddi.com/py-lib/trunk/fcgi.py. It
147
.. _flup: http://www.saddi.com/software/flup/
152
We've configured Apache to run the smart server at
153
`/srv/example.com/scripts/bzr-smart.py`. This is just a simple script we need
154
to write to configure a smart server, and glue it to the mod_python gateway.
155
Here's what it looks like::
158
from bzrlib.transport.http import wsgi
160
smart_server_app = wsgi.make_app(
161
root='/srv/example.com/www/code',
163
path_var='REQUEST_URI',
168
def handler(request):
169
"""Handle a single request."""
170
wsgi_server = modpywsgi.WSGIServer(smart_server_app)
171
return wsgi_server.run(request)
173
The `modpywsgi` module can be found at
174
http://dev.pocoo.org/projects/pocoo/browser/pocoo/wrappers/modpy.py. It is
175
part of pocoo_. You sould make sure you place modpywsgi.py in the same
176
directory as bzr-smart.py (ie. /srv/example.com/scripts/).
178
.. _pocoo: http://dev.pocoo.org/projects/pocoo/
183
Now you can use `bzr+http://` URLs, e.g.::
185
bzr log bzr+http://example.com/code/my-branch
187
Plain HTTP access should continue to work::
189
bzr log http://example.com/code/my-branch
192
Advanced configuration
193
----------------------
195
Because the Bazaar HTTP smart server is a WSGI application, it can be used with
196
any 3rd-party WSGI middleware or server that conforms the WSGI standard. The
197
only requirements are:
199
* to construct a `SmartWSGIApp`, you need to specify a **root transport** that it
201
* each request's `environ` dict must have a **'bzrlib.relpath'** variable set.
203
The `make_app` helper used in the example constructs a `SmartWSGIApp` with a
204
transport based on the `root` path given to it, and calculates the
205
'bzrlib.relpath` for each request based on the `prefix` and `path_var`
206
arguments. In the example above, it will take the 'REQUEST_URI' (which is set
207
by Apache), strip the '/code/' prefix and the '/.bzr/smart' suffix, and set that
208
as the 'bzrlib.relpath', so that a request for '/code/foo/bar/.bzr/smart' will
209
result in a 'bzrlib.relpath' of 'foo/bzr'.
211
It's possible to configure a smart server for a non-local transport, or that
212
does arbitrary path translations, etc, by constructing a `SmartWSGIApp`
213
directly. Refer to the docstrings of `bzrlib.transport.http.wsgi` and the `WSGI
214
standard`_ for further information.
216
.. _WSGI standard: http://www.python.org/dev/peps/pep-0333/
219
Pushing over ``bzr+http://``
220
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
222
It is possible to allow pushing data over the http smart server. The
223
easiest way to do this, is to just supply ``readonly=False`` to the
224
``wsgi.make_app()`` call. But be careful, because the smart protocol does
225
not contain any Authentication. So if you enable write support, you will
226
want to restrict access to ``.bzr/smart`` URLs to restrict who can
227
actually write data on your system. At this time, it is not possible to
228
allow some people to have read-only access and others to have read-write
229
access to the same urls. Because at the HTTP layer (which is doing the
230
Authenticating), everything is just a POST request. However, it would
231
certainly be possible to have HTTPS require authentication and use a
232
writable server, and plain HTTP allow read-only access.
added
removed
doc/en/user-guide/http_smart_server.txt
