Skip to content

Gitweb and Nginx

November 1, 2012

Git Web provides a great interface for your git projects, and is useful even if you just use it locally. It provides a very convenient way to browse your repositories and search over them using some of the more interesting searches.

This will cover installation and configuration of nginx and gitweb.


You need to have git installed! Since you are reading this it is likely you already do, but just in case:

sudo apt-get install git

There is no requirement to configure this, but you may wish to set your username and email address. You can do that like so:

git config --global ""
git config --global "Billy Everyteen"


The next part is the webserver that will run all this. While this can be done (quite easily) with apache, this tutorial covers nginx. Get it like this:

sudo apt-get install nginx

This will install the nginx server at /etc/nginx, as well as creating a control script at /etc/init.d/nginx. The server will be started by default, you can check it is running by visiting http://localhost. You should see a message saying “Welcome to nginx!”.


You then need to install a fast cgi wrapper and something that will handle spawning the fcgi instances as appropriate. While you could install these from source and spend some time configuring them, once again the apt repositories come to the rescue:

sudo apt-get install fcgiwrap spawn-fcgi

This should create a socket file at /var/run/fcgiwrap.socket. If you have terminal file colouring on, you will see that this file differs from regular files. That is because it is a unix socket. This socket allows communication between nginx and the fcgi process.

Git Web

Now we need to install the gitweb package that will actually display the git repositories and provide search.

sudo apt-get install gitweb

This will create the following files and folders:

  • /etc/gitweb.conf
    This configures the gitweb instance. By default it serves the projects from /var/cache/git
  • /usr/share/gitweb
    This contains the cgi scripts as well as the images and icons. Some settings are within the .cgi files found in this folder.
  • /var/cache/git
    This is the default location that gitweb will look for projects. You can change this by editing /etc/gitweb.conf.


The final part of setting it up is actually linking it all up together.

The socket that the fast cgi wrapper creates is owned by www-data, so nginx must run as that user. To do this you just need to edit the /etc/nginx/nginx.conf file and change the user to www-data. You should see the user line near the top of this file.

The nginx server then needs to be instructed to serve the content through gitweb. Here is an example configuration that you should create in /etc/nginx/sites-available/gitweb:

server {
  listen 80 default;

  location /index.cgi {
    root /usr/share/gitweb/;
    include fastcgi_params;
    gzip off;
    fastcgi_param SCRIPT_NAME $uri;
    fastcgi_param GITWEB_CONFIG /etc/gitweb.conf;
    fastcgi_pass  unix:/var/run/fcgiwrap.socket;
  location / {
    root /usr/share/gitweb/;
    index index.cgi;

There are plenty of ways that you can adjust this, but for now it is sufficient.

The final part is to activate this vhost and then restart nginx:

sudo ln -s /etc/nginx/sites-available/gitweb /etc/nginx/sites-enabled/gitweb
sudo /etc/init.d/nginx restart

After this, browsing to http://localhost should show you an empty list of projects (you may need to force reload the page if your browser has cached the old version).

Adding Projects

The list is empty because you have no projects in the /var/cache/git folder. Luckily you do not need to have all your git projects in this folder, instead all you need to do is to link the .git folder from a project to this folder. If you had a folder in your home directory called work which you wished to include, you could do so with the following command:

sudo ln -s ~/work/.git /var/cache/git/work.git

If you do that and then refresh the projects page you should see your project in the list! Woo!

Making it all nice!

You may notice that the project has a description of “Unnamed repository; edit this file ‘description’ to name the repository.”. The file it wants you to edit is the description file found within the .git folder of the repository. Editing that will set the description for the project. Keep it short so you can easily read it on the project list page.

The second bit of messiness you may notice is that the title of the projects page is “Untitled Git”. You can change this by defining the SERVER_NAME in the vhost if you wish, or you can edit the /usr/share/gitweb/index.cgi and /usr/share/gitweb/gitweb.cgi files, updating this line:

# name of your site or organization to appear in page titles
# replace this with something more descriptive for clearer bookmarks
our $site_name = ""
                 || ($ENV{'SERVER_NAME'} || "Untitled") . " Git";

And that is it!

Securing it

You may not wish to have everyone browsing your projects, especially as the gitweb interface allows them to clone your projects. If you are concerned about this then you may wish to apply access controls to the nginx vhost. The simplest of these is access by IP address. If you add the lines:

deny all;

To the server block of your nginx configuration then only browsing from localhost will be permitted – everyone else will get a 403. Obviously, you want to think about why you are setting this up before you start denying legitimate users.

From → git, nginx

  1. Hi, I am able to view projects list on the browser. But when I click on one of the repositories, I get an nginx 404. What could I have missed?

    • Manuel Malagon permalink

      This is exactly what is happening to me. Were you able to figure this out?

  2. Satish Bharatiya permalink

    All worked for me fine, except for the last step of symlinking work git. With newer versions of git, you have to do something like this, via a bare repo and post-update hook:

    $ cd /var/lib/git
    $ git clone –bare ~/work/.git work.git
    $ cd work.git
    $ mv hooks/post-update.sample hooks/post-update
    $ chmod a+x hooks/post-update

    Restart server & it worked.

  3. Eric Johnson permalink

    This worked well for me. However, Gitweb loads slowly for me. Is there any way to reduce loading times?

  4. An error occurred while reading CGI reply (no response received) ,when i do i all , i can`t solve this questions,can you tell me ,how to solve it ?

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s