Fossil

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

<style type="text/css">
  p {
    margin-left: 4em;
    margin-right: 3em;
  }

  li p {
    margin-left: 0;
  }

  h2 {
    margin-left: 1em;
  }

  h3 {
    margin-left: 3em;

and can run comfortably on a generic $5/month virtual host 
or on a small device like a RaspberryPI, 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 launching a server on a Fossil repository, it is best to
<p>Prior to serving a Fossil repository to others, consider running <a
prepare the repository to be served.  The easiest way to do this
is to run the <a href="$ROOT/help?cmd=ui"><tt>fossil ui</tt></a> command
href="$ROOT/help?cmd=ui"><tt>fossil ui</tt></a> locally and taking these
on a workstation and then visit the "Setup" menu.  
Minimum preparation actions include:</p>
minimum recommended preparation steps:</p>

<ol>
<li>
Ensure that you have an administrator user account and password
configured.  Visit the Setup/Users page to accomplish this.</p></li>
<li>
Visit the Setup/Security-Audit page to verify that other
security-related permissions and settings are as you want them.
You might want to configure the repository to be completely private
for the initial upload and server activatation, then open access up to
the public as part of the 
<a href="#postsetup">post-activation configuration refinement</a>
stage.
</p></li>
  <li><p>Fossil creates only one user in a <a
  href="$ROOT/help?cmd=new">new repository</a> and gives it the <a
  href="../admin-v-setup.md">all-powerful Setup capability</a>.  (“s”)
  The default random password for that user is fairly strong against
  remote attack, but because that user has so much power, you might want
  to give it an even 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>
Additional configuration can be accomplished after the server is up
<p>With the repository secured, it is safe to upload a copy of the
and running.  Once the preliminary configuration is completed
upload the repository database file to the server and proceed to
activate the server using one or more of the techniques described
in the next two sections.
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>

</p>

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

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

<ol>
  <li><a id="cgi"        href="any/cgi.md">CGI</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, additional configuration
<p>After the server is up and running, log into it as the Setup user and
fine-tuning can be accomplished by logging in as an administrator
and visiting the Setup menu.  Pay particular attention to the
"Setup/Security-Audit" page to ensure that you have not mistakenly
configured the server in a way that might expose information that you
want to keep private. Other post-activation steps include the following:</p>
visit the Admin menu to finish configuring that repository for
service:</p>

<ol>
  <li><p>Add user accounts for your other team members. Use the
  pre-defined user capabilities to define access policies rather than
  give out those same set of capabilities redundantly to each
<li>
Add additional users accounts so that all team members have appropriate
check-in and check-out access to the repository.</li>
<li>
Modify the look-and-feel of site by customizing the skin.
<li>
If the repository includes <a href="../embeddeddoc.wiki">embedded
documentation</a> then perhaps activate the search feature so that
visitors can do full-text search on your documentation.
<li>
Connect the repository to an email server so that it can send email
  user.</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?cmd=/timeline.rss">timeline RSS
  feed</a>.</p></li>

notifications of new check-ins or other repository activate.
<li>
Turn on the various logging features.
  <li><p>Turn on the various logging features.</p></li>
<li>
If you locked down the repository as completely private prior to
upload, you might want to open up access to the public once you get
everything working.  Or, keep the repository private, according to
your needs.
</ol>

<p>
After any signification configuration change, it is a good idea to
revisit the Setup/Security-Audit page just to double-check that you
have not created any security problems in your installation.
</p>
<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>