/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: v.ladeuil+lp at free
  • Date: 2007-02-04 17:41:12 UTC
  • mto: (2323.7.1 redirection)
  • mto: This revision was merged to the branch mainline in revision 2390.
  • Revision ID: v.ladeuil+lp@free.fr-20070204174112-iv6gxzinnjddlaxj
Add tests for redirection. Preserve transport decorations.

* bzrlib/tests/test_http.py:
(TestRedirections): new tests.

* bzrlib/tests/HttpServer.py:
(HttpServer): Make server host and port public once the socket
have been established.

* bzrlib/tests/HTTPTestUtil.py:
(RedirectRequestHandler, HTTPServerRedirecting): New http test
server for redirections. Only a whole host can be redirected, so
far.

* bzrlib/errors.py:
(RedirectRequested.__init__): Add a 'qual_proto' oso that
transport decorations can be transmitted to redirected transport.
(RedirectRequested._requalify_url,
RedirectRequested.get_source_url,
RedirectRequested.get_target_url): New methods providing fully
decorated urls.

* bzrlib/bzrdir.py:
(BzrDir.open_from_transport): The redirection should preserve
transport decorations.
(BzrDirMetaFormat1): To be able to specialize bzr branches from
foreign branches, we need to register BzrDirMetaFormat1 as the
default control format (instead of BzrDirMetaFormat which is
abstract and can still be used by foreign branches).

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 setup a Bazaar HTTP smart server, using
 
9
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