Rev 4910: (nmb) Add intro and setups sections to admin-guide in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Fri Dec 18 15:37:09 GMT 2009
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 4910 [merge]
revision-id: pqm at pqm.ubuntu.com-20091218153705-pnr33hwkmvy1b33i
parent: pqm at pqm.ubuntu.com-20091218105213-3amdsy9oq337u387
parent: nmb at wartburg.edu-20091207215101-lv1fyi2blzer4h5j
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Fri 2009-12-18 15:37:05 +0000
message:
(nmb) Add intro and setups sections to admin-guide
modified:
doc/en/admin-guide/introduction.txt introduction.txt-20091205144603-lgpl0e0z6lzk2rdw-7
doc/en/admin-guide/other-setups.txt othersetups.txt-20091205144603-lgpl0e0z6lzk2rdw-9
doc/en/admin-guide/simple-setups.txt simplesetups.txt-20091205144603-lgpl0e0z6lzk2rdw-11
doc/en/conf.py conf.py-20090722133816-63ik5s6s5gsnz7zy-12
=== modified file 'doc/en/admin-guide/introduction.txt'
--- a/doc/en/admin-guide/introduction.txt 2009-12-07 18:12:21 +0000
+++ b/doc/en/admin-guide/introduction.txt 2009-12-07 21:51:01 +0000
@@ -1,11 +1,55 @@
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 at lists.canonical.com or on Launchpad at
+https://launchpad.net/bzr.
+
Scope of this guide
-------------------
+In this guide, we will discuss various techniques for making Bazaar projects
+available, migrating from other Version Control Systems, browsing code over
+the Web and combining Bazaar with other tools. In many of these categories,
+multiple options exist and we will try to explains the costs and benefits of
+the various options.
+
+The intended audience for this guide is the individuals who administer the
+computers that will do the serving. Much of the configuration that we will
+discuss requires administrator privileges and we will not necessarily indicate
+every point that those privileges are needed. That said, reading this guide
+can also be very helpful for those who are interested in communicating to the
+system administrators about the requirements for making full use of Bazaar.
+
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/
=== modified file 'doc/en/admin-guide/other-setups.txt'
--- a/doc/en/admin-guide/other-setups.txt 2009-12-07 18:12:21 +0000
+++ b/doc/en/admin-guide/other-setups.txt 2009-12-07 21:51:01 +0000
@@ -4,10 +4,57 @@
Dumb servers
------------
+Bazaar can also serve branches over protocols that know nothing about Bazaar's
+specific needs. These are called "dumb servers" to distinguish them from
+Bazaar's native protocol. Currently HTTP, FTP, SFTP and HTTP+WebDAV can be
+used to read branches remotely. FTP, SFTP and HTTP+WebDAV can be used for
+writing as well. To use any of these protocols, it is just necessary to
+provide access to the server's filesystem under ``/srv/bzr``.
+
+For example, for Apache to provide read-only access to the branches
+in ``/srv/bzr`` the configuration may look like this::
+
+ Alias /code /srv/bzr
+ <Directory /srv/bzr>
+ Options Indexes
+ # ...
+ </Directory>
+
+and users could use the URL ``http://server.example.com/code/projectx/trunk``
+to refer to the trunk branch.
+
+Note that SFTP access is often available whenever there is SSH access and 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.
+
Smart server over HTTP(S)
-------------------------
+Bazaar can use its native protocol with HTTP requests. Since HTTP is a network
+protocol that is available on many networks, this can be a good option where
+SSH access is not possible. Another benefit of this setup is that all of the
+authentication and access control methods available to the HTTP server (basic,
+LDAP, ActiveDirectory, etc.) are then available to control access to Bazaar
+branches. More information about setting up this type of access using Apache
+and FastCGI or mod_python or WSGI is in the `smart server section of the User's
+Guide <../user-guide/http_smart_server.html>`_.
+
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 the
+smart server does not do any additional access control so this may allow
+undesired people to make changes to branches. (Which of course can be
+reverted.) If the user that runs the server has write access to the branches
+on the filesystem, then anyone with access to port 4155 on the server can make
+changes to the branches stored there.
=== modified file 'doc/en/admin-guide/simple-setups.txt'
--- a/doc/en/admin-guide/simple-setups.txt 2009-12-07 18:12:21 +0000
+++ b/doc/en/admin-guide/simple-setups.txt 2009-12-07 21:51:01 +0000
@@ -1,5 +1,93 @@
Simple Setups
=============
+Consider the following simple scenario where we will be serving Bazaar branches
+that live on a single server. Those branches are in the subdirectories of
+``/srv/bzr`` (or ``C:\\bzr``) and they will all be related to a single project
+called "ProjectX". ProjectX will have a trunk branch and at least one feature
+branch. As we get further, we will consider other scenarios, but this will be
+a sufficiently motivating example.
+
Smart server
------------
+
+The simplest possible setup for providing outside access to the branches on
+the server uses Bazaar's built-in smart server tunneled over SSH_ so
+that people who can access your server using SSH can have read and write
+access to branches on the server. This setup uses the authentication
+mechanisms of SSH including private keys, and the access control mechanisms of
+the server's operating system. In particular, using groups on the server, it
+is possible to provide different access privileges to different groups of
+developers.
+
+.. _SSH: http://www.openssh.org/
+
+Setup
+~~~~~
+
+There is no setup required for this on the server, apart from having Bazaar
+installed and SSH access available to your developers. Using SSH
+configuration options it is possible to restrict developers from using
+anything *but* Bazaar on the server via SSH, and to limit what part of the
+file system they can access.
+
+Client
+~~~~~~
+
+Clients can access the branches using URLs with the ``bzr+ssh://`` prefix. For
+example, to get a local copy of the ProjectX trunk, a developer could do::
+
+ $ bzr branch bzr+ssh://server.example.com/srv/bzr/projectx/trunk projectx
+
+If the developers have write access to the ``/srv/bzr/projectx`` directory, then
+they can create new branches themselves using::
+
+ $ bzr branch bzr+ssh://server.example.com/srv/bzr/projectx/trunk \
+ bzr+ssh://server.example.com/srv/bzr/projectx/feature-gui
+
+Of course, if this isn't desired, then developers should not have write access
+to the ``/srv/bzr/projectx`` directory.
+
+Further Configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+For a project with multiple branches that are all related, it is best to use a
+shared repository to hold all of the branches. To set this up, do::
+
+ $ cd /srv/bzr
+ $ bzr init-repo --no-trees projectx
+
+The ``--no-trees`` option saves space by not creating a copy of the working
+files on the server's filesystem. Then, any branch created under
+``/srv/bzr/projectx`` (see `Migration <migration.html>`_ for some ways to do
+this) will share storage space, which is particularly helpful for branches that
+have many revisions in common, such as a project trunk and its feature
+branches.
+
+If Bazaar is not installed on the user's path or not specified in the SSH
+configuration, then a path can be specified from the client with the
+``BZR_REMOTE_PATH`` environment variable. For example, if the Bazaar executable
+is installed in ``/usr/local/bzr-2.0/bin/bzr``, then a developer could use::
+
+ $ BZR_REMOTE_PATH=/usr/local/bzr-2.0/bin/bzr bzr info \
+ bzr+ssh://server.example.com/srv/bzr/proectx/trunk
+
+to get information about the trunk branch. The remote path can also be
+specified in Bazaar's configuration files for a particular location. See
+``bzr help configuration`` for more details.
+
+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
+
+to refer to one of his bug fix branches and::
+
+ $ bzr log bzr+ssh://server.example.com/~alice/fix-2047
+
+to refer to one of Alice's branches. [#]_
+
+.. [#] The version of Bazaar installed on the server must be at least 2.1.0b1
+ or newer to support ``/~/`` in bzr+ssh URLs.
=== modified file 'doc/en/conf.py'
--- a/doc/en/conf.py 2009-12-07 18:12:21 +0000
+++ b/doc/en/conf.py 2009-12-07 21:51:01 +0000
@@ -81,6 +81,7 @@
'release-notes/NEWS',
'user-reference/bzr_man',
'user-guide/index-plain',
+ 'admin-guide/index-plain',
# Miscellaneous
'user-reference/readme',
]
More information about the bazaar-commits
mailing list