apache.conf.in: add note about MaxProcesses option
[girocco.git] / README
Commit [+]AuthorDateLineData
796f63d2
SN
Stefan Naewe2009-11-06 16:45:14 +01001Girocco
2=======
3Petr Baudis <pasky@ucw.cz>
4
5
cdfe0ab3 Petr Baudis2008-07-23 19:08:13 +02006This is the duct tape that ties repo.or.cz together, codenamed Girocco.
79ebd4ab
PB
Petr Baudis2009-11-03 02:54:49 +01007It is packaged here for easy re-deployment - just follow the INSTALL file
8for brief deployment instructions; you may hit some obstacle here or there,
9though, so be prepared.
f7a7991f Petr Baudis2006-10-06 21:00:04 +020010
922ca021
KM
Kyle J. McKay2013-06-15 13:38:26 -070011Girocco is an Open Source project covered by the GNU General Public License.
12See the file COPYING for further details.
13
f7a7991f Petr Baudis2006-10-06 21:00:04 +020014
79ebd4ab
PB
Petr Baudis2009-11-03 02:54:49 +010015About Girocco
16-------------
92f1b95a Petr Baudis2006-10-07 22:43:29 +020017
79ebd4ab
PB
Petr Baudis2009-11-03 02:54:49 +010018Girocco is a Git hosting solution, designed to allow users easily create and
19access repositories over the web, either in mirror mode (Girocco maintains a
20clone of the given repository locally) or in push mode (Girocco maintains
21a secure chroot with ssh inside for push-only access). A well-known feature
22is forking support, where users can easily publish modifications of projects
23they don't own, and mob user support, allowing a sandbox within a project
24where anonymous pushing is allowed.
92f1b95a Petr Baudis2006-10-07 22:43:29 +020025
79ebd4ab
PB
Petr Baudis2009-11-03 02:54:49 +010026Typical scenarios are:
27
28* Full-blown hosting site with both mirroring and ssh push access
29 (like repo.or.cz)
30* Internal Git hosting site with no mirroring, but users being able to easily
31 set up projects to push to (corporate deployment with no networked homes)
32* Internal Git hosting site with no pushing, instead mirroring specified
33 projects from people's home directories for others to easily access and fork
34 (corporate deployment especially suitable for NFS homes and UNIX-savvy
35 users)
36
37Girocco itself comprises of a terse documentation, somewhat customized gitweb
38instance, CGI scripts for user and project management, and several management
39scripts for the hosting site maintenance.
40
41
42Girocco vs...
43-------------
44
45* Gitorious: Gitorious is very slick hosting solution, but without mirroring
46 support (thus less flexible for both public and corporate deployment) and
47 offering different project model and interface nice for Web 2.0 fans but
48 not for those who prefer the raw beauty and terseness of gitweb.
49
50* GitHub: Like Gitorious, but actually not open-source at all.
51
52* Gitosis, gitolite: Not really a hosting solution, just a clever way to give
53 multiple users push access over SSH without giving them actual UNIX accounts
54 on the system. It could be used as an alternative to chroot for push access
55 support in Girocco, though that is unfortunately not yet implemented.
56
57
58Requirements and setup
59----------------------
60
61You will need git pre-installed, or you can build and install one from
62the git.git subdirectory; normally, Girocco will use only gitweb from there.
63However, some bits of Girocco (e.g. the chroot setup) will rely on
e9dec6ff
PB
Petr Baudis2009-11-04 12:03:51 +010064/usr/bin/git regardless of cmd_git settings; for chroot you will also need
65/bin/nc.openbsd (netcat-openbsd debian package). You will need to add the
66right users to the right groups (a dedicated Girocco user and the CGI user,
79ebd4ab
PB
Petr Baudis2009-11-03 02:54:49 +010067at least); root access or root user cooperation will be probably essential
68unless you have good suexec setup. Girocco is designed to be run only with
69single instance within one system. If you want git protocol access, you will
70need to set up git-daemon independently, but it's very easy with inetd.
71
72After configuring Girocco (editing Girocco/Config.pm and possibly other
73files), you should try to run make install and carefully look at any
74errors. See INSTALL for details. The installation procedure (especially
75chroot setup) is tuned for Debian systems, elsewhere you might need to
76adjust few things.
77
e4b75509 Petr Baudis2009-11-04 09:24:08 +010078You should be running jobd.sh at all times - it will periodically check
79ebd4ab
PB
Petr Baudis2009-11-03 02:54:49 +010079all the repositories and check if any need garbage collection, but also
80update them if the mirroring mode is enabled.
81
e4b75509
PB
Petr Baudis2009-11-04 09:24:08 +010082If you enable mirror support or want to have push notifications, you must
83also be running taskd.pl - it will listen to clone requests and perform
84the actual clone operations, and listen to notification messages from
85repository post-receive hooks and perform notifications.
79ebd4ab
PB
Petr Baudis2009-11-03 02:54:49 +010086
87If you enable push support, you will have to run sshd as root from
88within the chroot setup by make install; no special setup of the sshd
89is necessary, up to specifying a port to listen at in etc/ssh/sshd_config
56a52a1e Kyle J. McKay2013-05-07 11:21:27 -070090within the chroot (if the port is not to be 22).
79ebd4ab
PB
Petr Baudis2009-11-03 02:54:49 +010091
92Alternately, you can use push support with extremely relaxed security,
93but using the system-wide password database and not requiring a chroot.
94Or you could implement Gitosis permission model and send me a patch. ;-)
92f1b95a Petr Baudis2006-10-07 22:43:29 +020095
92f1b95a Petr Baudis2006-10-07 22:43:29 +020096
79ebd4ab
PB
Petr Baudis2009-11-03 02:54:49 +010097History and naming
98------------------
99
100Until Jul 2008, we called all the repo.or.cz machinery just 'repo', however
101that is not very good name, especially since the machinery is now suitable
102for universal usage even outside of repo.or.cz. Thankfully, Jan Engelhart
103invented a nice name 'Girocco', standing for 'GIt Repo.Or.Cz COdebase'.
104
105At that time, the machinery was a set of ugly cronjobs completely specific
106for repo.or.cz. However, Novartis sponsored an internship for Pasky to
107generalize the framework and adapt it for an internally suitable usage.
108And another year later, Pasky finally finished the job by porting Girocco
109back to useable state for repo.or.cz and further cleaning it up.
110
111
248da9a6
PB
Petr Baudis2009-11-10 10:10:31 +0100112Forks
113-----
114
115An important Girocco concept is a _project fork_ - anyone can fork any
116project (including a fork of another project), the fork resides in the
117directory structure as PARENT/FORK.git. Forks are meant as a place for
118people to freely publish their modifications for the project, even if
119they don't have push permissions to the parent. To save space and
120bandwidth, the fork will reuse objects in the parent project, garbage
121collection is done in a clever way not to prune objects used in forks.
122
123
79ebd4ab
PB
Petr Baudis2009-11-03 02:54:49 +0100124Implementation of project database
125----------------------------------
126
127(All uids and gids are allocated from range 65536..infty. All passwords are
128stored in DES crypt(3) format because Apache is moronic - in the past
129the group file was also used as htpasswd file.)
92f1b95a
PB
Petr Baudis2006-10-07 22:43:29 +0200130
131When you register a project, it will get a gid allocation and you will set a
132password for it. The triple is stored in a group(5) file (but containing just
133the project groups):
134
135 projname:crypt:gid:list,of,users
136
137When you register a user, it will get a uid allocation and you will upload
138an ssh public key for it. The user is stored in a passwd(5) file (but
139containing just the repo.or.cz users; 65534 is nogroup):
140
b50a59c4 Petr Baudis2006-10-08 02:01:08 +0200141 username:x:uid:65534:email:/:/bin/git-shell
92f1b95a
PB
Petr Baudis2006-10-07 22:43:29 +0200142
143The authorized keys are stored in /etc/sshkeys/username.
144
145When you (un)assign user to a project, you just manipulate the list of users
146for the project in /etc/group. The web interface for the project administration
79ebd4ab Petr Baudis2009-11-03 02:54:49 +0100147is protected by the group password.
92f1b95a Petr Baudis2006-10-07 22:43:29 +0200148
422c4003 Petr Baudis2006-10-09 04:15:43 +0200149Since Apache is not in the project groups, there is a special cronjob run
79ebd4ab Petr Baudis2009-11-03 02:54:49 +0100150once in a while to fix up the permissions for the refs/, info/, and objects/
422c4003
PB
Petr Baudis2006-10-09 04:15:43 +0200151project directories, under the root user.
152
79ebd4ab
PB
Petr Baudis2009-11-03 02:54:49 +0100153If the given project is in push mode, that is indicated by having a .nofetch
154file in the repository. If the given project is in mirror mode on the other
155hand, that is indicated by the absence of .nofetch and by having double colon
156after the gid in the group(5) file - this prevents listed users to actually
157have write access to the repository.