Fossil

CGI mode.  The "index.html" CGI script looks like this:

<blockquote><pre>
#!/usr/bin/fossil
repository: /fossil/fossil.fossil
</pre></blockquote>

This is one of three ways to set up a 
<a href="quickstart.wiki#serversetup">fossil web server</a>.

The "<b>/trunk/</b>" part of the URL tells fossil to use
the documentation files from the most recent trunk check-in.
If you wanted to see an historical version of this document,
you could substitute the name of a check-in for "<b>/trunk/</b>".
For example, to see the version of this document associated with
check-in [9be1b00392], simply replace the "<b>/trunk/</b>" with

      Fossil uses plain old HTTP (with
      [./quickstart.wiki#proxy | proxy support])
      for all network communications, meaning that it works fine from behind
      restrictive firewalls.  The protocol is
      [./stats.wiki | bandwidth efficient] to the point that Fossil can be
      used comfortably over a dial-up internet connection.

  6.  <b>CGI and SCGI Enabled</b> -
      No server is required to use fossil.  But a
      server does make collaboration easier.  Fossil supports four different
      yet simple [./quickstart.wiki#serversetup | server configurations].
      The most popular is a 2-line CGI script.  This is the approach
      used by the [./selfhost.wiki | self-hosting fossil repositories].

  7.  <b>Robust &amp; Reliable</b> -
      Fossil stores content using an [./fileformat.wiki | enduring file format]
      in an SQLite database so that transactions are
      atomic even if interrupted by a power loss or system crash.  Furthermore,

    <p>This will back out the changes that the merge or update made to the
    working checkout.  There is also a [/help/redo|redo] command if you undo by
    mistake.  Undo and redo only work for changes that have
    not yet been checked in using commit and there is only a single
    level of undo/redo.</p>


<a name="serversetup"></a>
<h2>Setting Up A Server</h2>


    <p>The easiest way to set up a server is:</p>

    <blockquote>
    <b>[/help/server | fossil server]</b> <i>repository-filename</i>

    </blockquote>

    <p>Or</b>

    <blockquote>
    <b>[/help/ui | fossil ui]</b> <i>repository-filename</i>

    </blockquote>

    <p>The <b>ui</b> command is intended for accessing the web interface
    from a local desktop.  The <b>ui</b> command binds to the loopback IP
    address only (and thus makes the web interface visible only on the
    local machine) and it automatically start your web browser pointing at the
    server.  For cross-machine collaboration, use the <b>server</b> command,
    which binds on all IP addresses and does not try to start a web browser.
    You can omit the <i>repository-filename</i> if you are within
    a checked-out local tree.  The <b>server</b> uses port 8080 by default
    but you can specify a different port using the <b>-port</b> option.</p>

    <p>The same commands can be used with the --scgi option to run 
    [./scgi.wiki | SCGI] from Nginx, if desired.</p>

    <p>Command-line servers like this are useful when two people want
    to share a repository on temporary or ad-hoc basis.  For a more
    permanent installation, you should use either the CGI server or the
    inetd server.
    <a name="cgiserver"></a>
    To use the CGI server, create a CGI script that
    looks something like this:</p>

    <blockquote><b>
    #!/usr/local/bin/fossil<br>
    repository: /home/proj1/repos1.fossil
    </b></blockquote>

    <p>Adjust the paths in this CGI script to match your installation
    and make sure both repository file and the directory that contains it
    are readable and writable by the user that CGI scripts run as.
    Then point clients at the CGI script.  That's all there is to it!</p>

    <a name="inetdserver"></a>
    <p>You can also run fossil from inetd or xinetd.  For an inetd
    installation, make an entry in /etc/inetd.conf that looks something
    like this:</p>

    <blockquote><b>
    80 stream tcp nowait.1000 root /usr/bin/fossil \<br>
        /usr/bin/fossil http /home/proj1/repos1.fossil
    </b></blockquote>

    <p>Adjust the paths to suit your installation, of course.  Notice that
    fossil runs as root.  This is not required - you can run it as an
    unprivileged user.  But it is more secure to run fossil as root.
    When you do run fossil as root, it automatically puts itself in a
    chroot jail in the same directory as the repository, then drops
    root privileges prior to reading any information from the socket.</p>

<a name="proxy"></a>
<h2>HTTP Proxies</h2>

    <p>If you are behind a restrictive firewall that requires you to use
    an HTTP proxy to reach the internet, then you can configure the proxy
    in three different ways.  You can tell fossil about your proxy using

<title>How To Configure A Fossil Server</title>
<nowiki>
<p>This guide is intended to help guide you in setting up a Fossil server.</p>












<h2>Standalone server</h2><blockquote>
The easiest way to set up a Fossil server is to use the <tt>server</tt> or
<tt>ui</tt> command.  Assuming the repository you are interested in serving is
in the file "<tt>repo.fossil</tt>", you can use either of these commands to
start Fossil as a server:
<ul>
<li><b>fossil server repo.fossil</b>
<li><b>fossil ui repo.fossil</b>
</ul>

<p>


Both of these commands start a Fossil server on port 8080 on the local machine,

which can be accessed with the URL: <tt>http://localhost:8080/</tt> 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.
</p>

<p>
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.
</p>

<p>
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.
</p>

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

<h2>Fossil as an ''inetd'' service</h2><blockquote>
<p>


Modify your <tt>/etc/inetd.conf</tt> (on Linux, modify as appropriate for
your platform) so it contains a line like this:
<blockquote>
<pre>
12345 stream tcp nowait.1000 root /path-to/fossil /path-to/fossil http /other-path-to/repository
</pre>
</blockquote>
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.


</p>
<p>
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:</p>
<blockquote>
<pre>
service http-alt
{
  port = 591
  socket_type = stream
  wait = no
  user = root
  server = /usr/bin/fossil
  server_args = http /home/fossil/repos/
}
</pre>
</blockquote>
<p>
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.
</p>
<p>
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.
</p>
</blockquote>

<h2>Fossil as CGI</h2><blockquote>
<p>

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. 
</p>
</blockquote>

<h3>One script per repository</h3><blockquote>
<p>
Create a script (let's call it 'repo') in your CGI directory which has content
like this:
<blockquote><pre>
#!/path-to/fossil
repository: /path-to-repo/repository
</pre></blockquote>
</p>
<p>

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.
</p>
<p>
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:
<tt>http://mydomain.org/cgi-bin/repo</tt> (assuming the "repo" script is
accessible under "cgi-bin", which would be a typical deployment on Apache
for instance).
</p>
</blockquote>

<h3>Serving multiple repositories with one script</h3><blockquote>
<p>
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'):
<blockquote><pre>
#!/path-to/fossil
directory: /path-to-repo/fossils
notfound: http://url-to-go-to-if-repo-not-found/
</pre></blockquote>
</p>
<p>
Once deployed, a URL like: <tt>http://mydomain.org/cgi-bin/repo/XYZ</tt>
will serve up the repository "fossils/XYX.fossil" (if it exists).  This
makes serving multiple projects on one server pretty painless.
</p>
</blockquote>

<h2>Fossil as SCGI</h2><blockquote>

<p>
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:
<blockquote><pre>
location ~ ^/demo_project/ {
    include scgi_params;
    scgi_pass localhost:9000;
    scgi_param SCRIPT_NAME "/demo_project";
}
</pre></blockquote>
<p>
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.
</p>
<p>
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.

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.
</p>

</blockquote>

</nowiki>