Fossil

The Fossil Web Interface
Login

The Fossil Web Interface

One of the innovative features of Fossil is its built-in web interface. This web interface provides everything you need to run a software development project:

You get all of this, and more, for free when you use Fossil. There are no extra programs to install or setup. Everything you need is already pre-configured and built into the self-contained, stand-alone Fossil executable.

As an example of how useful this web interface can be, the entire Fossil website, including the document you are now reading, is rendered using the Fossil web interface, with no enhancements, and little customization.

<style> div.content pre { background: #cccccc; padding: 0.25em; } </style>

Key point: The Fossil website is just a running instance of Fossil!

Note also that because Fossil is a distributed system, you can run the web interface on your local machine while off network (for example, while on an airplane) including making changes to wiki pages and/or trouble ticket, then synchronize with your co-workers after you reconnect. When you clone a Fossil repository, you don't just get the project source code, you get the entire project management website.

Very Simple Startup

To start using the built-in Fossil web interface on an existing Fossil repository, simply type this:

fossil ui existing-repository.fossil

Substitute the name of your repository, of course. The "ui" command will start a web server running (it figures out an available TCP port to use on its own) and then automatically launches your web browser to point at that server. If you run the "ui" command from within an open check-out, you can omit the repository name:

fossil ui

The latter case is a very useful short-cut when you are working on a Fossil project and you want to quickly do some work with the web interface. Notice that Fossil automatically finds an unused TCP port to run the server on and automatically points your web browser to the correct URL. So there is never any fumbling around trying to find an open port or to type arcane strings into your browser URL entry box. The interface just pops right up, ready to run.

The Fossil web interface is also very easy to setup and run on a network server, as either a CGI program or from inetd, or as an SCGI server. Details on how to do that are described further below.

Things To Do Using The Web Interface

You can view timelines of changes to the project. The default "Timeline" link on the menu bar takes you to a page that shows the 20 most recent check-ins, wiki page edits, ticket/bug-report changes, and/or blog entries. This gives a very useful snapshot of what has been happening lately on the project. You can click to go further back in time, if needed. Or follow hyperlinks to see details, including diffs and annotated diffs, of individual check-ins, wiki page edits, ticket changes, and blog edits.

You can view and edit tickets and bug reports by following the "Tickets" link on the menu bar. Fossil is backed by an SQL database, so users with appropriate permissions can write new ticket report formats based on SQL query statements. Fossil is careful to prevent ticket report formats from doing any mischief on the database (it only allows SELECT statements to run) and it restricts access to sensitive data such as user passwords. So it is actually safe to let anonymous users on the internet write their own ticket formats if you like. In addition to viewing and/or creating report formats, you can also create new tickets or look at summaries or complete histories of existing tickets. Any changes you make will automatically merge with changes from your co-workers the next time your repository is synchronized.

You can view and edit wiki by following the "Wiki" link on the menu bar. Fossil has its own easy-to-remember markup rules, or if you prefer, it also supports Markdown. And, as with tickets, all of your edits will automatically merge with those of your co-workers when your repository synchronizes.

You can view summary reports of branches in the check-in graph by visiting the "Branches" link on the menu bar. From those pages you can follow hyperlinks to get additional details. These screens allow you to easily keep track of what is going on with separate sub-teams within your project team.

The "Files" link on the menu allows you to browse through the file hierarchy of the project and to view complete changes histories on individual files, with hyperlinks to the check-ins that made those changes, and with diffs and annotated diffs between versions.

The web interface supports embedded documentation. Embedded documentation is documentation files (usually in wiki format) that are checked into project as part of the source tree. Such files can be viewed as if they were ordinary web pages. This document that you are now reading is an example of embedded documentation.

Customizing The Web Interface Appearance

Users with appropriate permissions can customize the look and feel of the web interface using the "Admin" link on the main menu of the web interface. Templates for the header and footer of each page can be edited, as can the CSS for the entire page. You can even change around the main menu. Timeline display preferences can be edited. The page that is brought up as the "Home" page can be changed. It is often useful to set the "Home" page to be a wiki page or an embedded document. The built-in pages /home and /index can be used as the "Home" page. They have identical effect, which is to instruct Fossil to find and display a wiki page with the same name as the project, or if that does not exist, /README.md or /index.wiki.

An embedded document link such as doc/trunk/README.md can be used for the "Home" page. If you specify one of the built-in keywords /home or /index, the page will not be treated as an embedded document.

Installing On A Network Server

When you create a new Fossil project and after you have configured it like you want it using the web interface, you can make the project available to a distributed team by simply copying the single repository file up to a web server that supports CGI or SCGI. To run Fossil as CGI, just put the sample-project.fossil file in a directory where CGI scripts have both read and write permission on the file and the directory that contains the file, then add a CGI script that looks something like this: 

  #!/usr/local/bin/fossil
  repository: /home/www/sample-project.fossil

Adjust the script above so that the paths are correct for your system, of course, and also make sure the Fossil binary is installed on the server. But that is all you have to do. You now have everything you need to host a distributed software development project in less than five minutes using a two-line CGI script.

Instructions for setting up an SCGI server are available separately.

You don't have a CGI- or SCGI-capable web server running on your server machine? Not a problem. The Fossil interface can also be launched via inetd or xinetd. An inetd configuration line sufficient to launch the Fossil web interface looks like this: 

  80 stream tcp nowait.1000 root /usr/local/bin/fossil \
  /usr/local/bin/fossil http /home/www/sample-project.fossil

As always, you'll want to adjust the pathnames to whatever is appropriate for your system. The xinetd setup uses a different syntax but follows the same idea.