Fossil

Check-in [5bb1e112]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:An attempt to make the main server.wiki page simpler and yet self-contained, all at once.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | server-docs
Files: files | file ages | folders
SHA3-256: 5bb1e1122849e86aca22a8b6c21156bda37c5783311c482d9ef3b73438f9ba71
User & Date: drh 2019-08-16 14:25:15
Context
2019-08-16
18:36
Added starting version of www/server/windows/iis.md, covering only the HTTP reverse proxying case. check-in: fbacfacf user: wyoung tags: server-docs
14:25
An attempt to make the main server.wiki page simpler and yet self-contained, all at once. check-in: 5bb1e112 user: drh tags: server-docs
12:53
Moved the chroot and loadmgmt sections of www/server.wiki into separate documents. This change also adds info on /proc to the chroot doc, which was missing in its prior server.wiki form. Also reduced a few other "details" sections of server.wiki to bullet points in the new "Further Details" list at the end of the document. check-in: 85eaffb6 user: wyoung tags: server-docs
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/server.wiki.

1
2
3
4
5
6
7
8
9
10
11
12
13



14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
..
39
40
41
42
43
44
45
46
47
48
49


50
51
52
53






54















55
56

57










58
59
60
61
62
63
64
...
143
144
145
146
147
148
149



<title>How To Configure A Fossil Server</title>

<h2>No Server Required</h2>

<blockquote>
Fossil does <em>not</em> require a central server.
Data sharing and synchronization can be entirely peer-to-peer.
Fossil uses [https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type|conflict-free replicated data types]
to ensure that (in the limit) all participating peers see the exact same content.
</blockquote>

<h2>But, A Server Can Be Useful</h2>




