/loggerhead/trunk

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/loggerhead/trunk

« back to all changes in this revision

Viewing changes to docs/index.rst

  • Committer: Ubuntu One Auto Copilot
  • Author(s): Jelmer Vernooij
  • Date: 2023-02-03 20:03:20 UTC
  • mfrom: (547.1.1 lp:loggerhead)
  • Revision ID: otto-copilot@canonical.com-20230203200320-czhzowsk0q4v4g94
Upgrade Python code to a modern version

Merged from https://code.launchpad.net/~jelmer/loggerhead/pyupgrade/+merge/436797

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/index.rst
1
1
Loggerhead:  A web viewer for ``bzr`` branches
2
2
==============================================
3
3
 
4
 
Loggerhead is a web viewer for projects in Bazaar. It can be used to navigate 
 
4
Loggerhead is a web viewer for projects in Breezy. It can be used to navigate
5
5
a branch history, annotate files, view patches, perform searches, etc.
6
6
Loggerhead is heavily based on `bazaar-webserve
7
7
<https://launchpad.net/bzr-webserve>`_, which was, in turn, loosely
13
13
 
14
14
Loggerhead depends on the following Python libraries.:
15
15
 
16
 
- SimpleTAL for templating.
17
 
 
18
 
- simplejson for producing JSON data.
 
16
- Chameleon for templating.
19
17
 
20
18
- Paste for the server. (You need version 1.2 or newer of Paste).
21
19
 
22
 
- Paste Deploy  (optional, needed when proxying through Apache).
 
20
- PasteDeploy (optional, needed when proxying through Apache).
23
21
 
24
22
- flup (optional, needed to use FastCGI, SCGI or AJP).
25
23
 
29
27
 
30
28
.. code-block:: sh
31
29
 
32
 
   $ sudo apt-get install python-simpletal
33
 
   $ sudo apt-get install python-simplejson
 
30
   $ sudo apt-get install python-chameleon
34
31
   $ sudo apt-get install python-paste
35
32
   $ sudo apt-get install python-pastedeploy
36
33
   $ sudo apt-get install python-flup
37
34
 
38
 
Installing Dependencies Using :command:`easy_install`
39
 
#####################################################
 
35
Installing Dependencies Using :command:`pip`
 
36
############################################
 
37
 
 
38
You should normally create and activate a virtual environment first.
40
39
 
41
40
.. code-block:: sh
42
41
 
43
 
   $ easy_install \
44
 
     -f http://www.owlfish.com/software/simpleTAL/py2compatible/download.html \
45
 
     SimpleTAL
46
 
   $ easy_install simplejson
47
 
   $ easy_install Paste
48
 
   $ easy_install PasteDeploy
49
 
   $ easy_install flup
 
42
   # Basic installation only
 
43
   $ pip install loggerhead
 
44
   # Installation for proxying through Apache
 
45
   $ pip install 'loggerhead[proxied]'
 
46
   # Installation for FastCGI, SCGI or AJP
 
47
   $ pip install 'loggerhead[flup]'
50
48
 
51
49
 
52
50
Running the Standalone Loggerhead Server
53
51
----------------------------------------
54
52
 
55
53
After installing all the dependencies, you should be able to run
56
 
:command:`serve-branches` with the branch you want to serve on the
 
54
:command:`loggerhead-serve` with the branch you want to serve on the
57
55
command line:
58
56
 
59
57
.. code-block:: sh
60
58
 
61
 
    ./serve-branches ~/path/to/branch
 
59
    ./loggerhead-serve ~/path/to/branch
62
60
 
63
61
By default, the script listens on port 8080, so head to
64
62
http://localhost:8080/ in your browser to see the branch.
70
68
Loggerhead will notice and refresh, and Bazaar uses its own branch
71
69
locking to prevent corruption.
72
70
 
73
 
See :doc:`serve-branches` for all command line options.
 
71
See :doc:`loggerhead-serve` for all command line options.
74
72
 
75
73
Running Loggerhead as a Daemon
76
74
------------------------------
84
82
   $ sudo cp ./loggerheadd /etc/init.d
85
83
 
86
84
2) Edit the file to configure where your Loggerhead is installed, and which
87
 
   serve-branches options you would like.
 
85
   loggerhead-serve options you would like.
88
86
 
89
87
.. code-block:: sh
90
88
 
101
99
   $ sudo chkconfig --add loggerheadd
102
100
 
103
101
 
104
 
Using Loggerhead as a Bazaar Plugin
105
 
------------------------------------
 
102
Using Loggerhead as a Breezy Plugin
 
103
-----------------------------------
106
104
 
107
 
This branch contains experimental support for using Loggerhead as a Bazaar
 
105
This branch contains experimental support for using Loggerhead as a Breezy
108
106
plugin.  To use it, place the top-level Loggerhead directory (the one
109
 
containing COPYING.txt) at ``~/.bazaar/plugins/loggerhead``.  E.g.:
 
