Fossil

How To Configure A Fossil Server
Login

How To Configure A Fossil Server

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. CGI
  2. Stand-alone HTTP server
  3. Socket listener
  4. SCGI

All of these methods can serve either a single repository or a directory containing repositories named "*.fossil".

You are not restricted to using a single method. The same Fossil repository can be served using two or more of the above techniques at the same time. These methods use clean, well-defined, standard interfaces (CGI, SCGI, and HTTP) which allow you to easily migrate from one method to another to accommodate changes in hosting providers or administrator preferences.

CGI

Most ordinary web servers can run Fossil as a CGI script. This method is known to work with Apache, lighttpd, and althttpd. The Fossil server administrator places a short CGI script in the web server's document hierarchy, and when a client requests the appropriate URL, that script runs Fossil to generate the response.

CGI is a good choice for merging Fossil into an existing web site, particularly on hosts that have CGI set up for you already and won't let you modify the web server configuration further. The Fossil self-hosting repositories are implemented with CGI underneath althttpd.

Stand-alone HTTP Server

This is the easiest method. 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. You can expose Fossil directly to the clients in this way or you can interpose a reverse proxy layer between the clients and Fossil.

Socket Listener

Only slightly more complicated is the socket listener method. Instead of letting Fossil run in the background continuously to handle HTTP requests from clients, you configure a socket listener daemon to run a fossil http command on each HTTP hit. That Fossil instance handles only that one hit and then shuts back down, letting the socket listener go back to waiting for the next hit. This scheme is known to work with inetd, xinetd, stunnel, launchd, and systemd.

SCGI

The Fossil standalone server can also run in SCGI modefossil server --scgi — instead of HTTP mode, which allows it to respond to requests from web servers such as nginx that don't support CGI. SCGI is a simpler protocol to proxy than HTTP, since the HTTP doesn't have to be re-interpreted in terms of the proxy's existing HTTP implementation, but it's more complex to set up because you also have to set up an SCGI-to-HTTP proxy for it. It is worth taking on this difficulty only when you need to integrate Fossil into an existing web site already being served by an SCGI-capable web server.

Setup Tutorials

We've broken the configuration for each method out into a series of sub-articles. Some of these are generic, while others depend on particular operating systems or front-end software:

⇩ OS / Method ⇨ direct inetd stunnel CGI SCGI althttpd proxy service
Any
Debian/Ubuntu
macOS
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.

The method in the "proxy" column is for the platform's default web server configured as a reverse proxy for Fossil's built-in HTTP server: nginx, IIS, Apache, etc.

We welcome contributions to fill gaps () in the table above.

Further Details