Circle Device


Quick Reference

nginx with cgit

nginx with cgit

cgit is a plain CGI executable for viewing git repositories. nginx is a web server that does not support plain CGI. This is a quick walkthrough on how to get them working together.

Required Packages

  • nginx
  • cgit
  • spawn-fcgi
  • fcgiwrap

On Gentoo (my distribution of choice) just emerge:

emerge nginx spawn-fcgi fcgiwrap

Download and compile cgit (it could be emerged but that would probably take the fun out of it).

Configure nginx with FastCGI

When a request comes in for a file in /cgi-bin/ that request must be forwarded to the fastcgi daemon... in this case fcgiwrap which is wrapping cgit spawned by spawn-fcgi. Yes, you are correct, it is a bit clunky.

http {
... stuff ...
server {
    listen 80;
    server_name localhost;
    access_log /var/log/nginx/localhost.access_log main;
    error_log/var/log/nginx/localhost.error_log info;
    root /var/www/localhost/htdocs;

    location /cgi-bin/cgit {
        root /var/www/localhost;
        include /etc/nginx/fastcgi_params;
        fastcgi_param DOCUMENT_ROOT   $document_root;
        fastcgi_param PATH_INFO       $uri;
        fastcgi_param QUERY_STRING    $args;
        fastcgi_param SCRIPT_NAME     /cgi-bin/cgit;
        fastcgi_pass unix:/tmp/cgi.sock;
... maybe more stuff ...

In another terminal execute create the fcgiwrap daemon:

spawn-fcgi -s /tmp/cgi.sock -P /var/run/ -u nginx -g nginx -- /usr/sbin/fcgiwrap -f

To see that it is working attempt to access http://hostname/cgi-bin/cgit. You should be presented with your git repositories.

Background Note

fcgiwrap uses DOCUMENT_ROOT and SCRIPT_NAME (concatenated together) or SCRIPT_FILENAME (exclusively) to determine the CGI executable. In the above example fcgiwrap will try to execute: /var/www/localhost/cgi-bin/cgit when a reqest is made to /cgi-bin/cgit since DOCUMENT_ROOT is taken from $document_root which is defined on the line root /var/www/localhost and script name is /cgi-bin/cgit.

Important Note

In the above configuration there is a socket created in /tmp for some modern distributions this will not work as the nginx service may be executed in a namespace that provides a private /tmp. To avoid this try placing the socket in /var/run for example:

spawn-fcgi -s /var/run/nginx-cgi.sock -P /var/run/ -u nginx -g nginx -- /usr/sbin/fcgiwrap -f

Cleaning up

Naturally this will not work across re-boots, you should make a script to start cgit.


Quick Links: Techie Stuff | General | Personal | Quick Reference