Bazaar

Merge lp://staging/~nmb/bzr/admin-guide-intro into lp://staging/bzr

  1. admin-guide-intro
  2. Merge into bzr.dev
Proposed by Neil Martinsen-Burrell
Status: Merged
Approved by: Vincent Ladeuil
Approved revision: not available
Merged at revision: not available
Proposed branch: lp://staging/~nmb/bzr/admin-guide-intro
Merge into: lp://staging/bzr
Prerequisite: lp://staging/~nmb/bzr/admin-guide-structure
Diff against target: 232 lines (+181/-1)
4 files modified
doc/en/admin-guide/introduction.txt (+45/-1)
doc/en/admin-guide/other-setups.txt (+47/-0)
doc/en/admin-guide/simple-setups.txt (+88/-0)
doc/en/conf.py (+1/-0)
To merge this branch: bzr merge lp://staging/~nmb/bzr/admin-guide-intro
Reviewer Review Type Date Requested Status
Vincent Ladeuil Approve
John A Meinel Needs Fixing
Review via email: mp+15760@code.staging.launchpad.net
To post a comment you must log in.
Revision history for this message
Neil Martinsen-Burrell (nmb) wrote :

This builds on the admin guide structure to add an introduction to Bazaar and descriptions of the basic ways to set things up.

Revision history for this message
John A Meinel (jameinel) wrote :

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Neil Martinsen-Burrell wrote:
> Neil Martinsen-Burrell has proposed merging lp:~nmb/bzr/admin-guide-intro into lp:bzr with lp:~nmb/bzr/admin-guide-structure as a prerequisite.
>
> Requested reviews:
> bzr-core (bzr-core)
>
>
> This builds on the admin guide structure to add an introduction to Bazaar and descriptions of the basic ways to set things up.
>

+administrators. Bazaar is a flexible system that provides many possible
+options for serving projects, in ways that will hopefully meet your
needs. If
                             ^- I don't think you need this comma

+ecosystem, please let us know at <email address hidden> on on
Launchpad at

"on on" should probably be "or on".

> +Note that SFTP access is often available whenever there is SSH access, but it
> +may be a good choice when Bazaar cannot be installed on the server to allow
> +``bzr+ssh://`` access. Dumb servers are slower by their very nature than the
> +native protocol, but they can be a good choice in situations where the
> +software and protocols that can be used on the server or the network is
> +limited.
> +

^- I think the first sentence is actually an "and". A 'but' would be if
you recommend using bzr+ssh if it is at all possible. Something like:

If it is possible to install bzr on the server, then it is generally
recommended to use ``bzr+ssh``. If it is not feasible to install bzr,
but you do have SSH access, then often you can fall back to SFTP access.

Just a thought.

It can be run with the ``--allow-writes`` option, but if
+the user that the server is running as has write access to the branch
+directories on the filesystem, then this will allow anyone with access
to port
+4155 on the server to make changes to the branches stored there.

^- This sentence seems a bit clumsy. I don't have any great suggestions,
though.

+If developers have home directories on the server, they can use ``/~/`` in
+URLs to refer to their home directory. They can also use
``/~username/`` to
+refer to the home directory of user ``username``. For example, if
there are two
+developers ``alice`` and ``bob``, then Bob could use::
+
+ $ bzr log bzr+ssh://server.example.com/~/fix-1023
+

^- We probably should add a footnote that you need the bzr server to be
at least 2.1.0b1 or newer to support /~/ for bzr+ssh urls.

 review: needs_fixing

I also didn't review any of this for layout, just content. I'm assuming
someone else felt that the outline was a reasonable layout for presentation.
John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAksdZ7YACgkQJdeBCYSNAAPKqwCdFG+HIbtLY2erNiqWEhKF7k+K
ck0AoL9UlR/1d0gsCzizTcCmEvye5nJj
=FUQQ
-----END PGP SIGNATURE-----

review: Needs Fixing
Revision history for this message
Neil Martinsen-Burrell (nmb) wrote :

Fixed in the branch. Thanks for the review.

Revision history for this message
Vincent Ladeuil (vila) wrote :

Looks good to me, the layout sounds good too and has not been significantly modified by this patch.