107
containing COPYING.txt) at ``~/.config/breezy/plugins/loggerhead``.  E.g.:
110
108
 
111
109
.. code-block:: sh
112
110
 
113
 
   $ bzr branch lp:loggerhead ~/.bazaar/plugins/loggerhead
 
111
   $ bzr branch lp:loggerhead ~/.config/breezy/plugins/loggerhead
114
112
   $ cd ~/myproject
115
113
   $ bzr serve --http
116
114
 
118
116
Using a Config File
119
117
-------------------
120
118
 
121
 
To hide branches from being displayed, add to ``~/.bazaar/locations.conf``,
 
119
To hide branches from being displayed, add to ``~/.config/breezy/locations.conf``,
122
120
under the branch's section:
123
121
 
124
122
.. code-block:: ini
132
130
Serving Loggerhead behind Apache
133
131
--------------------------------
134
132
 
135
 
If you want to view Bazaar branches from your existing Apache
 
133
If you want to view Breezy branches from your existing Apache
136
134
installation, you'll need to configure Apache to proxy certain
137
135
requests to Loggerhead.  Adding lines like this to your Apache
138
136
configuration is one way to do this:
144
142
        ProxyPassReverse http://127.0.0.1:8080/branches/
145
143
    </Location>
146
144
 
147
 
If Paste Deploy is installed, the :command:`serve-branches` script can be
 
145
If Paste Deploy is installed, the :command:`loggerhead-serve` script can be
148
146
run behind a proxy at the root of a site, but if you're running it at
149
147
some path into the site, you'll need to specify it using
150
148
``--prefix=/some_path``.
151
149
 
 
150
Serving Loggerhead with mod_wsgi
 
151
--------------------------------
 
152
 
 
153
A second method for using Loggerhead with apache is to have apache itself
 
154
execute Loggerhead via mod_wsgi.  You need to add configuration for apache and
 
155
for breezy to make this work.  Example config files are in the Loggerhead doc
 
156
directory as apache-loggerhead.conf and breezy.conf.  You can copy them into
 
157
place and use them as a starting point following these directions:
 
158
 
 
159
1) Install mod_wsgi.  On Ubuntu and other Debian derived distros::
 
160
 
 
161
    sudo apt-get install libapache2-mod-wsgi
 
162
 
 
163
   On Fedora-derived distros::
 
164
 
 
165
    su -c yum install mod_wsgi
 
166
 
 
167
2) Copy the breezy.conf file where apache will find it (May be done for you if
 
168
   you installed Loggerhead from a distribution package)::
 
169
 
 
170
    # install -d -o apache -g apache -m 0755 /etc/loggerhead
 
171
    # cp -p /usr/share/doc/loggerhead*/breezy.conf /etc/loggerhead/
 
172
    # mkdir -p /var/www/.config
 
173
    # ln -s /etc/loggerhead /var/www/.config/breezy
 
174
 
 
175
3) Create the cache directory (May be done for you if you installed Loggerhead
 
176
   from a distribution package)::
 
177
 
 
178
    # install -d -o apache -g apache -m 0700 /var/cache/loggerhead/
 
179
 
 
180
4) Edit /etc/loggerhead/breezy.conf.  You need to set http_root_dir to the filesystem
 
181
   path that you will find your bzr branches under.  Note that normal
 
182
   directories under that path will also be visible in Loggerhead.
 
183
 
 
184
5) Install the apache conf file::
 
185
 
 
186
     # cp -p /usr/share/doc/loggerhead*/apache-loggerhead.conf /etc/httpd/conf.d/loggerhead.conf
 
187
 
 
188
6) Edit /etc/httpd/conf.d/loggerhead.conf to point to the url you desire to
 
189
   serve Loggerhead on.  This should match with the setting for
 
190
   http_user_prefix in breezy.conf
 
191
 
 
192
7) Restart apache and you should be able to start browsing
 
193
 
 
194
.. note:: If you have SELinux enabled on your system you may need to allow
 
195
   apache to execute files in temporary directories.  You will get a
 
196
   MemoryError traceback from python if this is the case.  This is because of
 
197
   the way that python ctypes interacts with libffi.  To rectify this, you may
 
198
   have to do several things, such as mounting tmpdirs so programs can be
 
199
   executed on them and setting this SELinux boolean::
 
200
 
 
201
       setsebool httpd_tmp_exec on
 
202
 
 
203
   This bug has information about how python and/or Linux distros might solve
 
204
   this issue permanently and links to bugs which diagnose the root cause.
 
205
   https://bugzilla.redhat.com/show_bug.cgi?id=582009
152
206
 
153
207
Search
154
208
------
165
219
.. toctree::
166
220
   :maxdepth: 2
167
221
 
168
 
   serve-branches
169
 
   start-loggerhead
170
 
   stop-loggerhead
 
222
   loggerhead-serve
171
223
 
172
224
 
173
225
Support