/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/en/user-guide/http_smart_server.txt

  • Committer: Jelmer Vernooij
  • Date: 2017-05-21 19:09:26 UTC
  • mfrom: (6622.1.36 breezy)
  • Revision ID: jelmer@jelmer.uk-20170521190926-5vtz8xaf0e9ylrpc
Merge rename to breezy.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/http_smart_server.txt
1
 
Serving Bazaar with Apache
 
1
Serving Breezy with Apache
2
2
==========================
3
3
 
4
 
This document describes one way to set up a Bazaar HTTP smart server,
 
4
This document describes one way to set up a Breezy HTTP smart server,
5
5
using Apache 2.0 and FastCGI or mod_python or mod_wsgi.
6
6
 
7
7
For more information on the smart server, and other ways to configure it
11
11
-------
12
12
 
13
13
You have a webserver already publishing `/srv/example.com/www/code` as
14
 
`http://example.com/code/...` with plain HTTP.  It contains bzr branches and
 
14
`http://example.com/code/...` with plain HTTP.  It contains branches and
15
15
directories like `/srv/example.com/www/code/branch-one` and
16
16
`/srv/example.com/www/code/my-repo/branch-two`.  You want to provide read-only
17
17
smart server access to these directories in addition to the existing HTTP
39
39
        # ...
40
40
    </Directory>
41
41
 
42
 
We need to change it to handle all requests for URLs ending in `.bzr/smart`.  It
 
42
We need to change it to handle all requests for URLs ending in `.brz/smart`.  It
43
43
will look like::
44
44
 
45
45
    Alias /code /srv/example.com/www/code
47
47
        Options Indexes FollowSymLinks
48
48
        RewriteEngine On
49
49
        RewriteBase /code
50
 
        RewriteRule ^(.*/)?\.bzr/smart$ /srv/example.com/scripts/bzr-smart.fcgi
 
50
        RewriteRule ^(.*/)?\.bzr/smart$ /srv/example.com/scripts/brz-smart.fcgi
51
51
    </Directory>
52
52
 
53
 
    # bzr-smart.fcgi isn't under the DocumentRoot, so Alias it into the URL
 
53
    # brz-smart.fcgi isn't under the DocumentRoot, so Alias it into the URL
54
54
    # namespace so it can be executed.
55
 
    Alias /srv/example.com/scripts/bzr-smart.fcgi /srv/example.com/scripts/bzr-smart.fcgi
 
55
    Alias /srv/example.com/scripts/brz-smart.fcgi /srv/example.com/scripts/brz-smart.fcgi
56
56
    <Directory /srv/example.com/scripts>
57
57
        Options ExecCGI
58
 
        <Files bzr-smart.fcgi>
 
58
        <Files brz-smart.fcgi>
59
59
            SetHandler fastcgi-script
60
60
        </Files>
61
61
    </Directory>
62
62
 
63
 
This instructs Apache to hand requests for any URL ending with `/.bzr/smart`
64
 
inside `/code` to a Bazaar smart server via FastCGI.
 
63
This instructs Apache to hand requests for any URL ending with `/.brz/smart`
 
64
inside `/code` to a Breezy smart server via FastCGI.
65
65
 
66
66
Refer to the mod_rewrite_ and mod_fastcgi_ documentation for further
67
67
information.
80
80
Define the rewrite rules with mod_rewrite the same way as for FastCGI, except
81
81
change::
82
82
 
83
 
    RewriteRule ^(.*/)?\.bzr/smart$ /srv/example.com/scripts/bzr-smart.fcgi
 
83
    RewriteRule ^(.*/)?\.bzr/smart$ /srv/example.com/scripts/brz-smart.fcgi
84
84
 
85
85
to::
86
86
 
87
 
    RewriteRule ^(.*/)?\.bzr/smart$ /srv/example.com/scripts/bzr-smart.py
 
87
    RewriteRule ^(.*/)?\.bzr/smart$ /srv/example.com/scripts/brz-smart.py
88
88
 
89
89
Like with mod_fastcgi, we also define how our script is to be handled::
90
90
 
91
 
    Alias /srv/example.com/scripts/bzr-smart.py /srv/example.com/scripts/bzr-smart.py
 
91
    Alias /srv/example.com/scripts/brz-smart.py /srv/example.com/scripts/brz-smart.py
92
92
    <Directory /srv/example.com/scripts>
93
 
        <Files bzr-smart.py>
 
93
        <Files brz-smart.py>
94
94
            PythonPath "sys.path+['/srv/example.com/scripts']"
