← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/http_smart_server.txt

  • Committer: abentley
  • Date: 2005-10-14 03:50:50 UTC
  • mto: (1185.25.1)
  • mto: This revision was merged to the branch mainline in revision 1460.
  • Revision ID: abentley@lappy-20051014035050-d779472ccb599a51
semi-broke merge

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 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 set up a Bazaar HTTP smart server,
9
 
using Apache 2.0 and FastCGI or mod_python.
10
 
 
11
 
For more information on the smart server, and other ways to configure it
12
 
see the main `smart server documentation`_.
13
 
 
14
 
.. _smart server documentation: server.htm
15
 
 
16
 
Example
17
 
=======
18
 
 
19
 
You have a webserver already publishing `/srv/example.com/www/code` as
20
 
`http://example.com/code/...` with plain HTTP.  It contains bzr branches and
21
 
directories like `/srv/example.com/www/code/branch-one` and
22
 
`/srv/example.com/www/code/my-repo/branch-two`.  You want to provide read-only
23
 
smart server access to these directories in addition to the existing HTTP
24
 
access.
25
 
 
26
 
Configuring Apache 2.0
27
 
----------------------
28
 
 
29
 
FastCGI
30
 
~~~~~~~
31
 
 
32
 
First, configure mod_fastcgi, e.g. by adding lines like these to your
33
 
httpd.conf::
34
 
 
35
 
    LoadModule fastcgi_module /usr/lib/apache2/modules/mod_fastcgi.so
36
 
    FastCgiIpcDir /var/lib/apache2/fastcgi
37
 
    
38
 
In our example, we're already serving `/srv/example.com/www/code` at
39
 
`http://example.com/code`, so our existing Apache configuration would look
40
 
like::
41
 
 
42
 
    Alias /code /srv/example.com/www/code
43
 
    <Directory /srv/example.com/www/code>
44
 
        Options Indexes
45
 
        # ...
46
 
    </Directory>
47
 
 
48
 
We need to change it to handle all requests for URLs ending in `.bzr/smart`.  It
49
 
will look like::
50
 
 
51
 
    Alias /code /srv/example.com/www/code
52
 
    <Directory /srv/example.com/www/code>
53
 
        Options Indexes, FollowSymLinks
54
 
        RewriteEngine On
55
 
        RewriteBase /code
56
 
        RewriteRule ^(.*/|)\.bzr/smart$ /srv/example.com/scripts/bzr-smart.fcgi
57
 
    </Directory>
58
 
    
59
 
    # bzr-smart.fcgi isn't under the DocumentRoot, so Alias it into the URL
60
 
    # namespace so it can be executed.
61
 
    Alias /srv/example.com/scripts/bzr-smart.fcgi /srv/example.com/scripts/bzr-smart.fcgi
62
 
    <Directory /srv/example.com/scripts>
63
 
        Options ExecCGI
64
 
        <Files bzr-smart.fcgi>
65
 
            SetHandler fastcgi-script
66
 
        </Files>
67
 
    </Directory>
68
 
    
69
 
This instructs Apache to hand requests for any URL ending with `/.bzr/smart`
70
 
inside `/code` to a Bazaar smart server via FastCGI.
71
 
 
72
 
Refer to the mod_rewrite_ and mod_fastcgi_ documentation for further
73
 
information.
74
 
 
75
 
.. _mod_rewrite: http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html
76
 
.. _mod_fastcgi: http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html
77
 
 
78
 
mod_python
79
 
~~~~~~~~~~
80
 
 
81
 
First, configure mod_python, e.g. by adding lines like these to your
82
 
httpd.conf::
83
 
 
84
 
    LoadModule python_module /usr/lib/apache2/modules/mod_python.so
85
 
 
86
 
Define the rewrite rules with mod_rewrite the same way as for FastCGI, except
87
 
change::
88
 
 
89
 
    RewriteRule ^(.*/|)\.bzr/smart$ /srv/example.com/scripts/bzr-smart.fcgi
90
 
 
91
 
to::
92
 
 
93
 
    RewriteRule ^(.*/|)\.bzr/smart$ /srv/example.com/scripts/bzr-smart.py
94
 
 
95
 
Like with mod_fastcgi, we also define how our script is to be handled::
96
 
 
97
 
    Alias /srv/example.com/scripts/bzr-smart.py /srv/example.com/scripts/bzr-smart.py
98
 
    <Directory /srv/example.com/scripts>
99
 
        <Files bzr-smart.py>
100
 
            PythonPath "sys.path+['/srv/example.com/scripts']"
101
 
            AddHandler python-program .py
102
 
            PythonHandler bzr-smart::handler
103
 
        </Files>
104
 
    </Directory>
105
 
 
106
 
This instructs Apache to hand requests for any URL ending with `/.bzr/smart`
107
 
inside `/code` to a Bazaar smart server via mod_python.
108
 
 
109
 
Refer to the mod_python_ documentation for further information.
110
 
 
111
 
.. _mod_python: http://www.modpython.org/
112
 
 
113
 
 
114
 
