Summary

It is not necessary to have a central server in order to use Fossil. But a central server can help a project run more smoothly by giving developers a common point of rendezvous for syncing, and by providing a web-based portal where developers and non-developers alike can learn about the project and its current state.

Setting up a server using Fossil is easy. A separate document talks about all of the many different methods for setting up a Fossil server, one of which is as a CGI script. CGI is the technique that the three self-hosting Fossil repositories all use.

Setting up a Fossil server using CGI is mostly about writing a short script (usually just 2 lines line) in the cgi-bin folder of an ordinary web-server. But there are a lot of extra options that can be added to this script, to customize the configuration. This article describes those options.

CGI Script Options

The CGI script used to launch a Fossil server will usually look something like this:

#!/usr/bin/fossil
repository: /home/www/fossils/myproject.fossil

Of course, pathnames will likely be different. The first line (the "shebang") always gives the name of the Fossil executable. Subsequent lines are of the form "property: argument ...". The remainder of this document describes the available properties and their arguments.

repository: PATH

This property defines the Fossil repository that the server will use. Every Fossil CGI requires either this property or the directory: property (but not both). Many Fossil CGI scripts have this one property and no other.

directory: PATH

The PATH is the name of a directory that contains one or more Fossil repository files having the suffix ".fossil". If this property is used instead of repository:, then the Fossil server is able to serve all of the repositories in the directory. The specific repository used is selected by a prefix on the PATH_INFO.

notfound: URL

If the directory: option is used and if the PATH_INFO of the HTTP request does not correspond to any Fossil repository, then the request redirects to URL.

repolist

This is a Boolean property. If it is present, and if the directory: option is used, and if the PATH_INFO string is empty, then Fossil will show a list of available Fossil repositories.

The "skin" of the reply is determined by the first repository in the list that has a non-zero repolist-skin setting. If no repository has such a non-zero repolist-skin setting, then the repository list is generic HTML without any decoration.

localauth

This is a Boolean property. If it is present, setup capability is granted to any HTTP request that comes in over a loopback interface, such as 127.0.0.1.

skin: NAME

If NAME is the name of one of the built-in skins supported by Fossil, then this option causes Fossil to display using that built-in skin, and to ignore any custom skin that might be configured in the repository itself.

So, if you wanted to set up a server for a single Fossil project, but also give users the option to use several of the different built-in skins, you could create multiple CGI scripts, each with a different "skin:" property, but all pointing to the same repository:. Then users can select which skin to use by using the appropriate CGI.

files: GLOBLIST

The GLOBLIST argument is a comma-separate list of "globs" that specify filenames. In directory: mode, if the PATH_INFO does not identify any Fossil repository, but it does refer some other file in the directory, and that filename matches one of the glob patterns in the GLOBLIST, then the file is returned as static content.

setenv: NAME VALUE

This parameter causes additional environment variable NAME to have VALUE. This parameter can be repeated as many times as necessary.

HOME: PATH

This parameter is a short-hand for "setenv HOME PATH".

cgi-debug: FILE

Cause CGI-related debugging information to be appended in FILE. Use this to help debug CGI problems.

errorlog: FILENAME

This setting causes the server to log any errors in FILENAME. It is ok for multiple Fossil CGIs to share the same error log.

Setting up an error log for Fossil servers is not required, but it is recommended.

timeout: N

This property changes the timeout on each CGI request to N seconds. If N is zero, then there is no timeout. If this property is omitted, then the default timeout is 300 seconds (5 minutes).

extroot: PATH

This property defines the DOCUMENT_ROOT for the CGI Server Extensions. If this property is present, then CGI Server Extensions are enabled. When this property is omitted, CGI Server Extensions are disabled.

A cascade of CGI invocations can occur here. Fossil itself is started as CGI, then Fossil can turn around and invoke a sub-CGI extension. The sub-CGI extension outputs reply text, when Fossil then (optionally) augments with its own header and footer and returns to the original requestor. The property controls the DOCUMENT_ROOT of the sub-CGI.

redirect: REPO URL

Extract the "name" query parameter and search REPO for a check-in or ticket that matches the value of "name", then redirect to URL. There can be multiple "redirect:" lines that are processed in order. If the repo name is "*", then an unconditional redirect to URL is taken.

jsmode: VALUE

Specifies the delivery mode for JavaScript files. See "http --jsmode" for the allowed values and their meanings.

mainmenu: FILE

This parameter causes the contents of the given file to override the site's mainmenu configuration setting, much in the same way that the skin setting overrides the skin. This can be used to apply a common main menu to a number of sites, and centrally maintain it, without having to copy its contents into each site. Note, however, that the contents of this setting are not stored in the repository and will not be cloned along with the repository.