← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/admin-guide/code-browsing.txt

Add a NEWS entry and prepare submission.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/admin-guide/code-browsing.txt
 
1
Web-based code browsing
 
2
=======================
 
3
 
 
4
Browsing the history of a project online is an important part of version
 
5
control, since it allows people to easily see what happens in a branch
 
6
without having to have a local, up-to-date copy of that branch.  There are a
 
7
number of possible choices for browsing Bazaar branches on the web, but we
 
8
will cover one of them in particular detail and briefly mention the other
 
9
choices where they differ.
 
10
 
 
11
Loggerhead
 
12
----------
 
13
 
 
14
Loggerhead_ is a code browsing interface for Bazaar branches (now used in
 
15
Launchpad).  To see an example of Loggerhead in action, browse to
 
16
http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev/files which is the loggerhead
 
17
view of Bazaar's trunk branch.  Loggerhead runs as a web application on the
 
18
server which is accessed over HTTP via a RESTful interface.  It is possible to
 
19
run this application on its own dedicated port as
 
20
``http://www.example.com:8080`` or to proxy this location behind a separate web
 
21
server, for example at ``http://www.example.com/loggerhead/``.  We will discuss
 
22
both of these configurations below.
 
23
 
 
24
.. _Loggerhead: http://launchpad.net/loggerhead
 
25
 
 
26
Requirements
 
27
~~~~~~~~~~~~
 
28
 
 
29
Loggerhead depends on a number of other Python packages for the various Web
 
30
technologies that it builds on.  Some of these must be installed to use
 
31
loggerhead, although some of them are optional.  From the loggerhead `README`
 
32
file, these are
 
33
 
 
34
1) SimpleTAL for templating.
 
35
   On Ubuntu, `sudo apt-get install python-simpletal`
 
36
   or download from http://www.owlfish.com/software/simpleTAL/download.html
 
37
2) simplejson for producing JSON data.
 
38
   On Ubuntu, `sudo apt-get install python-simplejson`
 
39
   or use `easy_install simplejson`.
 
40
3) Paste for the server. (You need version 1.2 or newer of Paste.)
 
41
   On Ubuntu, `sudo apt-get install python-paste`
 
42
   or use `easy_install Paste`
 
43
4) Paste Deploy  (optional, needed when proxying through Apache)
 
44
   On Ubuntu, `sudo apt-get install python-pastedeploy`
 
45
   or use `easy_install PasteDeploy`
 
46
5) flup (optional, needed to use FastCGI, SCGI or AJP)
 
47
   On Ubuntu, `sudo apt-get install python-flup`
 
48
   or use `easy_install flup`
 
49
 
 
50
Although directions for installing these on Ubuntu Linux are given, most other
 
51
Linux distributions should package these dependencies, making installation
 
52
easy.  For Windows and Mac OS X, they should all be ``easy_install``-able or at
 
53
worst installable from the Python sources.
 
54
 
 
55
Built-in Web Server
 
56
~~~~~~~~~~~~~~~~~~~
 
57
 
 
58
Loggerhead has a built-in web server and when started with the
 
59
``serve-branches`` command, that web server is started on a default port
 
60
listening on the localhost.  If port 8080 (the default) is accessible on
 
61
``www.example.com``, then running
 
62
 
 
63
::
 
64
 
 
65
  $ serve-branches --host=www.example.com --port=8080 /srv/bzr
 
66
 
 
67
will list all of the available branches under that directory on
 
68
``http://www.example.com:8080/``, so that the ProjectX trunk could be browsed
 
69
at ``http://www.example.com:8080/projectx/trunk``.  Note that loggerhead
 
70
provides HTTP access to the underlying Bazaar branches (similar to that
 
71
described in `Smart server over HTTP(S)
 
72
<other-setups.html#smart-server-over-http-s>`_), so this command should be run
 
73
as a user without write privileges in ``/srv/bzr``.  By default, loggerhead
 
74
only listens on the localhost, not any external ports, unless specified as
 
75
above.
 
76
 
 
77
Behind a Proxy
 
78
~~~~~~~~~~~~~~
 
79
 
 
80
A more common and more safe way to run loggerhead is behind another web server
 
81
which will proxy certain requests to the loggerhead server on the localhost.
 
82
To do this, you need to have PasteDeploy installed (see `Requirements`_).
 
83
Assuming that your server has Apache running, you need to add configuration
 
84
such as this to set up the proxy
 
85
 
 
86
::
 
87
 
 
88
    <Location "/loggerhead/">
 
89
        ProxyPass http://127.0.0.1:8080/
 
90
        ProxyPassReverse http://127.0.0.1:8080/
 
91
    </Location>
 
92
 
 
93
If your proxy runs at some path within the server, then the ``serve-branches``
 
94
command must be started with the ``--prefix`` option.  For this example, we
 
95
could start loggerhead with the command
 
96
 
 
97
::
 
98
 
 
99
  $ serve-branches --prefix=/loggerhead /srv/bzr
 
100
 
 
101
This would allow the trunk branch of ProjectX to be browsed at
 
102
``http://www.example.com/loggerhead/projectx/trunk``.
 
103
 
 
104
Loggerhead comes with a script allowing it to run as a service on init.d based
 
105
Linux systems.  Contributions to do a similar thing on Windows servers would
 
106
be welcomed at http://launchpad.net/loggerhead.
 
107
  
 
108
 
 
109
Other web interfaces
 
110
--------------------
 
111
 
 
112
There are a number of other web interfaces available for Bazaar branches (see
 
113
the list at http://bazaar-vcs.org/WebInterfaces) and we will just mention a
 
114
couple of them here for their advantages in particular situations.
 
115
 
 
116
trac+bzr (http://launchpad.net/trac-bzr)
 
117
  Trac is a popular web app that integrates a browser for branches, an issue
 
118
  tracker and a wiki.  trac+bzr is a trac extension that allows for the
 
119
  trac to be used with Bazaar.
 
120
 
 
121
webbzr (http://thoughts.enseed.com/webbzr)
 
122
  This is a notable solution because it is written in pure PHP for web hosts
 
123
  that don't provide a way to run arbitrary Python applications such as Trac
 
124
  or Loggerhead.
 
125
 
 
126
Redmine (http://redmine.org/)
 
127
  Like trac, Redmine is a full project management application using the Ruby
 
128
  on Rails framework.  It includes support for Bazaar branches.