bzr-doc team mailing list archive

[Martin Pool <mbp@xxxxxxxxxxxxx>]

2009/12/2 Neil Martinsen-Burrell <nmb@xxxxxxxxxxxx>:
> Folks,
>
> This weekend I started work on a system administrator's guide, inspired by a
> couple of questions on IRC, the emacs/savannah situation and my own
> experience installing Launchpad.  As Bazaar is gaining much greater
> acceptance and being more widely adopted, more administrators will be tasked
> with installing and maintaining Bazaar and its relatives.

That's a great idea, thanks very much for starting this.

> Check out what I have at lp:~nmb/bzr/admin-guide in
> doc/en/admin-guide/index.txt. (Thanks to Ian C. for the skeleton structure.)

For those following along, you can also read it in
<http://bazaar.launchpad.net/~nmb/bzr/admin-guide/annotate/head%3A/doc/en/admin-guide/index.txt>

I have only some small tweaks; most of it looks very good.

-- 
Martin <http://launchpad.net/~mbp/>


> ==========================
> Bazaar Administrator Guide
> ==========================
>
> Note: this is a work in progress!
>
> .. contents:: Table of contents
>    :depth: 3
>
> Introduction
> ============
>
> Welcome to the Bazaar Version Control System's guide for system
> administrators.  Bazaar is a flexible system that provides many possible
> options for serving projects, in ways that will hopefully meet your needs.  If
> you have requirements that are not met by the current state of the Bazaar
> ecosystem, please let us know at bazaar@xxxxxxxxxxxxxxxxxxx on on Launchpad at
> https://launchpad.net/bzr.

'or on Launchad', and I'd point them to
<https://answers.launchpad.net/bzr> and put it in angle brackets so that
the punctuation doesn't get into the url.

> What you need to run a Bazaar server
> ------------------------------------
>
> Where possible, we will discuss both Unix (including Linux) and Windows server
> environments.  For the purposes of this document, we will consider Mac OS X as
> a type of Unix.
>
> In general, Bazaar requires only Python_ 2.4 or greater and the cElementTree_
> package (included in Python 2.5 and later) to run.  If you would *optionally*
> like to be able to access branches using SFTP, you need `paramiko and
> pycrypto`_.
>
> .. _Python: http://www.python.org/
> .. _cElementTree: http://effbot.org/zone/element-index.htm
> .. _paramiko and pycrypto: http://www.lag.net/paramiko/
>
> For maximum performance, Bazaar can make use of compiled versions of some
> critical components of the code.  Pure Python alternatives exist for all of
> these components, but they may be considerably slower.  To compile these
> extensions, you need a C compiler and the relevant header files from the
> Python package.  On Linux, these may be in a separate package.  Other
> operating systems should have the required headers installed by default.
>
> If you are installing a development version of Bazaar, rather than a released
> version, you will need Pyrex_ to create the C extensions.  The release
> tarballs already have the Pyrex-created C files.
>
> .. _Pyrex: http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/

It's worth making the point here that most people shouldn't need to worry
about compiling or getting those packages: they can get bzr from their os
packaging or (for Ubuntu) from PPAs on Launchpad, or for Windows or Mac
from the download page.  Or if they can't find a binary, they can ask.

> Direct Smart Server Access
> --------------------------
>
> The built-in server that is used by ``bzr+ssh://`` access can also be used as
> a persistent server on a dedicated port.  Bazaar's official port is 4155,
> although the port used can be configured.  Further information on running the
> Bazaar smart server from inetd, or directly from the shell is in the `User's
> Guide <../user-guide/server.html#inetd>`_.  The dedicated Bazaar server does not
> currently perform any authentication, so this server by default provides
> read-only access.  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.

Make it more explicit here that you should basically never use
--allow-writes on a server accessible from the internet, and it's not a
great idea even on an internal network.