Fix: typos in clone commands were creating empty repos
[gitosis.git] / 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.