~loggerhead-team/loggerhead/trunk-rich

44 by Robey Pointer
better readme
1
LOGGERHEAD
2
==========
3
384 by Martin Albisetti
Release 1.17
4
[ Version 1.17 for Bazaar 1.17 ]
59 by Robey Pointer
add version info to readme
5
146.1.5 by Michael Hudson
review comments
6
Loggerhead is a web viewer for Bazaar branches.  It can be used to
146.1.1 by Michael Hudson
release preparations
7
navigate a branch history, annotate files, perform searches... all the
8
usual things.
44 by Robey Pointer
better readme
9
165.1.5 by Michael Hudson
more readme stuff
10
165.1.2 by Michael Hudson
start on README
11
GETTING STARTED
12
---------------
13
305 by Michael Hudson
mention new dependency on simplejson
14
Loggerhead depends on:
15
218.1.1 by Marius Kruger
Add alternative insallation notes and mention the --prefix option in README.txt
16
1) SimpleTAL for templating.
305 by Michael Hudson
mention new dependency on simplejson
17
   On Ubuntu, `sudo apt-get install python-simpletal`
218.1.1 by Marius Kruger
Add alternative insallation notes and mention the --prefix option in README.txt
18
   or download from http://www.owlfish.com/software/simpleTAL/download.html
305 by Michael Hudson
mention new dependency on simplejson
19
2) simplejson for producing JSON data.
20
   On Ubuntu, `sudo apt-get install python-simplejson`
21
   or use `easy_install simplejson`.
22
3) Paste for the server. (You need version 1.2 or newer of Paste.)
23
   On Ubuntu, `sudo apt-get install python-paste`
218.1.1 by Marius Kruger
Add alternative insallation notes and mention the --prefix option in README.txt
24
   or use `easy_install Paste`
305 by Michael Hudson
mention new dependency on simplejson
25
4) Paste Deploy  (optional, needed when proxying through Apache)
26
   On Ubuntu, `sudo apt-get install python-pastedeploy`
218.1.1 by Marius Kruger
Add alternative insallation notes and mention the --prefix option in README.txt
27
   or use `easy_install PasteDeploy`
165.1.2 by Michael Hudson
start on README
28
185 by Martin Albisetti
* Clarify License and add copyright to all file headers (John Arbash Meinel)
29
Then simply run the 'serve-branches' with the branch you want to
165.1.5 by Michael Hudson
more readme stuff
30
serve on the command line:
31
185 by Martin Albisetti
* Clarify License and add copyright to all file headers (John Arbash Meinel)
32
    ./serve-branches ~/path/to/branch
165.1.5 by Michael Hudson
more readme stuff
33
34
The script listens on port 8080 so head to http://localhost:8080/ in
35
your browser to see the branch.  You can also pass a directory that
36
contains branches to the script, and it will serve a very simple
37
directory listing at other pages.
38
39
You may update the Bazaar branches being viewed at any time.
40
Loggerhead will notice and refresh, and Bazaar uses its own branch
41
locking to prevent corruption.
42
385 by Martin Albisetti
Super-trivial commit
43
To run loggerhead as a linux daemon:
228.1.2 by Marius Kruger
Add installation instructions for loggerheadd to README.txt and changed ubuntu -> Ubuntu for consistancy.
44
1) Copy loggerheadd to /etc/init.d
45
2) Edit the file to configure where your loggerhead is installed, and which
46
   serve-branches options you would like.
47
3) Register the service
48
   cd /etc/init.d
49
   a) on upstart based systems like Ubuntu run: 
50
      update-rc.d loggerheadd defaults
51
   b) on Sysvinit based systems like Centos or SuSE run:
52
      chkconfig --add loggerheadd
165.1.2 by Michael Hudson
start on README
53
262.2.1 by Martin Pool
Stub code to allow loggerhead to load as a plugin
54
55
LOGGERHEAD AS A BAZAAR PLUGIN
56
-----------------------------
57
58
This branch contains experimental support for using Loggerhead as a Bazaar
59
plugin.  To use it, place the top-level Loggerhead directory (the one
60
containing this file) at ``~/.bazaar/plugins/loggerhead``.
61
62
165.1.2 by Michael Hudson
start on README
63
USING A CONFIG FILE
64
-------------------
65
352.6.7 by Martin Albisetti
Tweaked NEWS and README.txt
66
To hide branches from being displayed, add to ``~/.bazaar/locations.conf``,
67
under the branch's section:
68
69
    [/path/to/branch]
70
    http_serve = False
71
72
73
More configuration options to come soon.
147.1.1 by Michael Hudson
poolie feedback
74
89 by Robey Pointer
fix up dev.cfg so that nobody will ever have to edit it, by letting the
75
165.1.2 by Michael Hudson
start on README
76
SERVING LOGGERHEAD FROM BEHIND APACHE
77
-------------------------------------
78
79
If you want to view Bazaar branches from your existing Apache
80
installation, you'll need to configure Apache to proxy certain
81
requests to Loggerhead.  Adding lines like this to you Apache
82
configuration is one way to do this::
83
84
    <Location "/branches/">
277 by Michael Hudson
* make example Apache stanza more correct with how PasteDeploy works
85
        ProxyPass http://127.0.0.1:8080/branches/
86
        ProxyPassReverse http://127.0.0.1:8080/branches/
165.1.2 by Michael Hudson
start on README
87
    </Location>
88
185 by Martin Albisetti
* Clarify License and add copyright to all file headers (John Arbash Meinel)
89
If Paste Deploy is installed, the 'serve-branches' script can be
165.1.5 by Michael Hudson
more readme stuff
90
run behind a proxy at the root of a site, but if you're running it at
218.1.1 by Marius Kruger
Add alternative insallation notes and mention the --prefix option in README.txt
91
some path into the site, you'll need to specify is using '--prefix=/some_path'.
44 by Robey Pointer
better readme
92
352.6.7 by Martin Albisetti
Tweaked NEWS and README.txt
93
94
SEARCH
95
------
96
97
Search is currently supported by using the bzr-search plugin (available
98
at: ``https://launchpad.net/bzr-search``
99
You need to have the plugin installed and each branch indexed to allow
100
searching on branches.
44 by Robey Pointer
better readme
101
102
SUPPORT
103
-------
104
147.1.1 by Michael Hudson
poolie feedback
105
Loggerhead is loosely based on bazaar-webserve, which was loosely
106
based on hgweb.  Discussion should take place on the bazaar-dev
107
mailing list at bazaar@lists.canonical.com.  You can join the list at
108
<https://lists.ubuntu.com/mailman/listinfo/bazaar>.  You don't need to
109
subscribe to post, but your first post will be held briefly for manual
110
moderation.
111
165.1.2 by Michael Hudson
start on README
112
Bugs are tracked on Launchpad; start at:
113
114
    https://bugs.launchpad.net/loggerhead
387 by Martin Albisetti
Add to the readme how to run loggerhead tests
115
116
117
HACKING
118
-------
119
120
To run loggerhead tests, you will need the package python-nose,
121
and run in the loggerhead directory:
122
123
    nosetests
124