initial commitHEADmaster

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>