README.rst

   1 ==========================================================
   2  ``gitosis`` -- software for hosting ``git`` repositories
   3 ==========================================================
   4
   5         Manage ``git`` repositories, provide access to them over SSH,
   6         with tight access control and not needing shell accounts.
   7
   8 .. note::
   9
  10         Documentation is still lacking, and non-default configurations
  11         (e.g. config file, repositories, installing in a location that
  12         is not in ``PATH``) basically have not been tested at all.
  13         Basic usage should be very reliable -- the project has been
  14         hosting itself for a long time. Any help is welcome.
  15
  16 ``gitosis`` aims to make hosting ``git`` repos easier and safer. It
  17 manages multiple repositories under one user account, using SSH keys
  18 to identify users. End users do not need shell accounts on the server,
  19 they will talk to one shared account that will not let them run
  20 arbitrary commands.
  21
  22 ``gitosis`` is licensed under the GPL, see the file ``COPYING`` for
  23 more information.
  24
  25 You can get ``gitosis`` via ``git`` by saying::
  26
  27     git clone git://eagain.net/gitosis
  28
  29 And install it via::
  30
  31     python setup.py install
  32
  33 Though you may want to use e.g. ``--prefix=``. For Debian/Ubuntu
  34 users, the source is debianized.
  35
  36
  37 Setting up
  38 ==========
  39
  40 First, we will create the user that will own the repositories. This is
  41 usually called ``git``, but any name will work, and you can have more
  42 than one per system if you really want to. The user does not need a
  43 password, but does need a valid shell (otherwise, SSH will refuse to
  44 work). Don't use an existing account unless you know what you're
  45 doing.
  46
  47 I usually store ``git`` repositories in the subtree
  48 ``/srv/example.com/git`` (replace ``example.com`` with your own
  49 domain). You may choose another location. Adjust to suit and run::
  50
  51         sudo adduser \
  52             --system \
  53             --shell /bin/sh \
  54             --gecos 'git version control' \
  55             --group \
  56             --disabled-password \
  57             --home /srv/example.com/git \
  58             git
  59
  60 This command is known to work in Debian and Ubuntu. Your mileage may
  61 vary.
  62
  63 You will need an SSH public key to continue. If you don't have one,
  64 you need to generate one. See the man page for ``ssh-keygen``, and you
  65 may also be interested in ``ssh-agent``. Create it on your personal
  66 computer, and protect the *private* key well -- that includes not
  67 transferring it over the network.
  68
  69 Next, we need to set things up for this newly-created user. The
  70 following command will create a ``~/repositories`` that will hold the
  71 ``git`` repositories, a ``~/.gitosis.conf`` that will be a symlink to
  72 the actual configuration file, and it will add the SSH public key to
  73 ``~/.ssh/authorized_keys`` with a ``command=`` option that restricts
  74 it to running ``gitosis-serve``. Run::
  75
  76         sudo -H -u git gitosis-init <FILENAME.pub
  77         # (or just copy-paste the public key when prompted)
  78
  79 then just ``git clone git@SERVER:gitosis-admin.git``, and you get a
  80 repository with SSH keys as ``keys/USER.pub`` and a ``gitosis.conf``
  81 where you can configure who has access to what.
  82
  83 .. warning::
  84
  85         For now, ``gitosis`` uses the ``HOME`` environment variable to
  86         locate where to write its files. If you use ``sudo -u``
  87         without ``-H``, ``sudo`` will leave the old value of ``HOME``
  88         in place, and this will cause trouble. There will be a
  89         workaround for that later on, but for now, always remember to
  90         use ``-H`` if you're sudoing to the account.
  91
  92 You should always edit the configuration file via ``git``. The file
  93 symlinked to ``~/.gitosis.conf`` on the server will be overwritten
  94 when pushing changes to the ``gitosis-admin.git`` repository.
  95
  96 Edit the settings as you wish, commit and push. That's pretty much it!
  97 Once you push, ``gitosis`` will immediately make your changes take
  98 effect on the server.
  99
 100
 101 Managing it
 102 ===========
 103
 104 To add new users:
 105
 106 - add a ``keys/USER.pub`` file
 107 - authorize them to read/write repositories as needed (or just
 108   authorize the group ``@all``)
 109
 110 To create new repositories, just authorize writing to them and
 111 push. It's that simple! For example: let's assume your username is
 112 ``jdoe`` and you want to create a repository ``myproject``.
 113 In your clone of ``gitosis-admin``, edit ``gitosis.conf`` and add::
 114
 115         [group myteam]
 116         members = jdoe
 117         writable = myproject
 118
 119 Commit that change and push. Then create the initial commit and push
 120 it::
 121
 122         mkdir myproject
 123         cd mypyroject
 124         git init
 125         git remote add myserver git@MYSERVER:myproject.git
 126         # do some work, git add and commit files
 127         git push myserver master:refs/heads/master
 128
 129 That's it. If you now add others to ``members``, they can use that
 130 repository too.
 131
 132
 133 Example configuration
 134 =====================
 135
 136 .. include:: example.conf
 137    :literal:
 138
 139
 140 Using git-daemon
 141 ================
 142
 143 Anonymous read-only access to ``git`` repositories is provided by
 144 ``git-daemon``, which is distributed as part of ``git``. But
 145 ``gitosis`` will still help you manage it: setting ``daemon = yes`` in
 146 your ``gitosis.conf``, either globally in ``[gitosis]`` or
 147 per-repository under ``[repo REPOSITORYNAME]``, makes ``gitosis``
 148 create the ``git-daemon-export-ok`` files in those repository, thus
 149 telling ``git-daemon`` that publishing those repositories is ok.
 150
 151 To actually run ``git-daemon`` in Ubuntu, put this in
 152 ``/etc/event.d/local-git-daemon``:
 153
 154 .. include:: etc-event.d-local-git-daemon
 155    :literal:
 156
 157 For other operating systems, use a similar invocation in an ``init.d``
 158 script, ``/etc/inittab``, ``inetd.conf``, ``runit``, or something like
 159 that (good luck).
 160
 161 Note that this short snippet is not a substitute for reading and
 162 understanding the relevant documentation.
 163
 164
 165 Using gitweb
 166 ============
 167
 168 ``gitweb`` is a CGI script that lets one browse ``git`` repositories
 169 on the web. It is most commonly used anonymously, but you could also
 170 require authentication in your web server, before letting people use
 171 it. ``gitosis`` can help here by generating a list of projects that
 172 are publicly visible. Simply add a section ``[repo REPOSITORYNAME]``
 173 to your ``gitosis.conf``, and allow publishing with ``gitweb = yes``
 174 (or globally under ``[gitosis]``). You should also set ``description``
 175 and ``owner`` for each repository.
 176
 177 Here's a LightTPD_ config file snippet showing how to run ``gitweb``
 178 as a CGI:
 179
 180 .. _LightTPD: http://www.lighttpd.net/
 181
 182 .. include:: lighttpd-gitweb.conf
 183    :literal:
 184
 185 And a simple ``gitweb.conf`` file:
 186
 187 .. include:: gitweb.conf
 188    :literal:
 189
 190 Note that this short snippet is not a substitute for reading and
 191 understanding the relevant documentation.
 192
 193
 194
 195 Contact
 196 =======
 197
 198 You can email the author at ``tv@eagain.net``, or hop on
 199 ``irc.freenode.net`` channel ``#git`` and hope for the best.
 200
 201 There will be more, keep an eye on http://eagain.net/ and/or the git
 202 mailing list.