~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/http_smart_server.txt

  • Committer: Vincent Ladeuil
  • Date: 2007-05-25 17:12:52 UTC
  • mto: (2485.8.44 bzr.connection.sharing)
  • mto: This revision was merged to the branch mainline in revision 2646.
  • Revision ID: v.ladeuil+lp@free.fr-20070525171252-hsooebpkqtb3j6ef
Add test for cat and missing.

* bzrlib/tests/commands/__init__.py:
(test_suite): Add test_cat and test_missing.

* bzrlib/tests/commands/test_cat.py: 
New file.

* bzrlib/tests/commands/test_missing.py: 
New file.

Show diffs side-by-side

added added

removed removed

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