Documentation is better tested by readers, so I'll land :)

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'doc/en/admin-guide/introduction.txt'
2--- doc/en/admin-guide/introduction.txt 2009-12-07 21:53:13 +0000
3+++ doc/en/admin-guide/introduction.txt 2009-12-07 21:53:13 +0000
4@@ -1,11 +1,55 @@
5 Introduction
6 ============
7
8+Welcome to the Bazaar Version Control System's guide for system
9+administrators. Bazaar is a flexible system that provides many possible
10+options for serving projects in ways that will hopefully meet your needs. If
11+you have requirements that are not met by the current state of the Bazaar
12+ecosystem, please let us know at bazaar@lists.canonical.com or on Launchpad at
13+https://launchpad.net/bzr.
14+
15 Scope of this guide
16 -------------------
17
18+In this guide, we will discuss various techniques for making Bazaar projects
19+available, migrating from other Version Control Systems, browsing code over
20+the Web and combining Bazaar with other tools. In many of these categories,
21+multiple options exist and we will try to explains the costs and benefits of
22+the various options.
23+
24+The intended audience for this guide is the individuals who administer the
25+computers that will do the serving. Much of the configuration that we will
26+discuss requires administrator privileges and we will not necessarily indicate
27+every point that those privileges are needed. That said, reading this guide
28+can also be very helpful for those who are interested in communicating to the
29+system administrators about the requirements for making full use of Bazaar.
30+
31 What you need to run a Bazaar server
32 ------------------------------------
33
34-
35+Where possible, we will discuss both Unix (including Linux) and Windows server
36+environments. For the purposes of this document, we will consider Mac OS X as
37+a type of Unix.
38+
39+In general, Bazaar requires only Python_ 2.4 or greater and the cElementTree_
40+package (included in Python 2.5 and later) to run. If you would *optionally*
41+like to be able to access branches using SFTP, you need `paramiko and
42+pycrypto`_.
43+
44+.. _Python: http://www.python.org/
45+.. _cElementTree: http://effbot.org/zone/element-index.htm
46+.. _paramiko and pycrypto: http://www.lag.net/paramiko/
47+
48+For maximum performance, Bazaar can make use of compiled versions of some
49+critical components of the code. Pure Python alternatives exist for all of
50+these components, but they may be considerably slower. To compile these
51+extensions, you need a C compiler and the relevant header files from the
52+Python package. On Linux, these may be in a separate package. Other
53+operating systems should have the required headers installed by default.
54+
55+If you are installing a development version of Bazaar, rather than a released
56+version, you will need Pyrex_ to create the C extensions. The release
57+tarballs already have the Pyrex-created C files.
58+
59+.. _Pyrex: http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/
60
61
62=== modified file 'doc/en/admin-guide/other-setups.txt'
63--- doc/en/admin-guide/other-setups.txt 2009-12-07 21:53:13 +0000
64+++ doc/en/admin-guide/other-setups.txt 2009-12-07 21:53:13 +0000
65@@ -4,10 +4,57 @@
66 Dumb servers
67 ------------
68
69+Bazaar can also serve branches over protocols that know nothing about Bazaar's
70+specific needs. These are called "dumb servers" to distinguish them from
71+Bazaar's native protocol. Currently HTTP, FTP, SFTP and HTTP+WebDAV can be
72+used to read branches remotely. FTP, SFTP and HTTP+WebDAV can be used for
73+writing as well. To use any of these protocols, it is just necessary to
74+provide access to the server's filesystem under ``/srv/bzr``.
75+
76+For example, for Apache to provide read-only access to the branches
77+in ``/srv/bzr`` the configuration may look like this::
78+
79+ Alias /code /srv/bzr
80+ <Directory /srv/bzr>
81+ Options Indexes
82+ # ...
83+ </Directory>
84+
85+and users could use the URL ``http://server.example.com/code/projectx/trunk``
86+to refer to the trunk branch.
87+
88+Note that SFTP access is often available whenever there is SSH access and it
89+may be a good choice when Bazaar cannot be installed on the server to allow
90+``bzr+ssh://`` access. Dumb servers are slower by their very nature than the
91+native protocol, but they can be a good choice in situations where the
92+software and protocols that can be used on the server or the network is
93+limited.
94+
95 Smart server over HTTP(S)
96 -------------------------
97
98+Bazaar can use its native protocol with HTTP requests. Since HTTP is a network
99+protocol that is available on many networks, this can be a good option where
100+SSH access is not possible. Another benefit of this setup is that all of the
101+authentication and access control methods available to the HTTP server (basic,
102+LDAP, ActiveDirectory, etc.) are then available to control access to Bazaar
103+branches. More information about setting up this type of access using Apache
104+and FastCGI or mod_python or WSGI is in the `smart server section of the User's
105+Guide <../user-guide/http_smart_server.html>`_.
106+
107 Direct Smart Server Access
108 --------------------------
109
110+The built-in server that is used by ``bzr+ssh://`` access can also be used as a
111+persistent server on a dedicated port. Bazaar's official port is 4155,
112+although the port used can be configured. Further information on running the
113+Bazaar smart server from inetd, or directly from the shell is in the `User's
114+Guide <../user-guide/server.html#inetd>`_. The dedicated Bazaar server does
115+not currently perform any authentication, so this server by default provides
116+read-only access. It can be run with the ``--allow-writes`` option, but the
117+smart server does not do any additional access control so this may allow
118+undesired people to make changes to branches. (Which of course can be
119+reverted.) If the user that runs the server has write access to the branches
120+on the filesystem, then anyone with access to port 4155 on the server can make
121+changes to the branches stored there.
122
123
124=== modified file 'doc/en/admin-guide/simple-setups.txt'
125--- doc/en/admin-guide/simple-setups.txt 2009-12-07 21:53:13 +0000
126+++ doc/en/admin-guide/simple-setups.txt 2009-12-07 21:53:13 +0000
127@@ -1,5 +1,93 @@
128 Simple Setups
129 =============
130
131+Consider the following simple scenario where we will be serving Bazaar branches
132+that live on a single server. Those branches are in the subdirectories of
133+``/srv/bzr`` (or ``C:\\bzr``) and they will all be related to a single project
134+called "ProjectX". ProjectX will have a trunk branch and at least one feature
135+branch. As we get further, we will consider other scenarios, but this will be
136+a sufficiently motivating example.
137+
138 Smart server
139 ------------
140+
141+The simplest possible setup for providing outside access to the branches on
142+the server uses Bazaar's built-in smart server tunneled over SSH_ so
143+that people who can access your server using SSH can have read and write
144+access to branches on the server. This setup uses the authentication
145+mechanisms of SSH including private keys, and the access control mechanisms of
146+the server's operating system. In particular, using groups on the server, it
147+is possible to provide different access privileges to different groups of
148+developers.
149+
150+.. _SSH: http://www.openssh.org/
151+
152+Setup
153+~~~~~
154+
155+There is no setup required for this on the server, apart from having Bazaar
156+installed and SSH access available to your developers. Using SSH
157+configuration options it is possible to restrict developers from using
158+anything *but* Bazaar on the server via SSH, and to limit what part of the
159+file system they can access.
160+
161+Client
162+~~~~~~
163+
164+Clients can access the branches using URLs with the ``bzr+ssh://`` prefix. For
165+example, to get a local copy of the ProjectX trunk, a developer could do::
166+
167+ $ bzr branch bzr+ssh://server.example.com/srv/bzr/projectx/trunk projectx
168+
169+If the developers have write access to the ``/srv/bzr/projectx`` directory, then
170+they can create new branches themselves using::
171+
172+ $ bzr branch bzr+ssh://server.example.com/srv/bzr/projectx/trunk \
173+ bzr+ssh://server.example.com/srv/bzr/projectx/feature-gui
174+
175+Of course, if this isn't desired, then developers should not have write access
176+to the ``/srv/bzr/projectx`` directory.
177+
178+Further Configuration
179+~~~~~~~~~~~~~~~~~~~~~
180+
181+For a project with multiple branches that are all related, it is best to use a
182+shared repository to hold all of the branches. To set this up, do::
183+
184+ $ cd /srv/bzr
185+ $ bzr init-repo --no-trees projectx
186+
187+The ``--no-trees`` option saves space by not creating a copy of the working
188+files on the server's filesystem. Then, any branch created under
189+``/srv/bzr/projectx`` (see `Migration <migration.html>`_ for some ways to do
190+this) will share storage space, which is particularly helpful for branches that
191+have many revisions in common, such as a project trunk and its feature
192+branches.
193+
194+If Bazaar is not installed on the user's path or not specified in the SSH
195+configuration, then a path can be specified from the client with the
196+``BZR_REMOTE_PATH`` environment variable. For example, if the Bazaar executable
197+is installed in ``/usr/local/bzr-2.0/bin/bzr``, then a developer could use::
198+
199+ $ BZR_REMOTE_PATH=/usr/local/bzr-2.0/bin/bzr bzr info \
200+ bzr+ssh://server.example.com/srv/bzr/proectx/trunk
201+
202+to get information about the trunk branch. The remote path can also be
203+specified in Bazaar's configuration files for a particular location. See
204+``bzr help configuration`` for more details.
205+
206+If developers have home directories on the server, they can use ``/~/`` in
207+URLs to refer to their home directory. They can also use ``/~username/`` to
208+refer to the home directory of user ``username``. For example, if there are two
209+developers ``alice`` and ``bob``, then Bob could use::
210+
211+ $ bzr log bzr+ssh://server.example.com/~/fix-1023
212+
213+to refer to one of his bug fix branches and::
214+
215+ $ bzr log bzr+ssh://server.example.com/~alice/fix-2047
216+
217+to refer to one of Alice's branches. [#]_
218+
219+.. [#] The version of Bazaar installed on the server must be at least 2.1.0b1
220+ or newer to support ``/~/`` in bzr+ssh URLs.
221
222=== modified file 'doc/en/conf.py'
223--- doc/en/conf.py 2009-12-07 21:53:13 +0000
224+++ doc/en/conf.py 2009-12-07 21:53:13 +0000
225@@ -81,6 +81,7 @@
226 'release-notes/NEWS',
227 'user-reference/bzr_man',
228 'user-guide/index-plain',
229+ 'admin-guide/index-plain',
230 # Miscellaneous
231 'user-reference/readme',
232 ]