Fossil

How To Configure A Fossil Server
Login

No Server Required

Fossil does not require a central server. But, a server can be very useful.

This article is a quick-reference guide for setting up your own Fossil server, with links to more detailed instructions specific to particular systems, should you want extra help.

Methods

There are basically four ways to set up a Fossil server:
  1. Socket listener: inetd, xinetd, stunnel...
  2. Stand-alone HTTP server
  3. SCGI
  4. CGI

The idea behind the socket listener approach is that each incoming HTTP request is relayed to a new instance of the fossil http command. That command reads the HTTP request from its standard input, handles the request, and writes a complete and correct HTTP reply on standard output which is then returned to the client.

A stand-alone server uses the fossil server command to run a process that listens for incoming HTTP requests on a socket and then dispatches a copy of itself to deal with each incoming request. A stand-alone server can talk directly with the client, or the system can be configured with a reverse proxy in between the client and Fossil.

Fossil can also be run using CGI from ordinary web servers such as Apache, IIS, lighttpd, or althttpd. A short CGI script is placed in the document hierarchy of the web server, and when a client requests the appropriate URL, Fossil is run to generate the responce. CGI is a good choice for incorporating Fossil as part of a larger website. The Fossil self-hosting repositories are implemented with CGI underneath althttpd.

For web servers such as nginx that do not support CGI, Fossil supports SCGI, a protocol that gives most of the simplicity of CGI with the efficiency of the stand-alone server option. With nginx, you use the fossil server command with the --scgi option.

Regardless of the method you choose, all can serve either a single repository or a directory hierarchy containing many repositories with names ending in ".fossil".

Note that a single project is not restricted to using a single server setup method. The same Fossil repository can be served using two or more of the above techniques, at the same time. And the server setup can change over time, to accomodate changes in hosting providers or administrator preferences.

System-Specific Setup Tutorials

We've broken the configuration for each method out into a series of sub-articles, some of which are OS-specific:
  Fossil Front-End Program
Host OS none inetd xinetd stunnel CGI SCGI althttpd nginx Apache IIS OS service
Any ✅ ✅ ✅ ✅ ✅ ✅ ✅ ❌ ❌ ❌ ❌
Debian/Ubuntu ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ❌ ❌ ❌
Windows ❌ ❌ ❌ ✅ ✅ ❌ ❌ ❌ ❌ ✅ ✅
Where there is a check mark in the "Any" row, the method for that is generic enough that it works across OSes that Fossil is known to work on. The check marks below that usually just link to this generic documentation.

There are several widely-deployed socket listener schemes besides the inetd, xinetd, and stunnel schemes with documents linked above: Apple’s launchd, Linux’s systemd, Solaris’ SMF, etc. We would welcome contributions to cover these as well. We also welcome contributions to fill gaps (❌) in the table above.

Further Details