Fossil

Check-in [81932667]
Login

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

Overview
Comment:Renamed www/server.wiki to www/server/index.html and converted it to HTML format. Did a bit of prose polishing and CSS work while in there.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | server-docs
Files: files | file ages | folders
SHA3-256: 819326676390d2742a28314726c616503549a71fb60eab195f16ce10b3121515
User & Date: wyoung 2019-08-18 04:41:56
Context
2019-08-18
04:51
Moved inline CSS within www/server/index.html elements up into a <style> block at the top. Then used that to create a more even matrix layout. Also fixed some incorrect URLs checked in with the prior version, due to the document changing directory level. check-in: 648574cb user: wyoung tags: server-docs
04:41
Renamed www/server.wiki to www/server/index.html and converted it to HTML format. Did a bit of prose polishing and CSS work while in there. check-in: 81932667 user: wyoung tags: server-docs
04:12
Small improvements to IIS + CGI doc check-in: f7c839c1 user: wyoung tags: server-docs
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Name change from www/server.wiki to www/server/index.html.

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
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
81
82
...
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

163
164

165
166
167



<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>
  <li>Socket listener:
      <a id="inetd"   href="./server/any/inetd.md">inetd</a>,
      <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 with CGI underneath althttpd.

For web servers such as nginx that do not support CGI, Fossil supports
SCGI, a protocol that gives most of the simplicity of CGI with the
efficiency of the stand-alone server option. With nginx, you use the
[/help/server|fossil server] command with the --scgi option.

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>
        <th colspan="11" style="background-color: #efefef">Fossil Front-End Program</th>
    </tr>

................................................................................
        <td style="text-align: center">❌</td>
        <td style="text-align: center">❌</td>
        <td style="text-align: center"><a href="./server/windows/iis.md">✅</a></td>
        <td style="text-align: center"><a href="./server/windows/service.md">✅</a></td>
    </tr>
</table>

<blockquote>
Where there is a check mark in the "Any" row, the method for that is
generic enough that it works across OSes that Fossil is known to work
on. The check marks below that usually just link to this generic
documentation.

There are several widely-deployed socket listener schemes besides the
<tt>inetd</tt>, <tt>xinetd</tt>, and <tt>stunnel</tt> schemes with
documents linked above: Apple’s <tt>launchd</tt>, Linux’s
<tt>systemd</tt>, Solaris’ SMF, etc. We would welcome [./contribute.wiki
| contributions] to cover these as well. We also welcome contributions
to fill gaps (❌) in the table above.
</blockquote>


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



|

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>


<
|
|

|
|
|
<




<
|



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







 







<
|


|

|


|
|
|
<




|
|
>
|
<
>
|
<
|
>
>
>
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
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
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
...
163
164
165
166
167
168
169

170
171
172
173
174
175
176
177
178
179
180

181
182
183
184
185
186
187
188

189
190

191
192
193
194
<div class='fossil-doc' data-title="How To Configure A Fossil Server">

<style>
  p {
    margin-left: 3em;
    margin-right: 3em;
  }

  h2 {
    margin-left: 1em;
  }

  h3 {
    margin-left: 3em;
  }

  ol, ul {
    margin-left: 3em;
  }
</style>


<h2>No Server Required</h2>


<p>Fossil does not require a central server, but <a
href="whyuseaserver.wiki">a server can be very useful</a>.</p>

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



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


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

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

<p>All of these methods can serve either a single repository or a
directory hierarchy containing many repositories with names ending in
"<tt>.fossil</tt>".</p>

<p>You are not restricted to using a single method. The same Fossil
repository can be served using two or more of the above techniques at
the same time. You can also migrate from one method to another to
accommodate changes in hosting providers or administrator
preferences.</p>


<h3>Socket Listener</h3>

<p>The idea behind the socket listener approach is that each incoming
HTTP request is relayed to a new instance of the <a
href="/help?cmd=http"><tt>fossil http</tt></a> 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.</p>


<h3>Stand-alone HTTP Server</h3>

<p>A stand-alone server uses the <a href="/help?cmd=server"><tt>fossil
server</tt></a> 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.</p>


<h3>CGI and SCGI</h3>

<p>Fossil can also be run using CGI from ordinary web servers such as
Apache, <a href="windows/cgi.md">IIS</a>, <tt>lighttpd</tt>, or
<tt>althttpd</tt>. The Fossil server administrator places a <a
href="/help?cmd=cgi">short CGI script</a> in the web server's document
hierarchy, and when a client requests the appropriate URL, that script
runs Fossil to generate the responce.  CGI is a good choice for merging
Fossil into an existing web site. The Fossil <a
href="../selfhost.wiki">self-hosting repositories</a> are implemented
with CGI underneath <tt>althttpd</tt>.</p>

<p>For web servers such as nginx that do not support CGI, Fossil
supports SCGI, a protocol that gives most of the simplicity of CGI with
the efficiency of the stand-alone server option. With nginx, you use the
<a href="/help/server"><tt>fossil server --scgi</tt></a> command.</p>



<h2 id="matrix">Setup Tutorials</h2>

<p>We've broken the configuration for each method out into a series of
sub-articles. Some of these are generic, while others depend on
particular operating systems or front-end software:</p>

<table style="margin-left: 6em;">
    <tr>
        <th>&nbsp;</th>
        <th colspan="11" style="background-color: #efefef">Fossil Front-End Program</th>
    </tr>

................................................................................
        <td style="text-align: center">❌</td>
        <td style="text-align: center">❌</td>
        <td style="text-align: center"><a href="./server/windows/iis.md">✅</a></td>
        <td style="text-align: center"><a href="./server/windows/service.md">✅</a></td>
    </tr>
</table>


<p>Where there is a check mark in the "Any" row, the method for that is
generic enough that it works across OSes that Fossil is known to work
on. The check marks below that usually just link to this generic
documentation.</p>

<p>There are several widely-deployed socket listener schemes besides the
<tt>inetd</tt>, <tt>xinetd</tt>, and <tt>stunnel</tt> schemes with
documents linked above: Apple’s <tt>launchd</tt>, Linux’s
<tt>systemd</tt>, Solaris’ SMF, etc. We would welcome <a
href="contribute.wiki">contributions</a> to cover these as well. We also
welcome contributions to fill gaps () in the table above.  </p>



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

<ul>
  <li> <a id="chroot"   href="../chroot.md">The Server Chroot Jail</a>
  <li><a id="loadmgmt" href="../loadmgmt.md">Managing Server Load</a>
  <li><a id="tls"      href="../ssl.wiki">Securing a Repository with TLS</a>

  <li><a id="ext"      href="../serverext.wiki">CGI Server Extensions</a>
  <li><a id="about"    href="../aboutcgi.wiki">How CGI Works In Fossil</a>

  <li><a id="sync"     href="../sync.wiki">The Fossil Sync Protocol</a>
</ul>

</div>