diff options
Diffstat (limited to 'www/server/index.html')
| -rw-r--r-- | www/server/index.html | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/www/server/index.html b/www/server/index.html new file mode 100644 index 0000000..c15d42f --- /dev/null +++ b/www/server/index.html @@ -0,0 +1,316 @@ +<div class='fossil-doc' data-title="How To Configure A Fossil Server"> + +<style type="text/css"> + .doc > .content th.fep { + font-family: "Helvetica Neue", "Arial Narrow", "Myriad Pro", "Avenir Next Condensed"; + font-stretch: condensed; + min-width: 3em; + padding: 0.4em; + white-space: nowrap; + } + + .doc > .content th.host { + font-family: "Helvetica Neue", "Arial Narrow", "Myriad Pro", "Avenir Next Condensed"; + font-stretch: condensed; + padding: 0.4em; + text-align: right; + } + + .doc > .content td.doc { + text-align: center; + } +</style> + + +<h2>No Server Required</h2> + +<p>Fossil does not require a central server, but <a +href="whyuseaserver.wiki">a server can be useful</a>.</p> + +<p>A Fossil server does not require much memory, CPU, or disk space +and can run comfortably on a generic $5/month virtual host +or on a small device like a Raspberry Pi, or it can co-exist +on a host running other services without getting in the way. + +<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="prep">Repository Prep</h2> + +<p>Prior to serving a Fossil repository to others, consider running <a +href="$ROOT/help/ui"><tt>fossil ui</tt></a> locally and taking these +minimum recommended preparation steps:</p> + +<ol> + <li><p>Fossil creates only one user in a <a + href="$ROOT/help/new">new repository</a> and gives it the <a + href="../caps/admin-v-setup.md#apsu">all-powerful Setup capability</a>. + The 10-digit random password generated for that user is fairly strong + against remote attack, even without explicit password guess rate + limiting, but because that user has so much power, you may want to + give it a much stronger password under Admin → Users.</a></li> + + <li><p>Run the Admin → Security-Audit tool to verify that other + security-related permissions and settings are as you want them. + Consider clicking the “Take it private” link on that page to lock down + the security on that site to a level appropriate to a private + repository, even if you will eventually want some public service. It's + better to start from a secure position and open up service + feature-by-feature as necessary than it is to start from a fully open + position and lock down features one by one to achieve a secure + stance.</p></li> +</ol> + +<p>With the repository secured, it is safe to upload a copy of the +repository file to your server and proceed with server setup, below. +Further configuration steps can wait until <a href="#postsetup">after +the server is running</a>.</p> + + +<h2 id="methods">Activation Methods</h2> + +<p>There are basically five ways to run a Fossil server:</p> + +<ol> + <li><a href="any/cgi.md">CGI</a> + <li><a href="#slist">Socket listener</a> + <li><a href="any/none.md">Stand-alone HTTP server</a> + <li><a href="any/scgi.md">SCGI</a> + <li><a href="#ssh">SSH</a> +</ol> + +<p>All of these methods can serve either a single repository or a +directory hierarchy containing multiple repositories.</p> + +<p>You are not restricted to a single server setup. The same Fossil +repository can be served using two or more of the above techniques at +the same time. These methods use clean, well-defined, standard +interfaces (CGI, SCGI, and HTTP) which allow you to easily migrate from +one method to another in response to changes in hosting providers or +administrator preferences.</p> + +<h3 id="cgi">CGI</h3> + +<p>Most ordinary web servers can <a href="any/cgi.md">run Fossil as a +CGI script</a>. This method is known to work with Apache, +<tt>lighttpd</tt>, and <a +href="any/althttpd.md"><tt>althttpd</tt></a>. The Fossil server +administrator places a <a href="$ROOT/help/cgi">short CGI script</a> in +the web server's document hierarchy and when a client requests the URL +that corresponds to that script, Fossil runs and generates the +response.</p> + +<p>CGI is a good choice for merging Fossil into an existing web site, +particularly on hosts that have CGI set up and working. +The Fossil <a href="../selfhost.wiki">self-hosting repositories</a> are +implemented with CGI underneath <tt>althttpd</tt>.</p> + +<h3 id="slist">Socket Listener</h3> + +<p>Socket listener daemons such as +<a id="inetd" href="any/inetd.md"><tt>inetd</tt></a>, <a id="xinetd" +href="any/xinetd.md"><tt>xinetd</tt></a>, <a id="stunnel" +href="any/stunnel.md"><tt>stunnel</tt></a>, <a +href="macos/service.md"><tt>launchd</tt></a>, and <a +href="debian/service.md"><tt>systemd</tt></a> +can be configured to invoke the the +<a href="$ROOT/help/http"><tt>fossil http</tt></a> command to handle +each incoming HTTP request. The "<tt>fossil http</tt>" command reads +the HTTP request off of standard input, computes an appropriate +reply, and writes the reply on standard output. There is a separate +invocation of the "<tt>fossil http</tt>" command for each HTTP request. +The socket listener daemon takes care of relaying content to and from +the client, and (in the case of <a href="any/stunnel.md">stunnel</a>) +handling TLS decryption and encryption. + +<h3 id="standalone">Stand-alone HTTP Server</h3> + +<p>This is the <a href="any/none.md">easiest method</a>. +A stand-alone server uses the +<a href="$ROOT/help/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. You can +expose Fossil directly to the clients in this way or you can interpose a +<a href="https://en.wikipedia.org/wiki/Reverse_proxy">reverse proxy</a> +layer between the clients and Fossil.</p> + +<h3 id="scgi">SCGI</h3> + +<p>The Fossil standalone server can also handle <a href="any/scgi.md">SCGI</a>. +When the <a href="$ROOT/help/server"><tt>fossil server</tt></a> command is +run with the extra <tt>--scgi</tt> option, it listens for incoming +SCGI requests rather than HTTP requests. This allows Fossil to +respond to requests from web servers <a href="debian/nginx.md">such as +nginx</a> that don't support CGI. SCGI is a simpler protocol to proxy +than HTTP, since the HTTP doesn't have to be re-interpreted in terms of +the proxy's existing HTTP implementation, but it's more complex to set +up because you also have to set up an SCGI-to-HTTP proxy for it. It is +worth taking on this difficulty only when you need to integrate Fossil +into an existing web site already being served by an SCGI-capable web +server.</p> + +<h3 id="ssh">SSH</h3> + +<p>Fossil supports <tt>ssh://</tt> URLs, but there are <a +href="../caps/#webonly">practical limitations</a> with the default +behavior. You can get the full power of <a href="../caps/">Fossil's RBAC +system</a> over SSH <a href="any/http-over-ssh.md">with a bit of clever +configuration</a>.</p> + +<h2 id="matrix">Activation 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> + +<div class="indent"><table> + <tr> + <th class="host">⇩ OS / Method ⇨</th> + <th class="fep">direct</th> + <th class="fep">inetd</th> + <th class="fep">stunnel</th> + <th class="fep">CGI</th> + <th class="fep">SCGI</th> + <th class="fep">FastCGI</th> + <th class="fep">althttpd</th> + <th class="fep">proxy</th> + <th class="fep">service</th> + </tr> + + <tr> + <th class="host"><a href="any/">Any</a></th> + <td class="doc"><a href="any/none.md">✅</a></td> + <td class="doc"><a href="any/inetd.md">✅</a></td> + <td class="doc"><a href="any/stunnel.md">✅</a></td> + <td class="doc"><a href="any/cgi.md">✅</a></td> + <td class="doc"><a href="any/scgi.md">✅</a></td> + <td class="doc">❌</td> + <td class="doc"><a href="any/althttpd.md">✅</a></td> + <td class="doc">❌</td> + <td class="doc">❌</td> + </tr> + + <tr> + <th class="host"><a href="debian/">Debian/Ubuntu</a></th> + <td class="doc"><a href="any/none.md">✅</a></td> + <td class="doc"><a href="any/inetd.md">✅</a></td> + <td class="doc"><a href="any/stunnel.md">✅</a></td> + <td class="doc"><a href="any/cgi.md">✅</a></td> + <td class="doc"><a href="any/scgi.md">✅</a></td> + <td class="doc">❌</td> + <td class="doc"><a href="any/althttpd.md">✅</a></td> + <td class="doc"><a href="debian/nginx.md">✅</a></td> + <td class="doc"><a href="debian/service.md">✅</a></td> + </tr> + + <tr> + <th class="host"><a href="macos/">macOS</a></th> + <td class="doc"><a href="any/none.md">✅</a></td> + <td class="doc">❌</td> + <td class="doc"><a href="any/stunnel.md">✅</a></td> + <td class="doc"><a href="any/cgi.md">✅</a></td> + <td class="doc"><a href="any/scgi.md">✅</a></td> + <td class="doc">❌</td> + <td class="doc"><a href="any/althttpd.md">✅</a></td> + <td class="doc">❌</td> + <td class="doc"><a href="macos/service.md">✅</a></td> + </tr> + + <tr> + <th class="host"><a href="openbsd/">OpenBSD</a></th> + <td class="doc"><a href="any/none.md">✅</a></td> + <td class="doc">❌</td> + <td class="doc"><a href="any/stunnel.md">✅</a></td> + <td class="doc"><a href="any/cgi.md">✅</a></td> + <td class="doc"><a href="any/scgi.md">✅</a></td> + <td class="doc"><a href="openbsd/fastcgi.md">✅</a></td> + <td class="doc"><a href="any/althttpd.md">✅</a></td> + <td class="doc">❌</td> + <td class="doc"><a href="openbsd/service.wiki">✅</a></td> + </tr> + + <tr> + <th class="host"><a href="windows/">Windows</a></th> + <td class="doc"><a href="windows/none.md">✅</a></td> + <td class="doc">❌</td> + <td class="doc"><a href="windows/stunnel.md">✅</a></td> + <td class="doc"><a href="windows/cgi.md">✅</a></td> + <td class="doc">❌</td> + <td class="doc">❌</td> + <td class="doc">❌</td> + <td class="doc"><a href="windows/iis.md">✅</a></td> + <td class="doc"><a href="windows/service.md">✅</a></td> + </tr> +</table></div> + +<p>Where there is a check mark in the "<b>Any</b>" 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>The method in the "<b>proxy</b>" column is for the platform's default +web server configured as a <a +href="https://en.wikipedia.org/wiki/Reverse_proxy">reverse proxy</a> for +Fossil's built-in HTTP server: <a href="debian/nginx.md">nginx</a>, <a +href="windows/iis.md">IIS</a>, Apache, etc.</p> + +<p>We welcome <a href="../contribute.wiki">contributions</a> to fill gaps +(<font size="-2">❌</font>) in the table above.</p> +</noscript> + + +<h2 id="postsetup">Post-Activation Configuration</h2> + +<p>After the server is up and running, log into it as the Setup user and +visit the Admin menu to finish configuring that repository for +service:</p> + +<ol> + <li><p>Add user accounts for your other team members. Use <a + href="../caps/index.md#ucat">categories</a> to define access policies + rather than redundantly give each new user the same <a + href="../caps/index.md#ucap">individual capabilities</a>.</p></li> + + <li><p>Test access to the repository from each category of non-Setup + user that you created. You may have to give your user categories some + overlooked capabilities, particularly if you followed <a + href="#prep">our earlier advice</a> to take the repository private + prior to setting up the server.</p></li> + + <li><p>Modify the repository's look and feel by <a + href="../customskin.md">customizing the skin</a>.</p></li> + + <li><p>If the repository includes <a + href="../embeddeddoc.wiki">embedded documentation</a>, consider + activating the search feature (Admin → Search) so that visitors can do + full-text search on your documentation.</p></li> + + <li><p>Now that others can be making changes to the repository, + consider monitoring them via <a href="../alerts.md">email alerts</a> + or the <a href="$ROOT/help/www/timeline.rss">timeline RSS + feed</a>.</p></li> + + <li><p>Turn on the various logging features.</p></li> +</ol> + +<p>Reload the Admin → Security-Audit page occasionally during this +process to double check that you have not mistakenly configured the +server in a way that might expose information that you want to keep +private.</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="bkofc" href="../backoffice.md" >The Backoffice</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> |