← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/admin-guide/simple-setups.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2009-12-18 15:37:05 UTC
  • mfrom: (4871.6.2 admin-guide-submit)
  • Revision ID: pqm@pqm.ubuntu.com-20091218153705-pnr33hwkmvy1b33i
(nmb) Add intro and setups sections to admin-guide

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/admin-guide/simple-setups.txt
1
1
Simple Setups
2
2
=============
3
3
 
 
4
Consider the following simple scenario where we will be serving Bazaar branches
 
5
that live on a single server.  Those branches are in the subdirectories of
 
6
``/srv/bzr`` (or ``C:\\bzr``) and they will all be related to a single project
 
7
called "ProjectX".  ProjectX will have a trunk branch and at least one feature
 
8
branch.  As we get further, we will consider other scenarios, but this will be
 
9
a sufficiently motivating example.
 
10
 
4
11
Smart server
5
12
------------
 
13
 
 
14
The simplest possible setup for providing outside access to the branches on
 
15
the server uses Bazaar's built-in smart server tunneled over SSH_ so
 
16
that people who can access your server using SSH can have read and write
 
17
access to branches on the server.  This setup uses the authentication
 
18
mechanisms of SSH including private keys, and the access control mechanisms of
 
19
the server's operating system.  In particular, using groups on the server, it
 
20
is possible to provide different access privileges to different groups of
 
21
developers.
 
22
 
 
23
.. _SSH: http://www.openssh.org/
 
24
 
 
25
Setup
 
26
~~~~~
 
27
 
 
28
There is no setup required for this on the server, apart from having Bazaar
 
29
installed and SSH access available to your developers.  Using SSH
 
30
configuration options it is possible to restrict developers from using
 
31
anything *but* Bazaar on the server via SSH, and to limit what part of the
 
32
file system they can access.
 
33
 
 
34
Client
 
35
~~~~~~
 
36
 
 
37
Clients can access the branches using URLs with the ``bzr+ssh://`` prefix.  For
 
38
example, to get a local copy of the ProjectX trunk, a developer could do::
 
39
 
 
40
  $ bzr branch bzr+ssh://server.example.com/srv/bzr/projectx/trunk projectx
 
41
 
 
42
If the developers have write access to the ``/srv/bzr/projectx`` directory, then
 
43
they can create new branches themselves using::
 
44
  
 
45
  $ bzr branch bzr+ssh://server.example.com/srv/bzr/projectx/trunk \
 
46
  bzr+ssh://server.example.com/srv/bzr/projectx/feature-gui
 
47
 
 
48
Of course, if this isn't desired, then developers should not have write access
 
49
to the ``/srv/bzr/projectx`` directory.
 
50
 
 
51
Further Configuration
 
52
~~~~~~~~~~~~~~~~~~~~~
 
53
 
 
54
For a project with multiple branches that are all related, it is best to use a
 
55
shared repository to hold all of the branches.  To set this up, do::
 
56
 
 
57
  $ cd /srv/bzr
 
58
  $ bzr init-repo --no-trees projectx
 
59
 
 
60
The ``--no-trees`` option saves space by not creating a copy of the working
 
61
files on the server's filesystem.  Then, any branch created under
 
62
``/srv/bzr/projectx`` (see `Migration <migration.html>`_ for some ways to do
 
63
this) will share storage space, which is particularly helpful for branches that
 
64
have many revisions in common, such as a project trunk and its feature
 
65
branches.
 
66
 
 
67
If Bazaar is not installed on the user's path or not specified in the SSH
 
68
configuration, then a path can be specified from the client with the
 
69
``BZR_REMOTE_PATH`` environment variable.  For example, if the Bazaar executable
 
70
is installed in ``/usr/local/bzr-2.0/bin/bzr``, then a developer could use::
 
71
 
 
72
  $ BZR_REMOTE_PATH=/usr/local/bzr-2.0/bin/bzr bzr info \
 
73
  bzr+ssh://server.example.com/srv/bzr/proectx/trunk
 
74
 
 
75
to get information about the trunk branch.  The remote path can also be
 
76
specified in Bazaar's configuration files for a particular location.  See
 
77
``bzr help configuration`` for more details.
 
78
 
 
79
If developers have home directories on the server, they can use ``/~/`` in
 
80
URLs to refer to their home directory.  They can also use ``/~username/`` to
 
81
refer to the home directory of user ``username``.  For example, if there are two
 
82
developers ``alice`` and ``bob``, then Bob could use::
 
83
 
 
84
  $ bzr log bzr+ssh://server.example.com/~/fix-1023
 
85
 
 
86
to refer to one of his bug fix branches and::
 
87
 
 
88
  $ bzr log bzr+ssh://server.example.com/~alice/fix-2047
 
89
  
 
90
to refer to one of Alice's branches. [#]_
 
91
 
 
92
.. [#] The version of Bazaar installed on the server must be at least 2.1.0b1 
 
93
       or newer to support ``/~/`` in bzr+ssh URLs.