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.

Apache mod_cgi and CONTENT_LENGTH

At some point in its 2.4.x family, Apache's mod_cgi stopped relaying the Content-Length header in the HTTP reply from CGIs back to clients. However, Fossil clients prior to 2024-04-17 depended on seeing the Content-Length header and were unable to handle HTTP replies without one. The change in Apache behavior caused "fossil clone" and "fossil sync" to stop working. There are two possible fixes to this problem:

  1. Restore legacy behavior in Apache by adding the following to the Apache configuration, scoped to the <Directory> entry or entries in which fossil is being served via CGI:

      <Directory ...>
         SetEnv ap_trust_cgilike_cl "yes"

  2. Upgrade your Fossil client to any trunk check-in after 2024-04-17, as Fossil was upgraded to be able to deal with the missing Content-Length field by check-in a8e33fb161f45b65.