95
95
            AddHandler python-program .py
96
 
            PythonHandler bzr-smart::handler
 
96
            PythonHandler brz-smart::handler
97
97
        </Files>
98
98
    </Directory>
99
99
 
100
 
This instructs Apache to hand requests for any URL ending with `/.bzr/smart`
101
 
inside `/code` to a Bazaar smart server via mod_python.
 
100
This instructs Apache to hand requests for any URL ending with `/.brz/smart`
 
101
inside `/code` to a Breezy smart server via mod_python.
102
102
 
103
 
NOTE: If you don't have bzrlib in your PATH, you will be need to change the
 
103
NOTE: If you don't have breezy in your PATH, you will be need to change the
104
104
following line::
105
105
 
106
106
            PythonPath "sys.path+['/srv/example.com/scripts']"
107
107
 
108
108
To::
109
109
 
110
 
            PythonPath "['/path/to/bzr']+sys.path+['/srv/example.com/scripts']"
 
110
            PythonPath "['/path/to/brz']+sys.path+['/srv/example.com/scripts']"
111
111
 
112
112
 
113
113
Refer to the mod_python_ documentation for further information.
119
119
~~~~~~~~
120
120
 
121
121
First, configure mod_wsgi, e.g. enabling the mod with a2enmod wsgi.
122
 
We need to change it to handle all requests for URLs ending in `.bzr/smart`.  It
 
122
We need to change it to handle all requests for URLs ending in `.brz/smart`.  It
123
123
will look like::
124
124
 
125
 
    WSGIScriptAliasMatch ^/code/.*/\.bzr/smart$ /srv/example.com/scripts/bzr.wsgi
 
125
    WSGIScriptAliasMatch ^/code/.*/\.bzr/smart$ /srv/example.com/scripts/brz.wsgi
126
126
 
127
127
    #The three next lines allow regular GETs to work too
128
128
    RewriteEngine On
133
133
        WSGIApplicationGroup %{GLOBAL}
134
134
    </Directory>
135
135
 
136
 
This instructs Apache to hand requests for any URL ending with `/.bzr/smart`
137
 
inside `/code` to a Bazaar smart server via WSGI, and any other URL inside
 
136
This instructs Apache to hand requests for any URL ending with `/.brz/smart`
 
137
inside `/code` to a Breezy smart server via WSGI, and any other URL inside
138
138
`/code` to be served directly by Apache.
139
139
 
140
140
Refer to the mod_wsgi_ documentation for further information.
141
141
 
142
142
.. _mod_wsgi: http://code.google.com/p/modwsgi/
143
143
 
144
 
Configuring Bazaar
 
144
Configuring Breezy
145
145
------------------
146
146
 
147
147
FastCGI
148
148
~~~~~~~
149
149
 
150
150
We've configured Apache to run the smart server at
151
 
`/srv/example.com/scripts/bzr-smart.fcgi`.  This is just a simple script we need
 
151
`/srv/example.com/scripts/brz-smart.fcgi`.  This is just a simple script we need
152
152
to write to configure a smart server, and glue it to the FastCGI gateway.
153
153
Here's what it looks like::
154
154
 
155
155
    import fcgi
156
 
    from bzrlib.transport.http import wsgi
 
156
    from breezy.transport.http import wsgi
157
157
 
