From a45445dca0563e95c2538a2f66ce7134fc40a3f0 Mon Sep 17 00:00:00 2001 From: Tommi Virtanen Date: Mon, 3 Sep 2007 17:51:44 -0700 Subject: Update documentation in preparation of release. --- README.rst | 145 ++++++++++++++++++++++++++++++++++++++++++++++++++++++----- TODO.rst | 48 ++++++++++++++++++++ example.conf | 36 +++++++++++++-- 3 files changed, 214 insertions(+), 15 deletions(-) diff --git a/README.rst b/README.rst index 1dc9b75..d39275b 100644 --- a/README.rst +++ b/README.rst @@ -2,24 +2,145 @@ ``gitosis`` -- software for hosting ``git`` repositories ========================================================== -Example configuration: + Manage ``git`` repositories, provide access to them over SSH, + with tight access control and not needing shell accounts. -.. include:: example.conf - :literal: +.. note:: + + Documentation is still lacking, and non-default configurations + (e.g. config file, repositories, installing in a location that + is not in ``PATH``) basically have not been tested at all. + Basic usage should be very reliable -- the project has been + hosting itself for a long time. Any help is welcome. + +``gitosis`` aims to make hosting ``git`` repos easier and safer. It +manages multiple repositories under one user account, using SSH keys +to identify users. End users do not need shell accounts on the server, +they will talk to one shared account that will not let them run +arbitrary commands. + +``gitosis`` is licensed under the GPL, see the file ``COPYING`` for +more information. + +You can get ``gitosis`` via ``git`` by saying:: + + git clone git://eagain.net/gitosis + +And install it via:: + + python setup.py install + +Though you may want to use e.g. ``--prefix=``. For Debian/Ubuntu +users, the source is debianized. + + +Setting up +========== + +First, we will create the user that will own the repositories. This is +usually called ``git``, but any name will work, and you can have more +than one per system if you really want to. The user does not need a +password, but does need a valid shell (otherwise, SSH will refuse to +work). + +I usually store ``git`` repositories in the subtree +``/srv/example.com/git`` (replace ``example.com`` with your own +domain). You may choose another location. Adjust to suit and run:: + + sudo adduser \ + --system \ + --no-create-home \ + --shell /bin/sh \ + --gecos 'git version control' \ + --group \ + --disabled-password \ + --home /srv/example.com/git \ + git + +This command is known to work in Debian and Ubuntu. Your mileage may +vary. + +You will need an SSH public key to continue. If you don't have one, +you need to generate one. See the man page for ``ssh-keygen``, and you +may also be interested in ``ssh-agent``. Create it on your personal +computer, and protect the *private* key well -- that includes not +transferring it over the network. -TODO -==== +Next, we need to set things up for this newly-created user. The +following command will create a ``~/repositories`` that will hold the +``git`` repositories, a ``~/.gitosis.conf`` that will be a symlink to +the actual configuration file, and it will add the SSH public key to +``~/.ssh/authorized_keys`` with a ``command=`` option that restricts +it to running ``gitosis-serve``. Run:: -gitosis-lint: check that the user account (e.g. ``git``) looks valid + sudo -H -u git gitosis-init