Serving via CGI

Serving via CGI

A Fossil server can be run from most ordinary web servers as a CGI program. This feature allows Fossil to seamlessly integrate into a larger website. The self-hosting Fossil repository web site is implemented using CGI. See the How CGI Works page for background information on the CGI protocol.

To run Fossil as CGI, create a CGI script (here called "repo") in the CGI directory of your web server with content like this:

    repository: /home/fossil/repo.fossil

Adjust the paths appropriately. It may be necessary to set certain permissions on this file or to modify an .htaccess file or make other server-specific changes. Consult the documentation for your particular web server. The following permissions are normally required, but, again, may be different for a particular configuration:

Once the CGI script is set up correctly, and assuming your server is also set correctly, you should be able to access your repository with a URL like: This is assuming you are running a web server like Apache that uses a “cgi-bin” directory for scripts like our “repo” example.

To serve multiple repositories from a directory using CGI, use the "directory:" tag in the CGI script rather than "repository:". You might also want to add a "notfound:" tag to tell where to redirect if the particular repository requested by the URL is not found:

    directory: /home/fossil/repos
    notfound: http://url-to-go-to-if-repo-not-found/

Once deployed, a URL like: will serve up the repository /home/fossil/repos/XYZ.fossil if it exists.

Additional options available to the CGI script are documented separately.

CGI with Apache behind an Nginx proxy

For the case where the Fossil repositories live on a computer, itself behind an Internet-facing machine that employs Nginx to reverse proxy HTTP(S) requests and take care of the TLS part of the connections in a transparent manner for the downstream web servers, the CGI parameter HTTPS=on might not be set. However, Fossil in CGI mode needs it in order to generate the correct links.

Apache can be instructed to pass this parameter further to the CGI scripts for TLS connections with a stanza like

    SetEnvIf X-Forwarded-Proto "https" HTTPS=on

in its config file section for CGI, provided that

    proxy_set_header  X-Forwarded-Proto $scheme;

has been be added in the relevant proxying section of the Nginx config file.

Return to the top-level Fossil server article.