No Server Required

Fossil does not require a central server. But, [./server/whyuseaserver.wiki|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 [/help?cmd=http|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 [/help?cmd=server|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 [/help?cmd=cgi|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 [./selfhost.wiki|self-hosting repositories] are implemented CGI running behind althttpd. For web servers such as Nginx that do not support CGI, Fossil can be run using SCGI. SCGI involves running the [/help?cmd=http|fossil http] command with the --scgi option. SCGI is something of a cross between a stand-alone server running behind a reverse proxy and an ordinary CGI server. 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:

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 [./contribute.wiki | contributions] to cover these as well. We also welcome contributions to fill gaps (❌) in the table above.

Further Details