By /robex/, July 2018. Back to Articles and Guides
In this guide I'll show how to setup a cgit instance with Apache and control access with gitolite. Specifically, I used Ubuntu but this should work for any distro (although the paths and package managers might change). The final appearance will roughly be like this:
For simplicity and avoidance of a combinatorial explosion of configuration options, I will assume the following things (you can, of course, change these):
Go to any directory with ~300MB free (don't worry, this is to compile only, it will only be about 8MB later) and type the following commands:
git clone https://git.zx2c4.com/cgit/ cd cgit git submodule init && git submodule update make
If everything went well, you should now have a binary called cgit in the current folder. Copy this, along with filters/ , favicon.ico , cgit.css and cgit.png to your server dir (from now on /home/web/cgit/).
*Note: as usual with Apache, remember that the user www-data must have read permissions on the directory.
If you don't already have it, install Apache and enable the cgi module:
sudo apt-get install apache2 sudo a2enmod cgi
Now setup the webserver. This should be under /etc/apache2/sites-available/(something).conf. (something) will depend on whether you'll use https or not. Here are the settings I used (simplified for http):
<VirtualHost *:80>
ServerAdmin webmaster@localhost
DocumentRoot /home/web/cgit/
<Directory "/home/web/cgit/">
AllowOverride All
Options ExecCGI FollowSymlinks
Require all granted
Allow from all
AddHandler cgi-script .cgi
</Directory>
Alias /cgit.css "/home/web/cgit/cgit.css"
Alias /cgit.png "/home/web/cgit/cgit.png"
Alias /favicon.ico "/home/web/cgit/favicon.ico"
#ScriptAlias / "/home/web/cgit/"
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
ServerName git.domain.com
</VirtualHost>
In my case, I didn't want the default behaviour of the urls showing /cgit.cgi/ everywhere, so my solution was to change the name of the binary to index.cgi (hence line 10) and create a RewriteRule for the subdirectories. This was accomplished with the help of cgit, by setting the following in the file /etc/cgitrc (cgit's configuration file, you have to create it):
virtual-root=/ css=/cgit.css logo=/cgit.png remove-suffix=1 snapshots=tar.bz2 zip readme=:README.md readme=:README readme=:readme
I decided to make the repositories password-protected, therefore I created a .htaccess file under /home/web/cgit. If you want them to be public ignore lines 1-4:
AuthType Basic
AuthName "restricted"
AuthUserFile # put your password file here
Require user # users
RewriteEngine On
# You can ignore this line, this is for my custom error pages
# RewriteRule "^(/errors/.*)" "/home/web$1"
RewriteCond %{ENV:REDIRECT_STATUS} ^$
RewriteCond %{REQUEST_URI} !(cgit.css|cgit.png|favicon.ico)
RewriteRule ^(.*)$ /index.cgi/$1
*Note: activate Apache's mod_rewrite with sudo a2enmod rewrite
Since we're at it, we will set syntax highlighting/markdown formatting at this point. Add this to /etc/cgitrc:
about-filter=/home/mint/web/cgit/filters/about-formatting.sh source-filter=/home/web/cgit/filters/syntax-highlighting.py
For syntax highlighting and markdown to work, the following packages must be installed:
sudo apt-get install python3 python3-pygments markdown python3-markdown
In order to add repositories, cgit offers 2 options. The first one (and most comfortable) is to scan a whole directory for repos. The other is to add each repository manually. To do this, add one of the following to /etc/cgitrc:
# scan entire directory scan-path=/home/git/repositories # add repo manually repo.url=myrepo.git repo.path=/home/repo/myrepo.git repo.desc=example
Note that if you want to scan for a whole directory and then setup individual parameters for each repository, you can create a cgitrc file inside that repository and set everything up there. The repo description must be inside the file description
You can change the default page title and description with the following parameters in cgitrc (full list is available here):
root-title=My git root-desc=My repos
Gitolite allows you to control access to your repositories without having to create shell users. The first step is easy enough, just leave the field that will popup in the installer blank:
sudo apt-get install gitolite3
Make sure that you have created a user called (in my case) git. Then login, generate an ssh key, and setup gitolite
sudo adduser git su - git ssh-keygen cp ~/.ssh/id_rsa.pub ~/git.pub gitolite setup -pk ~/git.pub
*Note: if you use a non-standard port for ssh, change it by creating the file ~/.ssh/config, with contents:
Host yourdomain.com Port 1337 # your port here
Now clone gitolite-admin, the repository used to manage gitolite, and add the public keys of the users you need under keys:
git clone [email protected]:gitolite-admin cd gitolite-admin cp user.pub keys git add . git commit -m 'added user' git push
Then, in the users computer, you must use the gitolite url (e.g: [email protected]:test-repo), not cgit (https://git.yourdomain.com/test-repo.git/), to push (you can use cgit to clone only).
Thats all for now, this took me an entire day of frustration to figure out and I hope to make your life easier if you stumble across this. You can try to setup git-http-backend to be able to push to the cgit url, but I was too lazy at the time of making this.