158
158
    smart_server_app = wsgi.make_app(
159
159
        root='/srv/example.com/www/code',
174
174
~~~~~~~~~~
175
175
 
176
176
We've configured Apache to run the smart server at
177
 
`/srv/example.com/scripts/bzr-smart.py`.  This is just a simple script we need
 
177
`/srv/example.com/scripts/brz-smart.py`.  This is just a simple script we need
178
178
to write to configure a smart server, and glue it to the mod_python gateway.
179
179
Here's what it looks like::
180
180
 
181
181
    import modpywsgi
182
 
    from bzrlib.transport.http import wsgi
 
182
    from breezy.transport.http import wsgi
183
183
 
184
184
    smart_server_app = wsgi.make_app(
185
185
        root='/srv/example.com/www/code',
197
197
The `modpywsgi` module can be found at
198
198
http://ice.usq.edu.au/svn/ice/trunk/apps/ice-server/modpywsgi.py. It was
199
199
part of pocoo_. You sould make sure you place modpywsgi.py in the same
200
 
directory as bzr-smart.py (ie. /srv/example.com/scripts/).
 
200
directory as brz-smart.py (ie. /srv/example.com/scripts/).
201
201
 
202
202
.. _pocoo: http://dev.pocoo.org/projects/pocoo/
203
203
 
206
206
~~~~~~~~
207
207
 
208
208
We've configured Apache to run the smart server at
209
 
`/srv/example.com/scripts/bzr.wsgi`.  This is just a simple script we need
 
209
`/srv/example.com/scripts/brz.wsgi`.  This is just a simple script we need
210
210
to write to configure a smart server, and glue it to the WSGI gateway.
211
211
Here's what it looks like::
212
212
 
213
 
    from bzrlib.transport.http import wsgi
 
213
    from breezy.transport.http import wsgi
214
214
 
215
215
    def application(environ, start_response):
216
216
        app = wsgi.make_app(
223
223
Clients
224
224
-------
225
225
 
226
 
Now you can use `bzr+http://` URLs or just `http://` URLs, e.g.::
 
226
Now you can use `brz+http://` URLs or just `http://` URLs, e.g.::
227
227
 
228
 
    bzr log bzr+http://example.com/code/my-branch
 
228
    brz log brz+http://example.com/code/my-branch
229
229
 
230
230
Plain HTTP access should continue to work::
231
231
 
232
 
    bzr log http://example.com/code/my-branch
 
232
    brz log http://example.com/code/my-branch
233
233
 
234
234
Advanced configuration
235
235
----------------------
236
236
 
237
 
Because the Bazaar HTTP smart server is a WSGI application, it can be used with
 
237
Because the Breezy HTTP smart server is a WSGI application, it can be used with
238
238
any 3rd-party WSGI middleware or server that conforms the WSGI standard.  The
239
239
only requirements are:
240
240
 
241
241
  * to construct a `SmartWSGIApp`, you need to specify a **root transport** that it
242
242
    will serve.
243
 
  * each request's `environ` dict must have a **'bzrlib.relpath'** variable set.
 
243
  * each request's `environ` dict must have a **'breezy.relpath'** variable set.
244
244
 
245
245
The `make_app` helper used in the example constructs a `SmartWSGIApp` with a
246
246
transport based on the `root` path given to it, and calculates the
247
 
'bzrlib.relpath` for each request based on the `prefix` and `path_var`
 
247
'breezy.relpath` for each request based on the `prefix` and `path_var`
248
248
arguments.  In the example above, it will take the 'REQUEST_URI' (which is set
249
 
by Apache), strip the '/code/' prefix and the '/.bzr/smart' suffix, and set that
250
 
as the 'bzrlib.relpath', so that a request for '/code/foo/bar/.bzr/smart' will
251
 
result in a 'bzrlib.relpath' of 'foo/bzr'.
 
249
by Apache), strip the '/code/' prefix and the '/.brz/smart' suffix, and set that
 
250
as the 'breezy.relpath', so that a request for '/code/foo/bar/.brz/smart' will
 
251
result in a 'breezy.relpath' of 'foo/brz'.
252
252
 
253
253
It's possible to configure a smart server for a non-local transport, or that
254
254
does arbitrary path translations, etc, by constructing a `SmartWSGIApp`
255
 
directly.  Refer to the docstrings of `bzrlib.transport.http.wsgi` and the `WSGI
 
255
directly.  Refer to the docstrings of `breezy.transport.http.wsgi` and the `WSGI
256
256
standard`_ for further information.
257
257
 
258
258
.. _WSGI standard: http://www.python.org/dev/peps/pep-0333/
265
265
easiest way to do this, is to just supply ``readonly=False`` to the
266
266
``wsgi.make_app()`` call. But be careful, because the smart protocol does
267
267
not contain any Authentication. So if you enable write support, you will
268
 
want to restrict access to ``.bzr/smart`` URLs to restrict who can
 
268
want to restrict access to ``.brz/smart`` URLs to restrict who can
269
269
actually write data on your system, e.g. in apache it looks like::
270
270
 
271
271
    <Location /code>
284
284
require authentication and use a writable server, and plain HTTP allow
285
285
read-only access.
286
286
 
287
 
If bzr gives an error like this when accessing your HTTPS site::
 
287
If brz gives an error like this when accessing your HTTPS site::
288
288
 
289
 
  bzr: ERROR: Connection error: curl connection error (server certificate verification failed.
 
289
  brz: ERROR: Connection error: curl connection error (server certificate verification failed.
290
290
  CAfile:/etc/ssl/certs/ca-certificates.crt CRLfile: none)
291
291
 
292
292
You can workaround it by using ``https+urllib`` rather than ``http`` in your