Configuring Bazaar
115
 
------------------
116
 
 
117
 
FastCGI
118
 
~~~~~~~
119
 
 
120
 
We've configured Apache to run the smart server at
121
 
`/srv/example.com/scripts/bzr-smart.fcgi`.  This is just a simple script we need
122
 
to write to configure a smart server, and glue it to the FastCGI gateway.
123
 
Here's what it looks like::
124
 
 
125
 
    import fcgi
126
 
    from bzrlib.transport.http import wsgi
127
 
 
128
 
    smart_server_app = wsgi.make_app(
129
 
        root='/srv/example.com/code',
130
 
        prefix='/code/',
131
 
        path_var='REQUEST_URI',
132
 
        readonly=True)
133
 
 
134
 
    fcgi.WSGIServer(smart_server_app).run()
135
 
        
136
 
The `fcgi` module can be found at http://svn.saddi.com/py-lib/trunk/fcgi.py.  It
137
 
is part of flup_.
138
 
 
139
 
.. _flup: http://www.saddi.com/software/flup/
140
 
 
141
 
mod_python
142
 
~~~~~~~~~~
143
 
 
144
 
We've configured Apache to run the smart server at
145
 
`/srv/example.com/scripts/bzr-smart.py`.  This is just a simple script we need
146
 
to write to configure a smart server, and glue it to the mod_python gateway.
147
 
Here's what it looks like::
148
 
 
149
 
    import modpywsgi
150
 
    from bzrlib.transport.http import wsgi
151
 
 
152
 
    smart_server_app = wsgi.make_app(
153
 
        root='/srv/example.com/code',
154
 
        prefix='/code/',
155
 
        path_var='REQUEST_URI',
156
 
        readonly=True)
157
 
 
158
 
    def handler(request):
159
 
        """Handle a single request."""
160
 
        wsgi_server = modpywsgi.WSGIServer(smart_server_app)
161
 
        return wsgi_server.run(request)
162
 
        
163
 
The `modpywsgi` module can be found at http://trac.pocoo.org/wiki/ModPyWsgi.  It
164
 
is part of pocoo_.
165
 
 
166
 
.. _pocoo: http://trac.pocoo.org/wiki/
167
 
 
168
 
Clients
169
 
-------
170
 
 
171
 
Now you can use `bzr+http://` URLs, e.g.::
172
 
 
173
 
    bzr log bzr+http://example.com/code/my-branch
174
 
 
175
 
Plain HTTP access should continue to work::
176
 
 
177
 
    bzr log http://example.com/code/my-branch
178
 
 
179
 
 
180
 
Advanced configuration
181
 
======================
182
 
 
183
 
Because the Bazaar HTTP smart server is a WSGI application, it can be used with
184
 
any 3rd-party WSGI middleware or server that conforms the WSGI standard.  The
185
 
only requirements are:
186
 
 
187
 
  * to construct a `SmartWSGIApp`, you need to specify a **root transport** that it
188
 
    will serve.
189
 
  * each request's `environ` dict must have a **'bzrlib.relpath'** variable set.
190
 
 
191
 
The `make_app` helper used in the example constructs a `SmartWSGIApp` with a
192
 
transport based on the `root` path given to it, and calculates the
193
 
'bzrlib.relpath` for each request based on the `prefix` and `path_var`
194
 
arguments.  In the example above, it will take the 'REQUEST_URI' (which is set
195
 
by Apache), strip the '/code/' prefix and the '/.bzr/smart' suffix, and set that
196
 
as the 'bzrlib.relpath', so that a request for '/code/foo/bar/.bzr/smart' will
197
 
result in a 'bzrlib.relpath' of 'foo/bzr'.
198
 
 
199
 
It's possible to configure a smart server for a non-local transport, or that
200
 
does arbitrary path translations, etc, by constructing a `SmartWSGIApp`
201
 
directly.  Refer to the docstrings of `bzrlib.transport.http.wsgi` and the `WSGI
202
 
standard`_ for further information.
203
 
 
204
 
.. _WSGI standard: http://www.python.org/dev/peps/pep-0333/
205
 
 
206
 
 
207
 
Pushing over ``bzr+http://``
208
 
----------------------------
209
 
 
210
 
It is possible to allow pushing data over the http smart server. The
211
 
easiest way to do this, is to just supply ``readonly=False`` to the
212
 
``wsgi.make_app()`` call. But be careful, because the smart protocol does
213
 
not contain any Authentication. So if you enable write support, you will
214
 
want to restrict access to ``.bzr/smart`` URLs to restrict who can
215
 
actually write data on your system.  At this time, it is not possible to
216
 
allow some people to have read-only access and others to have read-write
217
 
access to the same urls. Because at the HTTP layer (which is doing the
218
 
Authenticating), everything is just a POST request.  However, it would
219
 
certainly be possible to have HTTPS require authentication and use a
220
 
writable server, and plain HTTP allow read-only access.
221
 
 
222
 
 
223
 
.. 
224
 
   vim: ft=rst tw=74 et