5c65487c5f 2009-01-25 drh: <h1 align="center">The Fossil Web Interface</h1> 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: One of the innovative features of fossil is its built-in web interface. 5c65487c5f 2009-01-25 drh: This web interface provides everything you need to run a software 5c65487c5f 2009-01-25 drh: development project: 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: * [./bugtheory.wiki | Ticketing and bug tracking] 5c65487c5f 2009-01-25 drh: * [./wikitheory.wiki | Wiki] 5c65487c5f 2009-01-25 drh: * [./embeddeddoc.wiki | On-line documentation] 5c65487c5f 2009-01-25 drh: * Status information 5c65487c5f 2009-01-25 drh: * Timelines 5c65487c5f 2009-01-25 drh: * File and version lists and differences 5c65487c5f 2009-01-25 drh: * Historical change data 5c65487c5f 2009-01-25 drh: * Links to download historical versions as ZIP archives 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: You get all of this, and more, for free when you use fossil. 5c65487c5f 2009-01-25 drh: There are no extra programs to install or setup. 5c65487c5f 2009-01-25 drh: Everything you need is already pre-configured and built into the 5c65487c5f 2009-01-25 drh: self-contained, stand-alone fossil executable. 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: As an example of how useful this web interface can be, 5c65487c5f 2009-01-25 drh: the entire [./index.wiki | fossil website] (except for the 5c65487c5f 2009-01-25 drh: [http://www.fossil-scm.org/download.html | precompiled binary download page]), 5c65487c5f 2009-01-25 drh: including the document you are now reading, 5c65487c5f 2009-01-25 drh: is rendered using the stock fossil web interface, with no enhancements, 5c65487c5f 2009-01-25 drh: and little customization. 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: Note also that because fossil is a distribute system, you can run 5c65487c5f 2009-01-25 drh: the web interface on your local machine while off network (for example, 5c65487c5f 2009-01-25 drh: while on an airplane) including 5c65487c5f 2009-01-25 drh: making changes to wiki pages and/or trouble ticket, then synchronize with your 5c65487c5f 2009-01-25 drh: co-workers after you reconnect. 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: <h2>Drop-Dead Simple Startup</h2> 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: To start using the built-in fossil web interface on an existing fossil 5c65487c5f 2009-01-25 drh: repository, simply type this: 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: <b>fossil ui existing-repository.fossil</b> 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: Substitute the name of your repository, of course. 5c65487c5f 2009-01-25 drh: The "ui" command will start a webserver running (it figures out an 5c65487c5f 2009-01-25 drh: available TCP port to use on its own) and then automatically launches 5c65487c5f 2009-01-25 drh: your web browser to point at that server. If you run the "ui" command 5c65487c5f 2009-01-25 drh: from within an open check-out, you can omit the repository name: 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: <b>fossil ui</b> 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: The latter case is a very useful short-cut when you are working on a 5c65487c5f 2009-01-25 drh: fossil project and what to quickly do some work with the interface. 5c65487c5f 2009-01-25 drh: Notice that fossil automatically finds an unused TCP port to run the 5c65487c5f 2009-01-25 drh: server own and automatically points your web browser to the correct 5c65487c5f 2009-01-25 drh: URL. So there is never any fumbling around trying to find an open 5c65487c5f 2009-01-25 drh: port or to type arcane strings into your browser URL entry box. 5c65487c5f 2009-01-25 drh: The interface just pops right up, ready to run. 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: The fossil web interface is also very easy to setup and run on a 5c65487c5f 2009-01-25 drh: network server, as either a CGI program or from inetd. Details on how 5c65487c5f 2009-01-25 drh: to do that are described further below. 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: <h2>Things To Do Using The Web Interface</h2> 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: You can view <b>timelines</b> of changes to the project. The default 5c65487c5f 2009-01-25 drh: "Timeline" link on the menu bar takes you to a page that shows the 20 5c65487c5f 2009-01-25 drh: most recent check-ins, wiki page edits, and ticket/bug-report changes. 5c65487c5f 2009-01-25 drh: This gives a very useful snapshot of what has been happening lately on the 5c65487c5f 2009-01-25 drh: project. You can click to go further back in time, if needed. Or 5c65487c5f 2009-01-25 drh: follow hyperlinks to see details, including diffs and annotated diffs, 5c65487c5f 2009-01-25 drh: of individual check-ins, wiki page edits, or ticket changes. 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: You can view and edit <b>tickets and bug reports</b> by following the 5c65487c5f 2009-01-25 drh: "Tickets" link on the menu bar. 5c65487c5f 2009-01-25 drh: Fossil is backed by an SQL database, so users with appropriate permissions 5c65487c5f 2009-01-25 drh: can write new ticket report formats based on SQL query statements. 5c65487c5f 2009-01-25 drh: Fossil is careful to prevent ticket report formats from doing any mischief 5c65487c5f 2009-01-25 drh: on the database (it only allows SELECT statements to run) and it restricts 5c65487c5f 2009-01-25 drh: access to sensitive data such as user passwords. So it is actually safe 5c65487c5f 2009-01-25 drh: to let anonymous users on the internet write their own ticket formats if 5c65487c5f 2009-01-25 drh: you like. In addition to viewing and/or creating report formats, you can 5c65487c5f 2009-01-25 drh: also create new tickets or look at summaries or complete histories of 5c65487c5f 2009-01-25 drh: existing tickets. Any changes you make will automatically merge with 5c65487c5f 2009-01-25 drh: changes from your co-workers the next time your repository is synchronized. 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: You can view and edit <b>wiki</b> by following the "Wiki" link on the 5c65487c5f 2009-01-25 drh: menu bar. Fossil uses simple and easy-to-remember 5c65487c5f 2009-01-25 drh: [/wiki_rules | wiki formatting rules] so you won't have to spend a lot 5c65487c5f 2009-01-25 drh: of time learning a new markup language. And, as with tickets, all of 5c65487c5f 2009-01-25 drh: your edits will automatically merge with those of your co-workers when 5c65487c5f 2009-01-25 drh: your repository synchronizes. 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: You can view summary reports of <b>leaves and branches</b> in the 5c65487c5f 2009-01-25 drh: check-in graph by visiting the "Leaves" or "Branches" links on the 5c65487c5f 2009-01-25 drh: menu bar. From those pages you can follow hyperlinks to get additional 5c65487c5f 2009-01-25 drh: details. These screens allow you to easily keep track of what is going 5c65487c5f 2009-01-25 drh: on with separate subteams within your project team. 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: The "Files" link on the menu allows you to browse though the <b>file 5c65487c5f 2009-01-25 drh: hierarchy</b> of the project and to view complete changes histories on 5c65487c5f 2009-01-25 drh: individual files, with hyperlinks to the check-ins that made those 5c65487c5f 2009-01-25 drh: changes, and with diffs and annotated diffs between versions. 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: The web interface supports [./embeddeddoc.wiki | embedded documentation]. 5c65487c5f 2009-01-25 drh: Embedded documentation is documentation files (usually in wiki format) 5c65487c5f 2009-01-25 drh: that are checked into project as part of the source tree. Such files 5c65487c5f 2009-01-25 drh: can be viewed as if they were ordinary web pages. This document that 5c65487c5f 2009-01-25 drh: you are now reading is an example of embedded documentation. 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: <h2>Customizing The Web Interface Appearance</h2> 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: Users with appropriate permissions can customize the look and feel of 5c65487c5f 2009-01-25 drh: the web interface using the "Admin" link on the main menu of the web 5c65487c5f 2009-01-25 drh: interface. Templates 5c65487c5f 2009-01-25 drh: for the header and footer of each page can be edited, as can the CSS 5c65487c5f 2009-01-25 drh: for the entire page. You can even change around the main menu. 5c65487c5f 2009-01-25 drh: Timeline display preferences can be edited. The page that is brought 5c65487c5f 2009-01-25 drh: up as the "Home" page can be changed. It is often useful to set the 5c65487c5f 2009-01-25 drh: "Home" page to be a wiki page or an embedded document. 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: <h2>Installing On A Network Server</h2> 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: When you create a new fossil project and after you have configured it 5c65487c5f 2009-01-25 drh: like you want it using the web interface, you can make the project 5c65487c5f 2009-01-25 drh: available to a distributed team by simply copying the single 5c65487c5f 2009-01-25 drh: repository file up to a web server that supports CGI. Just put the 5c65487c5f 2009-01-25 drh: <b>sample-project.fossil</b> file in a directory where CGI scripts 5c65487c5f 2009-01-25 drh: have both read and write permission on the file and the directory that 5c65487c5f 2009-01-25 drh: contains the file, then add a CGI script that looks something like this: 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: <verbatim> 5c65487c5f 2009-01-25 drh: #!/usr/local/bin/fossil 5c65487c5f 2009-01-25 drh: repository: /home/www/sample-project.fossil 5c65487c5f 2009-01-25 drh: </verbatim> 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: Adjust the script above so that the paths are correct for your system, 5c65487c5f 2009-01-25 drh: of course, and also make sure the fossil binary is installed on the server. 5c65487c5f 2009-01-25 drh: But that is <u>all</u> you have to do. You now have everything you need to host 5c65487c5f 2009-01-25 drh: a distributed software development project in less than five minutes using a 5c65487c5f 2009-01-25 drh: two-line CGI script. 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: You don't have a CGI-capable web server running on your server machine? 5c65487c5f 2009-01-25 drh: Not a problem. The fossil interface can also be launched via inetd or 5c65487c5f 2009-01-25 drh: xinetd. An inetd configuration line sufficient to launch the fossil 5c65487c5f 2009-01-25 drh: web interface looks like this: 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: <verbatim> 5c65487c5f 2009-01-25 drh: 80 stream tcp nowait.1000 root /usr/local/bin/fossil \ 5c65487c5f 2009-01-25 drh: /usr/local/bin/fossil http /home/www/sample-project.fossil 5c65487c5f 2009-01-25 drh: </verbatim> 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: As always, you'll want to adjust the pathnames to whatever is appropriate 5c65487c5f 2009-01-25 drh: for your system. The xinetd setup uses a different syntax but follows 5c65487c5f 2009-01-25 drh: the same idea. 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: Once you have your new repository running on the network server, delete 5c65487c5f 2009-01-25 drh: the original repository from your local machine, then clone the repository 5c65487c5f 2009-01-25 drh: off of the server: 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: <b>fossil clone http://user:password@myserver.org/cgi-bin/my-project</b> 5c65487c5f 2009-01-25 drh: 5c65487c5f 2009-01-25 drh: (As always, adjust the URL as appropriate for your installation.) 5c65487c5f 2009-01-25 drh: After copying a repository, it is important to reclone it onto new machines. 5c65487c5f 2009-01-25 drh: Each repository has a random "repository ID" and repositories will not 5c65487c5f 2009-01-25 drh: sync with another repository having the same ID (to avoid sync loops). 5c65487c5f 2009-01-25 drh: Cloning the repository will give you a new repository ID in your local 5c65487c5f 2009-01-25 drh: copy and allow you to sync with the server.
File Annotation