Fossil SCM

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

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button