README

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