|
1
|
<div class='fossil-doc' data-title="How To Configure A Fossil Server"> |
|
2
|
|
|
3
|
<style type="text/css"> |
|
4
|
.doc > .content th.fep { |
|
5
|
font-family: "Helvetica Neue", "Arial Narrow", "Myriad Pro", "Avenir Next Condensed"; |
|
6
|
font-stretch: condensed; |
|
7
|
min-width: 3em; |
|
8
|
padding: 0.4em; |
|
9
|
white-space: nowrap; |
|
10
|
} |
|
11
|
|
|
12
|
.doc > .content th.host { |
|
13
|
font-family: "Helvetica Neue", "Arial Narrow", "Myriad Pro", "Avenir Next Condensed"; |
|
14
|
font-stretch: condensed; |
|
15
|
padding: 0.4em; |
|
16
|
text-align: right; |
|
17
|
} |
|
18
|
|
|
19
|
.doc > .content td.doc { |
|
20
|
text-align: center; |
|
21
|
} |
|
22
|
</style> |
|
23
|
|
|
24
|
|
|
25
|
<h2>No Server Required</h2> |
|
26
|
|
|
27
|
<p>Fossil does not require a central server, but <a |
|
28
|
href="whyuseaserver.wiki">a server can be useful</a>.</p> |
|
29
|
|
|
30
|
<p>A Fossil server does not require much memory, CPU, or disk space |
|
31
|
and can run comfortably on a generic $5/month virtual host |
|
32
|
or on a small device like a Raspberry Pi, or it can co-exist |
|
33
|
on a host running other services without getting in the way. |
|
34
|
|
|
35
|
<p>This article is a quick-reference guide for setting up your own |
|
36
|
Fossil server, with links to more detailed instructions specific to |
|
37
|
particular systems, should you want extra help.</p> |
|
38
|
|
|
39
|
|
|
40
|
<h2 id="prep">Repository Prep</h2> |
|
41
|
|
|
42
|
<p>Prior to serving a Fossil repository to others, consider running <a |
|
43
|
href="$ROOT/help/ui"><tt>fossil ui</tt></a> locally and taking these |
|
44
|
minimum recommended preparation steps:</p> |
|
45
|
|
|
46
|
<ol> |
|
47
|
<li><p>Fossil creates only one user in a <a |
|
48
|
href="$ROOT/help/new">new repository</a> and gives it the <a |
|
49
|
href="../caps/admin-v-setup.md#apsu">all-powerful Setup capability</a>. |
|
50
|
The 10-digit random password generated for that user is fairly strong |
|
51
|
against remote attack, even without explicit password guess rate |
|
52
|
limiting, but because that user has so much power, you may want to |
|
53
|
give it a much stronger password under Admin → Users.</a></li> |
|
54
|
|
|
55
|
<li><p>Run the Admin → Security-Audit tool to verify that other |
|
56
|
security-related permissions and settings are as you want them. |
|
57
|
Consider clicking the “Take it private” link on that page to lock down |
|
58
|
the security on that site to a level appropriate to a private |
|
59
|
repository, even if you will eventually want some public service. It's |
|
60
|
better to start from a secure position and open up service |
|
61
|
feature-by-feature as necessary than it is to start from a fully open |
|
62
|
position and lock down features one by one to achieve a secure |
|
63
|
stance.</p></li> |
|
64
|
</ol> |
|
65
|
|
|
66
|
<p>With the repository secured, it is safe to upload a copy of the |
|
67
|
repository file to your server and proceed with server setup, below. |
|
68
|
Further configuration steps can wait until <a href="#postsetup">after |
|
69
|
the server is running</a>.</p> |
|
70
|
|
|
71
|
|
|
72
|
<h2 id="methods">Activation Methods</h2> |
|
73
|
|
|
74
|
<p>There are basically five ways to run a Fossil server:</p> |
|
75
|
|
|
76
|
<ol> |
|
77
|
<li><a href="any/cgi.md">CGI</a> |
|
78
|
<li><a href="#slist">Socket listener</a> |
|
79
|
<li><a href="any/none.md">Stand-alone HTTP server</a> |
|
80
|
<li><a href="any/scgi.md">SCGI</a> |
|
81
|
<li><a href="#ssh">SSH</a> |
|
82
|
</ol> |
|
83
|
|
|
84
|
<p>All of these methods can serve either a single repository or a |
|
85
|
directory hierarchy containing multiple repositories.</p> |
|
86
|
|
|
87
|
<p>You are not restricted to a single server setup. The same Fossil |
|
88
|
repository can be served using two or more of the above techniques at |
|
89
|
the same time. These methods use clean, well-defined, standard |
|
90
|
interfaces (CGI, SCGI, and HTTP) which allow you to easily migrate from |
|
91
|
one method to another in response to changes in hosting providers or |
|
92
|
administrator preferences.</p> |
|
93
|
|
|
94
|
<h3 id="cgi">CGI</h3> |
|
95
|
|
|
96
|
<p>Most ordinary web servers can <a href="any/cgi.md">run Fossil as a |
|
97
|
CGI script</a>. This method is known to work with Apache, |
|
98
|
<tt>lighttpd</tt>, and <a |
|
99
|
href="any/althttpd.md"><tt>althttpd</tt></a>. The Fossil server |
|
100
|
administrator places a <a href="$ROOT/help/cgi">short CGI script</a> in |
|
101
|
the web server's document hierarchy and when a client requests the URL |
|
102
|
that corresponds to that script, Fossil runs and generates the |
|
103
|
response.</p> |
|
104
|
|
|
105
|
<p>CGI is a good choice for merging Fossil into an existing web site, |
|
106
|
particularly on hosts that have CGI set up and working. |
|
107
|
The Fossil <a href="../selfhost.wiki">self-hosting repositories</a> are |
|
108
|
implemented with CGI underneath <tt>althttpd</tt>.</p> |
|
109
|
|
|
110
|
<h3 id="slist">Socket Listener</h3> |
|
111
|
|
|
112
|
<p>Socket listener daemons such as |
|
113
|
<a id="inetd" href="any/inetd.md"><tt>inetd</tt></a>, <a id="xinetd" |
|
114
|
href="any/xinetd.md"><tt>xinetd</tt></a>, <a id="stunnel" |
|
115
|
href="any/stunnel.md"><tt>stunnel</tt></a>, <a |
|
116
|
href="macos/service.md"><tt>launchd</tt></a>, and <a |
|
117
|
href="debian/service.md"><tt>systemd</tt></a> |
|
118
|
can be configured to invoke the the |
|
119
|
<a href="$ROOT/help/http"><tt>fossil http</tt></a> command to handle |
|
120
|
each incoming HTTP request. The "<tt>fossil http</tt>" command reads |
|
121
|
the HTTP request off of standard input, computes an appropriate |
|
122
|
reply, and writes the reply on standard output. There is a separate |
|
123
|
invocation of the "<tt>fossil http</tt>" command for each HTTP request. |
|
124
|
The socket listener daemon takes care of relaying content to and from |
|
125
|
the client, and (in the case of <a href="any/stunnel.md">stunnel</a>) |
|
126
|
handling TLS decryption and encryption. |
|
127
|
|
|
128
|
<h3 id="standalone">Stand-alone HTTP Server</h3> |
|
129
|
|
|
130
|
<p>This is the <a href="any/none.md">easiest method</a>. |
|
131
|
A stand-alone server uses the |
|
132
|
<a href="$ROOT/help/server"><tt>fossil server</tt></a> command to run a |
|
133
|
process that listens for incoming HTTP requests on a socket and then |
|
134
|
dispatches a copy of itself to deal with each incoming request. You can |
|
135
|
expose Fossil directly to the clients in this way or you can interpose a |
|
136
|
<a href="https://en.wikipedia.org/wiki/Reverse_proxy">reverse proxy</a> |
|
137
|
layer between the clients and Fossil.</p> |
|
138
|
|
|
139
|
<h3 id="scgi">SCGI</h3> |
|
140
|
|
|
141
|
<p>The Fossil standalone server can also handle <a href="any/scgi.md">SCGI</a>. |
|
142
|
When the <a href="$ROOT/help/server"><tt>fossil server</tt></a> command is |
|
143
|
run with the extra <tt>--scgi</tt> option, it listens for incoming |
|
144
|
SCGI requests rather than HTTP requests. This allows Fossil to |
|
145
|
respond to requests from web servers <a href="debian/nginx.md">such as |
|
146
|
nginx</a> that don't support CGI. SCGI is a simpler protocol to proxy |
|
147
|
than HTTP, since the HTTP doesn't have to be re-interpreted in terms of |
|
148
|
the proxy's existing HTTP implementation, but it's more complex to set |
|
149
|
up because you also have to set up an SCGI-to-HTTP proxy for it. It is |
|
150
|
worth taking on this difficulty only when you need to integrate Fossil |
|
151
|
into an existing web site already being served by an SCGI-capable web |
|
152
|
server.</p> |
|
153
|
|
|
154
|
<h3 id="ssh">SSH</h3> |
|
155
|
|
|
156
|
<p>Fossil supports <tt>ssh://</tt> URLs, but there are <a |
|
157
|
href="../caps/#webonly">practical limitations</a> with the default |
|
158
|
behavior. You can get the full power of <a href="../caps/">Fossil's RBAC |
|
159
|
system</a> over SSH <a href="any/http-over-ssh.md">with a bit of clever |
|
160
|
configuration</a>.</p> |
|
161
|
|
|
162
|
<h2 id="matrix">Activation Tutorials</h2> |
|
163
|
|
|
164
|
<p>We've broken the configuration for each method out into a series of |
|
165
|
sub-articles. Some of these are generic, while others depend on |
|
166
|
particular operating systems or front-end software:</p> |
|
167
|
|
|
168
|
<div class="indent"><table> |
|
169
|
<tr> |
|
170
|
<th class="host">⇩ OS / Method ⇨</th> |
|
171
|
<th class="fep">direct</th> |
|
172
|
<th class="fep">inetd</th> |
|
173
|
<th class="fep">stunnel</th> |
|
174
|
<th class="fep">CGI</th> |
|
175
|
<th class="fep">SCGI</th> |
|
176
|
<th class="fep">FastCGI</th> |
|
177
|
<th class="fep">althttpd</th> |
|
178
|
<th class="fep">proxy</th> |
|
179
|
<th class="fep">service</th> |
|
180
|
</tr> |
|
181
|
|
|
182
|
<tr> |
|
183
|
<th class="host"><a href="any/">Any</a></th> |
|
184
|
<td class="doc"><a href="any/none.md">✅</a></td> |
|
185
|
<td class="doc"><a href="any/inetd.md">✅</a></td> |
|
186
|
<td class="doc"><a href="any/stunnel.md">✅</a></td> |
|
187
|
<td class="doc"><a href="any/cgi.md">✅</a></td> |
|
188
|
<td class="doc"><a href="any/scgi.md">✅</a></td> |
|
189
|
<td class="doc">❌</td> |
|
190
|
<td class="doc"><a href="any/althttpd.md">✅</a></td> |
|
191
|
<td class="doc">❌</td> |
|
192
|
<td class="doc">❌</td> |
|
193
|
</tr> |
|
194
|
|
|
195
|
<tr> |
|
196
|
<th class="host"><a href="debian/">Debian/Ubuntu</a></th> |
|
197
|
<td class="doc"><a href="any/none.md">✅</a></td> |
|
198
|
<td class="doc"><a href="any/inetd.md">✅</a></td> |
|
199
|
<td class="doc"><a href="any/stunnel.md">✅</a></td> |
|
200
|
<td class="doc"><a href="any/cgi.md">✅</a></td> |
|
201
|
<td class="doc"><a href="any/scgi.md">✅</a></td> |
|
202
|
<td class="doc">❌</td> |
|
203
|
<td class="doc"><a href="any/althttpd.md">✅</a></td> |
|
204
|
<td class="doc"><a href="debian/nginx.md">✅</a></td> |
|
205
|
<td class="doc"><a href="debian/service.md">✅</a></td> |
|
206
|
</tr> |
|
207
|
|
|
208
|
<tr> |
|
209
|
<th class="host"><a href="macos/">macOS</a></th> |
|
210
|
<td class="doc"><a href="any/none.md">✅</a></td> |
|
211
|
<td class="doc">❌</td> |
|
212
|
<td class="doc"><a href="any/stunnel.md">✅</a></td> |
|
213
|
<td class="doc"><a href="any/cgi.md">✅</a></td> |
|
214
|
<td class="doc"><a href="any/scgi.md">✅</a></td> |
|
215
|
<td class="doc">❌</td> |
|
216
|
<td class="doc"><a href="any/althttpd.md">✅</a></td> |
|
217
|
<td class="doc">❌</td> |
|
218
|
<td class="doc"><a href="macos/service.md">✅</a></td> |
|
219
|
</tr> |
|
220
|
|
|
221
|
<tr> |
|
222
|
<th class="host"><a href="openbsd/">OpenBSD</a></th> |
|
223
|
<td class="doc"><a href="any/none.md">✅</a></td> |
|
224
|
<td class="doc">❌</td> |
|
225
|
<td class="doc"><a href="any/stunnel.md">✅</a></td> |
|
226
|
<td class="doc"><a href="any/cgi.md">✅</a></td> |
|
227
|
<td class="doc"><a href="any/scgi.md">✅</a></td> |
|
228
|
<td class="doc"><a href="openbsd/fastcgi.md">✅</a></td> |
|
229
|
<td class="doc"><a href="any/althttpd.md">✅</a></td> |
|
230
|
<td class="doc">❌</td> |
|
231
|
<td class="doc"><a href="openbsd/service.wiki">✅</a></td> |
|
232
|
</tr> |
|
233
|
|
|
234
|
<tr> |
|
235
|
<th class="host"><a href="windows/">Windows</a></th> |
|
236
|
<td class="doc"><a href="windows/none.md">✅</a></td> |
|
237
|
<td class="doc">❌</td> |
|
238
|
<td class="doc"><a href="windows/stunnel.md">✅</a></td> |
|
239
|
<td class="doc"><a href="windows/cgi.md">✅</a></td> |
|
240
|
<td class="doc">❌</td> |
|
241
|
<td class="doc">❌</td> |
|
242
|
<td class="doc">❌</td> |
|
243
|
<td class="doc"><a href="windows/iis.md">✅</a></td> |
|
244
|
<td class="doc"><a href="windows/service.md">✅</a></td> |
|
245
|
</tr> |
|
246
|
</table></div> |
|
247
|
|
|
248
|
<p>Where there is a check mark in the "<b>Any</b>" row, the method for that is |
|
249
|
generic enough that it works across OSes that Fossil is known to work |
|
250
|
on. The check marks below that usually just link to this generic |
|
251
|
documentation.</p> |
|
252
|
|
|
253
|
<p>The method in the "<b>proxy</b>" column is for the platform's default |
|
254
|
web server configured as a <a |
|
255
|
href="https://en.wikipedia.org/wiki/Reverse_proxy">reverse proxy</a> for |
|
256
|
Fossil's built-in HTTP server: <a href="debian/nginx.md">nginx</a>, <a |
|
257
|
href="windows/iis.md">IIS</a>, Apache, etc.</p> |
|
258
|
|
|
259
|
<p>We welcome <a href="../contribute.wiki">contributions</a> to fill gaps |
|
260
|
(<font size="-2">❌</font>) in the table above.</p> |
|
261
|
</noscript> |
|
262
|
|
|
263
|
|
|
264
|
<h2 id="postsetup">Post-Activation Configuration</h2> |
|
265
|
|
|
266
|
<p>After the server is up and running, log into it as the Setup user and |
|
267
|
visit the Admin menu to finish configuring that repository for |
|
268
|
service:</p> |
|
269
|
|
|
270
|
<ol> |
|
271
|
<li><p>Add user accounts for your other team members. Use <a |
|
272
|
href="../caps/index.md#ucat">categories</a> to define access policies |
|
273
|
rather than redundantly give each new user the same <a |
|
274
|
href="../caps/index.md#ucap">individual capabilities</a>.</p></li> |
|
275
|
|
|
276
|
<li><p>Test access to the repository from each category of non-Setup |
|
277
|
user that you created. You may have to give your user categories some |
|
278
|
overlooked capabilities, particularly if you followed <a |
|
279
|
href="#prep">our earlier advice</a> to take the repository private |
|
280
|
prior to setting up the server.</p></li> |
|
281
|
|
|
282
|
<li><p>Modify the repository's look and feel by <a |
|
283
|
href="../customskin.md">customizing the skin</a>.</p></li> |
|
284
|
|
|
285
|
<li><p>If the repository includes <a |
|
286
|
href="../embeddeddoc.wiki">embedded documentation</a>, consider |
|
287
|
activating the search feature (Admin → Search) so that visitors can do |
|
288
|
full-text search on your documentation.</p></li> |
|
289
|
|
|
290
|
<li><p>Now that others can be making changes to the repository, |
|
291
|
consider monitoring them via <a href="../alerts.md">email alerts</a> |
|
292
|
or the <a href="$ROOT/help/www/timeline.rss">timeline RSS |
|
293
|
feed</a>.</p></li> |
|
294
|
|
|
295
|
<li><p>Turn on the various logging features.</p></li> |
|
296
|
</ol> |
|
297
|
|
|
298
|
<p>Reload the Admin → Security-Audit page occasionally during this |
|
299
|
process to double check that you have not mistakenly configured the |
|
300
|
server in a way that might expose information that you want to keep |
|
301
|
private.</p> |
|
302
|
|
|
303
|
|
|
304
|
<h2 id="more">Further Details</h2> |
|
305
|
|
|
306
|
<ul> |
|
307
|
<li><a id="chroot" href="../chroot.md" >The Server Chroot Jail</a> |
|
308
|
<li><a id="loadmgmt" href="../loadmgmt.md" >Managing Server Load</a> |
|
309
|
<li><a id="bkofc" href="../backoffice.md" >The Backoffice</a> |
|
310
|
<li><a id="tls" href="../ssl.wiki" >Securing a Repository with TLS</a> |
|
311
|
<li><a id="ext" href="../serverext.wiki">CGI Server Extensions</a> |
|
312
|
<li><a id="about" href="../aboutcgi.wiki" >How CGI Works In Fossil</a> |
|
313
|
<li><a id="sync" href="../sync.wiki" >The Fossil Sync Protocol</a> |
|
314
|
</ul> |
|
315
|
|
|
316
|
</div> |
|
317
|
|