Fossil: How To Configure A Fossil Server

This guide is intended to help guide you in setting up a Fossil server.

Standalone server

The easiest way to set up a Fossil server is to use the server or ui command. Assuming the repository you are interested in serving is in the file "repo.fossil", you can use either of these commands to start Fossil as a server:

fossil server repo.fossil
fossil ui repo.fossil

Both of these commands start a Fossil server on port 8080 on the local machine, which can be accessed with the URL: http://localhost:8080/ using any handy web browser. The difference between the two commands is that "ui", in addition to starting the Fossil server, also starts a web browser and points it to the URL mentioned above, and the "ui" command binds to the loopback IP address only (127.0.0.1) so that the "ui" command cannot be used to serve content to a different machine.

If one of the commands above is run from within an option checkout, then the repository name can be omitted and the checkout is used as the repository.

Instead of a single repository, the commands above can specify a directory that contains multiple Fossil repositories named with the ".fossil" suffix. In this case, the request URL should begin with the base name of the particular repository that is desired.

Additional notes:

The option "--port NNN" will start the server on port "NNN" instead of 8080.
If port 8080 is already being used (perhaps by another Fossil server), then Fossil will use the next available port number.
The "server" and "ui" commands are an excellent options for quickly sharing with coworkers on a small network.
This deployment scenario does not require special "root" or "administrator" access in order to share the repository.

Fossil as an ''inetd'' service

Modify your /etc/inetd.conf (on Linux, modify as appropriate for your platform) so it contains a line like this:
12345 stream tcp nowait.1000 root /path-to/fossil /path-to/fossil http /other-path-to/repository
In this example, you are telling "inetd" that when an incoming connection on port "12345" happens, it should launch the binary "/path-to/fossil". Obviously you will need to modify the "path-to" parts as appropriate for your particular setup.

If you system is running xinetd, then a typical configuration will be held an a separate file (often named "/etc/xinetd.d/http-alt") that might look something like this:
service http-alt
{
  port = 591
  socket_type = stream
  wait = no
  user = root
  server = /usr/bin/fossil
  server_args = http /home/fossil/repos/
}
The xinetd example above has Fossil configured to serve multiple repositories, contained under the "/home/fossil/repos/" directory. All repositories should be named with a ".fossil" suffix. In such a setup, the first element of the request URI should be the name of the repository relative to the /home/fossil/repos/ directory and without the ".fossil" suffix.

Using inetd or xinetd is a more complex setup than the "standalone" server, but it has the advantage of only using system resources when an actual connection is attempted. If no-one ever connects to that port, a Fossil server will not (automatically) run. It has the disadvantage of requiring "root" access and therefore may not normally be available to lower-priced "shared" servers on the internet.

Fossil as CGI

This is the most flexible and most likely to be widely usable of these deployment scenarios. In order for it to work, you must have the ability to install "CGI scripts" on the server you are interested in using.

One script per repository

Create a script (let's call it 'repo') in your CGI directory which has content like this:
#!/path-to/fossil
repository: /path-to-repo/repository
It may be necessary to set permissions properly, or to modify an ".htaccess" file or other server-specific things like that. Consult with your server provider if you need that sort of assistance.

Once the script is set up correctly, and assuming your server is also set correctly, you should be able to access your repository with a URL like: http://mydomain.org/cgi-bin/repo (assuming the "repo" script is accessible under "cgi-bin", which would be a typical deployment on Apache for instance).

Serving multiple repositories with one script

This scenario is almost identical to the previous one. However, here we will assume you have multiple repositories, in one directory. (Call the directory 'fossils'). All repositories served, in this case, must use the ".fossil" filename suffix. As before, create a script (again, 'repo'):
#!/path-to/fossil
directory: /path-to-repo/fossils
notfound: http://url-to-go-to-if-repo-not-found/
Once deployed, a URL like: http://mydomain.org/cgi-bin/repo/XYZ will serve up the repository "fossils/XYX.fossil" (if it exists). This makes serving multiple projects on one server pretty painless.

Fossil as SCGI

The [/help/server|fossil server] command, described above as a way of starting a stand-alone web server, can be used for SCGI. Simply add the --scgi command-line option and the stand-alone server will interpret and respond to the SimpleCGI or SCGI protocol rather than raw HTTP. This can be used in combination with a webserver (such as Nginx) that does not support CGI. A typical Nginx configuration to support SCGI with Fossil would look something like this:
location ~ ^/demo_project/ {
    include scgi_params;
    scgi_pass localhost:9000;
    scgi_param SCRIPT_NAME "/demo_project";
}
Note that Fossil requires either the PATH_INFO or the SCRIPT_NAME variable in order to function properly, but Nginx provides neither by default. So it is necessary to provide the SCRIPT_NAME parameter in the configuration. Failure to do this will cause Fossil to return an error.

All of the features of the stand-alone server mode described above, such as the ability to server a directory full of Fossil repositories rather than just a single repository, work the same way in SCGI mode.

Securing a repository with SSL

Using either CGI or SCGI, it is trivial to use SSL to secure the server. Simply set up the Fossil CGI scripts etc. as above, but modify the Apache (or IIS, etc.) server to require SSL (that is, a URL with "https://") in order to access the CGI script directory. This may also be accomplished (on Apache, at least) using appropriate ".htaccess" rules.

If you are using "inetd" to serve your repository, then you simply need to add "/usr/bin/stunnel" (perhaps on a different path, depending on your setup) before the command line to launch Fossil.

At this stage, the standalone server (e.g. "fossil server") does not support SSL.

For more information, see Using SSL with Fossil.

Various security concerns with hosted repositories

There are two main concerns relating to usage of Fossil for sharing sensitive information (source or any other data):

Interception of the Fossil synchronization stream, thereby capturing data, and
Direct access to the Fossil repository on the server

Regarding the first, it is adequate to secure the server using SSL, and disallowing any non-SSL access. The data stream will be encrypted by the HTTPS protocol, rendering the data reasonably secure. The truly paranoid may wish to deploy ssh encrypted tunnels, but that is quite a bit more difficult and cumbersome to set up (particularly for a larger number of users).

As far as direct access to the repository, the same steps must be taken as for any other internet-facing data-store. Access passwords to any disk-accessing accounts should be strong (and preferably changed from time to time). However, the data in the repository itself are not encrypted (unless you save encrypted data yourself), and so the system administrators of your server will be able to access your data (as with any hosting service setup). The only workaround in this case is to host the server yourself, in which case you will need to allocate resources to deal with administration issues.