Fossil: How To Configure A Fossil Server

No Server Required

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

A Fossil server does not require much memory, CPU, or disk space and can run comfortably on a generic $5/month virtual host or on a small device like a Raspberry Pi, or it can co-exist on a host running other services without getting in the way.

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.

Repository Prep

Prior to serving a Fossil repository to others, consider running fossil ui locally and taking these minimum recommended preparation steps:

Fossil creates only one user in a new repository and gives it the all-powerful Setup capability. The 10-digit random password generated for that user is fairly strong against remote attack, even without explicit password guess rate limiting, but because that user has so much power, you may want to give it a much stronger password under Admin → Users.
Run the Admin → Security-Audit tool to verify that other security-related permissions and settings are as you want them. Consider clicking the “Take it private” link on that page to lock down the security on that site to a level appropriate to a private repository, even if you will eventually want some public service. It's better to start from a secure position and open up service feature-by-feature as necessary than it is to start from a fully open position and lock down features one by one to achieve a secure stance.

With the repository secured, it is safe to upload a copy of the repository file to your server and proceed with server setup, below. Further configuration steps can wait until after the server is running.

Activation Methods

There are basically five ways to run a Fossil server:

All of these methods can serve either a single repository or a directory hierarchy containing mulitiple repositories.

You are not restricted to a single server setup. 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 in response to 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 URL that corresponds to that script, Fossil runs and generates the response.

CGI is a good choice for merging Fossil into an existing web site, particularly on hosts that have CGI set up and working. The Fossil self-hosting repositories are implemented with CGI underneath althttpd.

Socket Listener

Socket listener daemons such as inetd, xinetd, stunnel, launchd, and systemd can be configured to invoke the the fossil http command to handle each incoming HTTP request. The "fossil http" command reads the HTTP request off of standard input, computes an appropriate reply, and writes the reply on standard output. There is a separate invocation of the "fossil http" command for each HTTP request. The socket listener daemon takes care of relaying content to and from the client, and (in the case of stunnel) handling TLS decryption and encryption.

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.

SCGI

The Fossil standalone server can also handle SCGI. When the fossil server command is run with the extra --scgi option, it listens for incoming SCGI requests rather than HTTP requests. This allows Fossil 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.

SSH

Fossil supports ssh:// URLs, but there are practical limitations with the default behavior. You can get the full power of Fossil's RBAC system over SSH with a bit of clever configuration.

Activation 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	FastCGI	althttpd	proxy	service
Any	✅	✅	✅	✅	✅	❌	✅	❌	❌
Debian/Ubuntu	✅	✅	✅	✅	✅	❌	✅	✅	✅
macOS	✅	❌	✅	✅	✅	❌	✅	❌	✅
OpenBSD	✅	❌	✅	✅	✅	✅	✅	❌	✅
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.

Post-Activation Configuration

After the server is up and running, log into it as the Setup user and visit the Admin menu to finish configuring that repository for service:

Add user accounts for your other team members. Use categories to define access policies rather than redundantly give each new user the same individual capabilities.
Test access to the repository from each category of non-Setup user that you created. You may have to give your user categories some overlooked capabilities, particularly if you followed our earlier advice to take the repository private prior to setting up the server.
Modify the repository's look and feel by customizing the skin.
If the repository includes embedded documentation, consider activating the search feature (Admin → Search) so that visitors can do full-text search on your documentation.
Now that others can be making changes to the repository, consider monitoring them via email alerts or the timeline RSS feed.
Turn on the various logging features.

Reload the Admin → Security-Audit page occasionally during this process to double check that you have not mistakenly configured the server in a way that might expose information that you want to keep private.

Fossil