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. On the other hand, 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.

NOTES:

1. The option "--port NNN" will start the server on port "NNN" instead of 8080.
2. If port 8080 is already being used (perhaps by another Fossil server), then Fossil will use the next available port number.
3. Starting either command from within an "open" Fossil checkout will start a server using the repository corresponding to the checkout.
4. This is an excellent option for quickly sharing with coworkers on a small network.
5. A huge advantage to this deployment scenario is that no special "root" or "administrator" access is required 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.

This 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 a ''CGI script''

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.

Securing a repository with SSL

Using either of the CGI script approaches, 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.