← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/http_smart_server.txt

Add WSGI smart server.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/http_smart_server.txt
 
1
===========================
 
2
Serving Bazaar with FastCGI
 
3
===========================
 
4
 
 
5
This document describes one way to setup a Bazaar HTTP smart server, using
 
6
Apache 2.0 and FastCGI.
 
7
 
 
8
Example
 
9
=======
 
10
 
 
11
You have a webserver already publishing `/srv/example.com/www/code` as
 
12
`http://example.com/code/...` with plain HTTP.  It contains bzr branches and
 
13
directories like `/srv/example.com/www/code/branch-one` and
 
14
`/srv/example.com/www/code/my-repo/branch-two`.  You want to provide read-only smart
 
15
server access to these directories in addition to the existing HTTP access.
 
16
 
 
17
Configuring Apache 2.0
 
18
----------------------
 
19
 
 
20
First, configure mod_fastcgi, e.g. by adding lines like these to your
 
21
httpd.conf::
 
22
 
 
23
    LoadModule fastcgi_module /usr/lib/apache2/modules/mod_fastcgi.so
 
24
    FastCgiIpcDir /var/lib/apache2/fastcgi
 
25
    
 
26
In our example, we're already serving `/srv/example.com/www/code` at
 
27
`http://example.com/code`, so our existing Apache configuration would look
 
28
like::
 
29
 
 
30
    Alias /code /srv/example.com/www/code
 
31
    <Directory /srv/example.com/www/code>
 
32
        Options Indexes
 
33
        # ...
 
34
    </Directory>
 
35
 
 
36
We need to change it to handle all requests for URLs ending in `.bzr/smart`.  It
 
37
will look like::
 
38
 
 
39
    Alias /code /srv/example.com/www/code
 
40
    <Directory /srv/example.com/www/code>
 
41
        Options Indexes, FollowSymLinks
 
42
        RewriteEngine On
 
43
        RewriteBase /code
 
44
        RewriteRule ^(.*)/\.bzr/smart$ /srv/example.com/scripts/bzr-smart.fcgi
 
45
    </Directory>
 
46
    
 
47
    Alias /srv/example.com/scripts/bzr-smart.fcgi /srv/example.com/scripts/bzr-smart.fcgi
 
48
    <Directory /srv/example.com/scripts>
 
49
        Options ExecCGI
 
50
        <Files bzr-smart.fcgi>
 
51
            SetHandler fastcgi-script
 
52
        </Files>
 
53
    </Directory>
 
54
    
 
55
This instructs Apache to hand requests for any URL ending with `/.bzr/smart`
 
56
inside `/code` to a Bazaar smart server via FastCGI.
 
57
 
 
58
Refer to the mod_rewrite_ and mod_fastcgi_ documentation for further
 
59
information.
 
60
 
 
61
.. _mod_rewrite: http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html
 
62
.. _mod_fastcgi: http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html
 
63
 
 
64
Configuring Bazaar
 
65
------------------
 
66
 
 
67
We've configured Apache to run the smart server at
 
68
`/srv/example.com/scripts/bzr-smart.fcgi`.  This is just a simple script we need
 
69
to write to configure a smart server, and glue it to the FastCGI gateway.
 
70
Here's what it looks like::
 
71
 
 
72
    import fcgi
 
73
    from bzrlib.transport.http import wsgi
 
74
 
 
75
    smart_server_app = wsgi.make_app(
 
76
        root='/srv/example.com/code',
 
77
        prefix='/code/',
 
78
        path_var='REQUEST_URI')
 
79
 
 
80
    fcgi.WSGIServer(smart_server_app).run()
 
81
        
 
82
The `fcgi` module can be found at http://svn.saddi.com/py-lib/trunk/fcgi.py.  It
 
83
is part of flup_.
 
84
 
 
85
.. _flup: http://www.saddi.com/software/flup/
 
86
 
 
87
Clients
 
88
-------
 
89
 
 
90
Now you can use `bzr+http://` URLs, e.g.::
 
91
 
 
92
    bzr log bzr+http://example.com/code/my-branch
 
93
 
 
94
Plain HTTP access should continue to work::
 
95
 
 
96
    bzr log http://example.com/code/my-branch
 
97
 
 
98
 
 
99
Advanced configuration
 
100
======================
 
101
 
 
102
Because the Bazaar HTTP smart server is a WSGI application, it can be used with
 
103
any 3rd-party WSGI middleware or server that conforms the WSGI standard.  The
 
104
only requirements are:
 
105
 
 
106
  * to construct a `SmartWSGIApp`, you need to specify a **root transport** that it
 
107
    will serve.
 
108
  * each request's `environ` dict must have a **'bzrlib.relpath'** variable set.
 
109
 
 
110
The `make_app` helper used in the example constructs a `SmartWSGIApp` with a
 
111
transport based on the `root` path given to it, and calculates the
 
112
'bzrlib.relpath` for each request based on the `prefix` and `path_var`
 
113
arguments.  In the example above, it will take the 'REQUEST_URI' (which is set
 
114
by Apache), strip the '/code/' prefix and the '/.bzr/smart' suffix, and set that
 
115
as the 'bzrlib.relpath', so that a request for '/code/foo/bar/.bzr/smart' will
 
116
result in a 'bzrlib.relpath' of 'foo/bzr'.
 
117
 
 
118
It's possible to configure a smart server for a non-local transport, or that
 
119
does arbitrary path translations, etc, by constructing a `SmartWSGIApp`
 
120
directly.  Refer to the docstrings of `bzrlib.transport.http.wsgi` and the `WSGI
 
121
standard`_ for further information.
 
122
 
 
123
.. _WSGI standard: http://www.python.org/dev/peps/pep-0333/
 
124