<blockquote>
Fossil does not require a server,
but a server does make collaboration easier.
A Fossil server also works well as a complete website for a project.
For example, the [https://www.fossil-scm.org/] website, including the
page you are now reading,
is just a Fossil server displaying the content of the
self-hosting repository for Fossil.

This article is a guide for setting up your own Fossil server.

See "[./aboutcgi.wiki|How CGI Works In Fossil]" for background
information on the underlying CGI technology.
See "[./sync.wiki|The Fossil Sync Protocol]" for information on the
wire protocol used for client/server communication.
</blockquote>

<h2 id="methods">Methods</h2>

<blockquote>
There are basically four ways to set up a Fossil server:

<ol>
................................................................................
      <a id="xinetd"  href="./server/any/xinetd.md">xinetd</a>,
      <a id="stunnel" href="./server/any/stunnel.md">stunnel</a>...
  <li><a id="standalone" href="./server/any/none.md">Stand-alone HTTP server</a>
  <li><a id="scgi" href="./server/any/scgi.md">SCGI</a>
  <li><a  id="cgi" href="./server/any/cgi.md">CGI</a>
</ol>

Fossil's HTTP server can be used standalone or you can put it behind
many different pieces of software via various proxying schemes: Apache,
nginx, HAProxy, stunnel (proxy mode), IIS... We cover some of those
options below.



The CGI option works with many different web servers: Apache, IIS,
<tt>lighttpd</tt>, <tt>althttpd</tt>... Where CGI doesn't work, SCGI
usually does instead, such as in nginx.






















Regardless of the method you choose, all can serve either a single repository
or a directory hierarchy containing many repositories with names ending in ".fossil".












We've broken the configuration for each method out into a series of
sub-articles, some of which are OS-specific:
</blockquote>

<table style="margin-left: 6em;">
    <tr>
        <th>&nbsp;</th>
................................................................................

<h2 id="more">Further Details</h2>

  *  <a name="chroot"></a>[./chroot.md | The Server Chroot Jail]
  *  <a name="loadmgmt"></a>[./loadmgmt.md | Managing Server Load]
  *  <a name="tls"></a>[./ssl.wiki | Securing a Repository with TLS]
  *  <a name="ext"></a>[./serverext.wiki | CGI Server Extensions]









|
<
<
<

<
<
>
>
>
|
<
<
<
<
<
<
<

<
<
<
<
<
<
<







 







|
|
|
|
>
>

<
<
|
>
>
>
>
>
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
|
>

>
>
>
>
>
>
>
>
>
>







 







>
>
>
1
2
3
4
5
6
7



8


9
10
11
12







13







14
15
16
17
18
19
20
..
23
24
25
26
27
28
29
30
31
32
33
34
35
36


37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
...
159
160
161
162
163
164
165
166
167
168
<title>How To Configure A Fossil Server</title>

<h2>No Server Required</h2>

<blockquote>
Fossil does <em>not</em> require a central server.
But, [./server/whyuseaserver.wiki|a server can be very useful].






This article is a quick-reference guide for setting up your own
Fossil server, with links to more detailed instructions specific
to particular systems, should you want extra help.
</blockquote>
















<h2 id="methods">Methods</h2>

<blockquote>
There are basically four ways to set up a Fossil server:

<ol>
................................................................................
      <a id="xinetd"  href="./server/any/xinetd.md">xinetd</a>,
      <a id="stunnel" href="./server/any/stunnel.md">stunnel</a>...
  <li><a id="standalone" href="./server/any/none.md">Stand-alone HTTP server</a>
  <li><a id="scgi" href="./server/any/scgi.md">SCGI</a>
  <li><a  id="cgi" href="./server/any/cgi.md">CGI</a>
</ol>

The idea behind the socket listener approach is that each incoming HTTP
request is relayed to a new instance of the
[/help?cmd=http|fossil http] command.  That command reads the HTTP
request from its standard input, handles the request, and writes a
complete and correct HTTP reply on standard output which is then
returned to the client.



A stand-alone server uses the
[/help?cmd=server|fossil server] command to run a process that
listens for incoming HTTP requests on a socket and then dispatches
a copy of itself to deal with each incoming request.  A
stand-alone server can talk directly with the client, or the
system can be configured with a reverse proxy in between the
client and Fossil.

Fossil can also be run using CGI from ordinary web servers
such as Apache, IIS, <tt>lighttpd</tt>, or <tt>althttpd</tt>.
A [/help?cmd=cgi|short CGI script] is placed in the document
hierarchy of the web server, and when a client requests the
appropriate URL, Fossil is run to generate the responce.
CGI is a good choice for incorporating Fossil as part of a
larger website.  The Fossil [./selfhost.wiki|self-hosting repositories]
are implemented CGI running behind althttpd.

For web servers such as Nginx that do not support
CGI, Fossil can be run using SCGI.  SCGI involves running
the [/help?cmd=http|fossil http] command with the --scgi
option.  SCGI is something of a cross between a stand-alone server
running behind a reverse proxy and an ordinary CGI server.

Regardless of the method you choose, all can serve either a single
repository or a directory hierarchy containing many repositories 
with names ending in ".fossil".

Note that a single project is not restricted to using a single
server setup method.  The same Fossil repository can be served
using two or more of the above techniques, at the same time.  And
the server setup can change over time, to accomodate changes
in hosting providers or administrator preferences.
</blockquote>

<h2 id="matrix">System-Specific Setup Tutorials</h2>

<blockquote>
We've broken the configuration for each method out into a series of
sub-articles, some of which are OS-specific:
</blockquote>

<table style="margin-left: 6em;">
    <tr>
        <th>&nbsp;</th>
................................................................................

<h2 id="more">Further Details</h2>

  *  <a name="chroot"></a>[./chroot.md | The Server Chroot Jail]
  *  <a name="loadmgmt"></a>[./loadmgmt.md | Managing Server Load]
  *  <a name="tls"></a>[./ssl.wiki | Securing a Repository with TLS]
  *  <a name="ext"></a>[./serverext.wiki | CGI Server Extensions]
  *  [./aboutcgi.wiki|How CGI Works In Fossil]
  *  See "[./sync.wiki|The Fossil Sync Protocol]" for information on the
     wire protocol used for syncing Fossil repositories.

Added www/server/whyuseaserver.wiki.

























































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
<title>Benefits Of A Fossil Server</title>

<h2>No Server Required</h2>

Fossil does <em>not</em> require a central server.
Data sharing and synchronization can be entirely peer-to-peer.
Fossil uses 
[https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type|conflict-free replicated data types]
to ensure that (in the limit) all participating peers see the same content.

<h2>But, A Server Can Be Useful</h2>

Fossil does not require a server, but a server can be very useful.
Here are a few reasons to set up a Fossil server for your project:

  1.  <b>A server gives developers a common point of rendezvous for
      syncing their work.</b><p>
      It is possible for developers to synchronous peer-to-peer but
      that requires the developers coordinate the sync, which in turn
      requires that the developers both want to sync at the same moment.
      A server aleviates this time dependency by allowing each developer
      to sync whenever it is convenient (for example, automatically syncing
      after each commit and before each update).  Developers all stay
      in sync with each other, without having to interrupt each other
      constantly to set up a peer-to-peer sync.

  2.  <b>A server works as a project website for non-developers.</b><p>
      Fossil does more than just version control.  It also supports
      trouble-tickets, and wiki, and a forum.  It shows the status
      of the project.  And the embedded documentation feature provides
      a great mechanism for providing only instructions.

  3.  <b>A server provides project leaders with up-to-date status.</b><p>
      Project coordinators and BDFLs can click on a link or two at the
      central Fossil server for a project, and quickly tell what is
      going on.  They can do this from anywhere, even from their phones,
      without needing to actually sync to the device they are using.

  4.  <b>A server provides automatic off-site backups.</b><p>
      A Fossil server is an automatic remote backup for all the work
      going into a project.  You can even set up multiple servers, at
      multiple sites, with automatic synchronization between them, for
      added redundancy.  Such a set up means that no work is lost due
      to a single machine failure.