Update documentation in preparation of release.
This commit is contained in:
Tommi Virtanen
parent
82f5857759
commit
a45445dca0
3 changed files with 216 additions and 17 deletions
149
README.rst
149
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.
|
||||
|
||||
.. 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.
|
||||
|
||||
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::
|
||||
|
||||
sudo -H -u git gitosis-init <FILENAME.pub
|
||||
# (or just copy-paste the public key when prompted)
|
||||
|
||||
then just ``git clone git@SERVER:gitosis-admin.git``, and you get a
|
||||
repository with SSH keys as ``keys/USER.pub`` and a ``gitosis.conf``
|
||||
where you can configure who has access to what.
|
||||
|
||||
.. warning::
|
||||
|
||||
For now, ``gitosis`` uses the ``HOME`` environment variable to
|
||||
locate where to write its files. If you use ``sudo -u``
|
||||
without ``-H``, ``sudo`` will leave the old value of ``HOME``
|
||||
in place, and this will cause trouble. There will be a
|
||||
workaround for that later on, but for now, always remember to
|
||||
use ``-H`` if you're sudoing to the account.
|
||||
|
||||
You should always edit the configuration file via ``git``. The file
|
||||
symlinked to ``~/.gitosis.conf`` on the server will be overwritten
|
||||
when pushing changes to the ``gitosis-admin.git`` repository.
|
||||
|
||||
Edit the settings as you wish, commit and push. That's pretty much it!
|
||||
Once you push, ``gitosis`` will immediately make your changes take
|
||||
effect on the server.
|
||||
|
||||
|
||||
Managing it
|
||||
===========
|
||||
|
||||
To add new users:
|
||||
|
||||
- add a ``keys/USER.pub`` file
|
||||
- authorize them to read/write repositories as needed (or just
|
||||
authorize the group ``@all``)
|
||||
|
||||
To create new repositories, just authorize writing to them and
|
||||
push. It's that simple! For example: let's assume your username is
|
||||
``jdoe`` and you want to create a repository ``myproject``.
|
||||
In your clone of ``gitosis-admin``, edit ``gitosis.conf`` and add::
|
||||
|
||||
[group myteam]
|
||||
members = jdoe
|
||||
writable = myproject
|
||||
|
||||
Commit that change and push. Then create the initial commit and push
|
||||
it::
|
||||
|
||||
mkdir myproject
|
||||
git init
|
||||
git remote add myserver git@MYSERVER:myproject.git
|
||||
# do some work, git add and commit files
|
||||
git push myserver master:master
|
||||
|
||||
That's it. If you now add others to ``members``, they can use that
|
||||
repository too.
|
||||
|
||||
|
||||
Example configuration
|
||||
=====================
|
||||
|
||||
.. include:: example.conf
|
||||
:literal:
|
||||
|
||||
TODO
|
||||
====
|
||||
|
||||
gitosis-lint: check that the user account (e.g. ``git``) looks valid
|
||||
Contact
|
||||
=======
|
||||
|
||||
gitosis-init: create repo with conf+keydir
|
||||
|
||||
gitosis-create-repositories: create repos mentioned in config if
|
||||
they don't exist
|
||||
|
||||
make git hook: update authorized_keys
|
||||
|
||||
make git hook: update config file
|
||||
|
||||
git-daemon-export-ok
|
||||
You can email the author at ``tv@eagain.net``, or hop on
|
||||
``irc.freenode.net`` channel ``#git`` and hope for the best.
|
||||
|
||||
There will be more, keep an eye on http://eagain.net/ and/or the git
|
||||
mailing list.
|
||||
|
|
|
|||
48
TODO.rst
48
TODO.rst
|
|
@ -2,6 +2,15 @@
|
|||
TODO list
|
||||
===========
|
||||
|
||||
- let me have ~git{,/repositories} owned by root:root
|
||||
|
||||
- gitosis-lint: check that the user account (e.g. ``git``) looks valid
|
||||
|
||||
- gitosis-create-repositories: create repos mentioned in config if
|
||||
they don't exist
|
||||
|
||||
- git-daemon-export-ok
|
||||
|
||||
- guard against *.pub files named -foo.pub or foo;bar.pub
|
||||
|
||||
- gitweb doesn't understand mappings, just visible/no,
|
||||
|
|
@ -9,10 +18,49 @@
|
|||
|
||||
- maybe remove the whole mapping feature for good?
|
||||
|
||||
- maybe create symlink trees to make mappings visible in filesystem?
|
||||
|
||||
- use groups somehow to reduce typing for ``gitweb = yes``
|
||||
|
||||
- detect when repo actually ends in ``.git`` for ``projects.list``
|
||||
(otherwise gitweb won't see it)
|
||||
|
||||
- unit test projects.list generation in run-hook
|
||||
|
||||
- ConfigParser does not guarantee ordering, rewrite all unit tests to
|
||||
assume sorted, fix code to sort
|
||||
|
||||
- test with ssh://
|
||||
|
||||
- write description to a file, make REPO.git/description symlink to it
|
||||
if it doesn't exist (thus not overwriting local changes)
|
||||
|
||||
- gitweb knows about cloneurl, handle like description
|
||||
|
||||
- gitweb knows about README.html, figure out how to generate from e.g.
|
||||
README.rst in gitosis.git
|
||||
|
||||
- make gitosis-gitweb output a gitweb.conf file too
|
||||
|
||||
- need to chgrp repositories www-data to make them accessible by gitweb
|
||||
|
||||
- allow using git-cvsserver?
|
||||
|
||||
- move from log.foo("bar" % quux) to log.foo("bar", quux)
|
||||
|
||||
- can't trust "~"::
|
||||
|
||||
[0 tv@musti ~]$ sudo python -c 'import os; print os.path.expanduser("~")'
|
||||
/home/tv
|
||||
[0 tv@musti ~]$ sudo -H python -c 'import os; print os.path.expanduser("~")'
|
||||
/root
|
||||
|
||||
- command line options
|
||||
|
||||
- gitosis init --repositories=
|
||||
- gitosis init --config= (or whatever the option is elsewhere)
|
||||
- gitosis init --home= (for testing)
|
||||
- gitosis init --admin=username[@host]
|
||||
|
||||
- gitosis-run-hook has to be in PATH and PYTHONPATH before you can
|
||||
push to gitosis-admin.git
|
||||
|
|
|
|||
36
example.conf
36
example.conf
|
|
@ -1,20 +1,50 @@
|
|||
# this config file tries to show a bit of everything, most real life
|
||||
# configurations really only need a "group" section with "members" and
|
||||
# "writable"
|
||||
|
||||
[gitosis]
|
||||
repositories = repo
|
||||
## To override the default ~/repositories path
|
||||
# repositories = repositories
|
||||
|
||||
## Allow gitweb to show all known repositories. If you want gitweb,
|
||||
## you need either this or a [repo foo] section for each repository
|
||||
## you want visible in gitweb.
|
||||
gitweb = no
|
||||
|
||||
## Allow git-daemon to publish all known repositories. As with gitweb,
|
||||
## this can be done globally or per-repository.
|
||||
## NOT YET IMPLEMENTED.
|
||||
# daemon-ok = no
|
||||
|
||||
## Logging level, one of DEBUG, INFO, WARNING, ERROR, CRITICAL
|
||||
loglevel = DEBUG
|
||||
|
||||
[group quux]
|
||||
members = jdoe wsmith @anothergroup
|
||||
writable = foo bar baz/thud
|
||||
readonly = xyzzy
|
||||
|
||||
## You can play fancy tricks by making some repositories appear with
|
||||
## different names in different contexts. Not really supported
|
||||
## everywhere (e.g. gitweb) and can be confusing -- experts only.
|
||||
map writable visiblename1 = actualname1
|
||||
map readonly visiblename2 = actualname2
|
||||
|
||||
[repo foo]
|
||||
# description = blah blah
|
||||
## Allow gitweb to show this repository.
|
||||
gitweb = yes
|
||||
|
||||
## Oneline description of the project, mostly for gitweb.
|
||||
## NOT YET IMPLEMENTED.
|
||||
# description = blah blah
|
||||
## Owner of this repository. Used in gitweb list of projects.
|
||||
owner = John Doe
|
||||
|
||||
## Allow git-daemon to publish this repository.
|
||||
## NOT YET IMPLEMENTED.
|
||||
# daemon-ok = no
|
||||
|
||||
# [gitweb]
|
||||
[gitweb]
|
||||
## Where to make gitweb link to as it's "home location".
|
||||
## NOT YET IMPLEMENTED.
|
||||
# homelink = http://example.com/
|
||||
|
|
|
|||
Loading…
Reference in a new issue