Installing cgit + nginx on Debian Jessie

Animated image of professor Emmett Brown from Back to the Future, he looks shocked. Greetings Time Traveler!

It looks like you found a post that is several years old. Keep in mind that technology changes fast and some of the information in this post might no longer be relevant.

If you're stuck, leave a comment and I'll try to help if I can.

Image via GIPHY


cgit is a hyperfast web frontend for git repositories written in C. Coupled with nginx, this makes a super quick git repository viewer for your web server. I was not able to find a good tutorial on how to get this installed with nginx on a Debian server. The latest version of Debian Stable (Jessie) comes with cgit already in the repositories so a lot of previous tutorials that had you compile cgit are no longer necessary unless you really need the latest and greatest version of cgit.

Installation and Configuration

Install Packages

In order to run cgit with nginx, you will need to install cgit, nginx, and fcgiwrap.

sudo apt-get update 
sudo apt-get install cgit nginx fcgiwrap

Configure your nginx.conf to work with cgit

The contents of /etc/nginx/nginx.conf file should look something like this:

worker_processes 1; 

events { 
  worker_connections 1024; 

http { 
  include mime.types; 
  default_type application/octet-stream; 
  sendfile on;
  keepalive_timeout 65; 
  gzip on;

  server { 
     listen 80; 
     server_name; # update to be your own domain
     root /usr/share/cgit;
     try_files $uri @cgit;

     location @cgit { 
      include fastcgi_params; 
      fastcgi_param SCRIPT_FILENAME /usr/lib/cgit/cgit.cgi; 
      fastcgi_param PATH_INFO $uri; 
      fastcgi_param QUERY_STRING $args; 
      fastcgi_param HTTP_HOST $server_name; 
      fastcgi_pass unix:/run/fcgiwrap.socket; 

Configure cgit Edit /etc/cgitrc

Your file should look like this:

#cgit config
#see cgitrc(5) for details


Fire it up!

Now you are ready to see cgit. Restart nginx and navigate to your web server.

/etc/init.d/nginx restart

You should see the cgit home screen at your domain name or IP address now.

Add some repos

You can add repos to your /etc/cgitrc file and they will show up in cgit. The repo section of this file should look something like this:

# List of repositories. 
# This list could be kept in a different file (e.g. '/etc/cgitrepos') 
# and included like this: 
# include=/etc/cgitrepos 

repo.desc=This is my git repository 
repo.desc=That's my other git repository

Since cgit is packaged in Debian now, getting up and running is easier than ever. If you ran into any issues following this guide let me know in the comments.

Making cgit Pretty

So whats next? A bare cgit installation is pretty dull and there are some neat built in features that should be enabled for an optimal user experience. Open up /etc/cgitrc and made the following additions.

Configure Default README

You can set the default README for all repos by adding the following line. This will tell cgit to look for the file in your master branch for the default README for a given project.

Add an about filter

You can add an about filter which will add the about tab to your projects and display the README file configured in the previous step. about-filter=/usr/lib/cgit/filters/ Assuming that you have a file in your master branch you will now see it in the about tab of your project.

Enable Syntax Highlighting

This is a no brainer. Adding syntax highlighting makes your code easier to look at on the website. This takes a few steps. First install the highlight package with sudo apt-get install highlight. Next, open up /usr/lib/cgit/filters/ and uncomment the last line that reads exec highlight --force -f -I -O xhtml -S "$EXTENSION" 2>/dev/null Next, open up your stylesheet which should be found in usr/share/cgit/cgit.css and add the following sections:

# Style definition file generated by highlight 2.4.8, 
table.blob .num { color:#2928ff; } 
table.blob .esc { color:#ff00ff; } 
table.blob .str { color:#ff0000; } 
table.blob .dstr { color:#818100; } 
table.blob .slc { color:#838183; font-style:italic; } 
table.blob .com { color:#838183; font-style:italic; } 
table.blob .dir { color:#008200; } 
table.blob .sym { color:#000000; } 
table.blob .kwa { color:#000000; font-weight:bold; } 
table.blob .kwb { color:#830000; } 
table.blob .kwc { color:#000000; font-weight:bold; } 
table.blob .kwd { color:#010181; }  

# Style definition file generated by highlight 3.13,  
body.hl { background-color:#e0eaee; } 
pre.hl { color:#000000; background-color:#e0eaee; 
font-family:'Courier New',monospace;} 
.hl.num { color:#b07e00; } 
.hl.esc { color:#ff00ff; } 
.hl.str { color:#bf0303; } 
.hl.pps { color:#818100; } 
.hl.slc { color:#838183; font-style:italic; } { color:#838183; font-style:italic; } 
.hl.ppc { color:#008200; } 
.hl.opt { color:#000000; } 
.hl.ipl { color:#0057ae; } 
.hl.lin { color:#555555; } 
.hl.kwa { color:#000000; font-weight:bold; } 
.hl.kwb { color:#0057ae; } 
.hl.kwc { color:#000000; font-weight:bold; } 
.hl.kwd { color:#010181; }

Lastly, add this to your configuration file to enable syntax highlighting.


Since most of my repos look the same I configured these settings globally. You can also configure this at a per-repo level if you simply add any of theses sections to your specific repo settings. For example if you have a different README format such as README.rst for a repo called “my-repo” Then your configuration for that specfic repo would look something like this:

repo.desc=The best repo ever 
repo.owner=Your Name

Now you have a super fast git repo web viewer and it has a couple of bells and whistles as well.

Using cgit

There are a couple of tools out there to make the process of adding, removing, and modifying git repositories within cgit much simpler but we will focus here on how to do it manually and I will leave it up to you to decide which tools works best for you. cgit does not impose any special requirements for adding, removing, or modifying repositories so the entire process is based around core git functionality. Below is a workflow that works well for me.

Creating a Git User

Creating a git user that has access to /srv/git just makes good sense. To add a new user in Debian you will need to run the following commands and follow the on screen instructions to complete this process. adduser git

Adding your public key

In order to authenticate to the server and work with git it is good to add your public key to avoid working with passwords. If you do not already have a key, go ahead and create one on your local machine. ssh-keygen -b 8192 Follow the on screen instructions, and be sure to add a password to this key! Once you have create this key, copy the public key over to your git server under the git users .ssh/authorized_keys file.

scp $USER/.ssh/

Creating a new repository

Log into the git server as the git user and create a bare repository

cd /srv/git 
mkdir myrepo.git 
cd myrepo.git 
git init --bare

Push to the new repository

On your local computer

mkdir myrepo 
cd myrepo git init echo "My Awesome Repo" >> 
git add 
git commit -m 'initial commit' 
git remote add origin 
git push origin master

Add the new repository to cgit

Now that your repository is on your server, you can add it cgit by editing /etc/cgitrc and adding it as we did before.

repo.url = myrepo 
repo.path = /srv/git/myrepo.git 
repo.desc = My Awesome Repo 
repo.owner = Your Name

You are all set! Now you will see the new repo and any future changes inside of cgit as well as being able to hack away with git as you normally would.

Credits: I got a lot of inspiration from this guide via the awesome Arch Wiki. There were some minor changes that had to be made due to some configuration differences between Arch and Debian.

You can add a comment via Email. Or use the embedded discourse form shown below: