From 4f49b16079b27d7ce633619e4cddfdf2bffbc952 Mon Sep 17 00:00:00 2001 From: cashmere Date: Fri, 4 Sep 2026 09:05:24 +0200 Subject: initial commit --- www/server/index.html | 316 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 316 insertions(+) create mode 100644 www/server/index.html (limited to 'www/server/index.html') 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 @@ +
+ + + + +

No Server Required

+ +

Fossil does not require a central server, but a server can be useful.

+ +

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. + +

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.

+ + +

Repository Prep

+ +

Prior to serving a Fossil repository to others, consider running fossil ui locally and taking these +minimum recommended preparation steps:

+ +
    +

  1. Fossil creates only one user in a new repository and gives it the all-powerful Setup capability. + 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.

    2. + +

  2. 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.

    3. +
+ +

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 after +the server is running.

+ + +

Activation Methods

+ +

There are basically five ways to run a Fossil server:

+ +
    +
  1. CGI +
  2. Socket listener +
  3. Stand-alone HTTP server +
  4. SCGI +
  5. SSH +
+ +

All of these methods can serve either a single repository or a +directory hierarchy containing multiple repositories.

+ +

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.

+ +

CGI

+ +

Most ordinary web servers can run Fossil as a +CGI script. This method is known to work with Apache, +lighttpd, and althttpd. The Fossil server +administrator places a short CGI script 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.

+ +

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 self-hosting repositories are +implemented with CGI underneath althttpd.

+ +

Socket Listener

+ +

Socket listener daemons such as +inetd, xinetd, stunnel, launchd, and systemd +can be configured to invoke the the +fossil http command to handle +each incoming HTTP request. The "fossil http" 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 "fossil http" command for each HTTP request. +The socket listener daemon takes care of relaying content to and from +the client, and (in the case of stunnel) +handling TLS decryption and encryption. + +

Stand-alone HTTP Server

+ +

This is the easiest method. +A stand-alone server uses the +fossil server 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 +reverse proxy +layer between the clients and Fossil.

+ +

SCGI

+ +

The Fossil standalone server can also handle SCGI. +When the fossil server command is +run with the extra --scgi option, it listens for incoming +SCGI requests rather than HTTP requests. This allows Fossil to +respond to requests from web servers such as +nginx 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.

+ +

SSH

+ +

Fossil supports ssh:// URLs, but there are practical limitations with the default +behavior. You can get the full power of Fossil's RBAC +system over SSH with a bit of clever +configuration.

+ +

Activation Tutorials

+ +

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:

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
⇩ OS / Method ⇨directinetdstunnelCGISCGIFastCGIalthttpdproxyservice
Any✅✅✅✅✅❌✅❌❌
Debian/Ubuntu✅✅✅✅✅❌✅✅✅
macOS✅❌✅✅✅❌✅❌✅
OpenBSD✅❌✅✅✅✅✅❌✅
Windows✅❌✅✅❌❌❌✅✅
+ +

Where there is a check mark in the "Any" 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.

+ +

The method in the "proxy" column is for the platform's default +web server configured as a reverse proxy for +Fossil's built-in HTTP server: nginx, IIS, Apache, etc.

+ +

We welcome contributions to fill gaps +(❌) in the table above.

+ + + +

Post-Activation Configuration

+ +

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:

+ +
    +

  1. Add user accounts for your other team members. Use categories to define access policies + rather than redundantly give each new user the same individual capabilities.

    2. + +

  2. 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 our earlier advice to take the repository private + prior to setting up the server.

    3. + +

  3. Modify the repository's look and feel by customizing the skin.

    4. + +

  4. If the repository includes embedded documentation, consider + activating the search feature (Admin → Search) so that visitors can do + full-text search on your documentation.

    5. + +

  5. Now that others can be making changes to the repository, + consider monitoring them via email alerts + or the timeline RSS + feed.

    6. + +

  6. Turn on the various logging features.

    7. +
+ +

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.

+ + +

Further Details

+ + + +
-- cgit v1.3.1