Fossil SCM

fossil-scm / www / server / any / scgi.md

Source Blame History 72 lines

f146e21…	drh	1	# Serving via SCGI
f146e21…	drh	2
f146e21…	drh	3	There is an alternative to running Fossil as a [standalone HTTP
f146e21…	drh	4	server](./none.md), which is to run it in SimpleCGI (a.k.a. SCGI) mode,
f146e21…	drh	5	which uses the same [`fossil server`](/help/server) command as for HTTP
f146e21…	drh	6	service. Simply add the `--scgi` command-line option and the stand-alone
f146e21…	drh	7	server will speak the SCGI protocol rather than raw HTTP.
f146e21…	drh	8
f146e21…	drh	9	This can be used with a web server such as [nginx](http://nginx.org)
f146e21…	drh	10	which does not support [Fossil’s CGI mode](./cgi.md).
f146e21…	drh	11
f146e21…	drh	12	A basic nginx configuration to support SCGI with Fossil looks like this:
f146e21…	drh	13
8a1ba49…	wyoung	14	location /code/ {
8a1ba49…	wyoung	15	include scgi_params;
8a1ba49…	wyoung	16	scgi_param SCRIPT_NAME "/code";
8a1ba49…	wyoung	17	scgi_pass localhost:9000;
8a1ba49…	wyoung	18	}
5a58ac3…	wyoung	19
5a58ac3…	wyoung	20	The `scgi_params` file comes with nginx, and it simply translates nginx
5a58ac3…	wyoung	21	internal variables to `scgi_param` directives to create SCGI environment
5a58ac3…	wyoung	22	variables for the proxied program; in this case, Fossil. Our explicit
5a58ac3…	wyoung	23	`scgi_param` call to define `SCRIPT_NAME` adds one more variable to this
5a58ac3…	wyoung	24	set, which is necessary for this configuration to work properly, because
5a58ac3…	wyoung	25	our repo isn’t at the root of the URL hierarchy. Without it, when Fossil
653e90c…	wyoung	26	generates absolute URLs, they’ll be missing the `/code` part at the
5a58ac3…	wyoung	27	start, which will typically cause [404 errors][404].
5a58ac3…	wyoung	28
5a58ac3…	wyoung	29	The final directive simply tells nginx to proxy all calls to URLs under
653e90c…	wyoung	30	`/code` down to an SCGI program on TCP port 9000. We can temporarily
5a58ac3…	wyoung	31	set Fossil up as a server on that port like so:
5a58ac3…	wyoung	32
8a1ba49…	wyoung	33	$ fossil server /path/to/repo.fossil --scgi --localhost --port 9000 &
f146e21…	drh	34
f146e21…	drh	35	The `--scgi` option switches Fossil into SCGI mode from its default,
f146e21…	drh	36	which is [stand-alone HTTP server mode](./none.md). All of the other
f146e21…	drh	37	options discussed in that linked document — such as the ability to serve
f146e21…	drh	38	a directory full of Fossil repositories rather than just a single
f146e21…	drh	39	repository — work the same way in SCGI mode.
f146e21…	drh	40
f146e21…	drh	41	The `--localhost` option is simply good security: we’re using nginx to
f146e21…	drh	42	expose Fossil service to the outside world, so there is no good reason
f146e21…	drh	43	to allow outsiders to contact this Fossil SCGI server directly.
f146e21…	drh	44
f146e21…	drh	45	Giving an explicit non-default TCP port number via `--port` is a good
f146e21…	drh	46	idea to avoid conflicts with use of Fossil’s default TCP service port,
f146e21…	drh	47	8080, which may conflict with local uses of `fossil ui` and such.
f146e21…	drh	48
5a58ac3…	wyoung	49	We characterized the SCGI service start command above as “temporary”
5a58ac3…	wyoung	50	because running Fossil in the background like that means it won’t start
5a58ac3…	wyoung	51	back up on a reboot of the server. A simple solution to that is to add
5a58ac3…	wyoung	52	that command to `/etc/rc.local` on systems that have it. However, you
5a58ac3…	wyoung	53	might want to consider setting Fossil up as an OS service instead, so
5a58ac3…	wyoung	54	that you get the benefits of the platform’s service management
5a58ac3…	wyoung	55	framework:
5a58ac3…	wyoung	56
5a58ac3…	wyoung	57	* [Linux (systemd)](../debian/service.md)
5a58ac3…	wyoung	58	* [Windows service](../windows/service.md)
5a58ac3…	wyoung	59	* [macOS (launchd)](../macos/service.md)
5a58ac3…	wyoung	60	* [xinetd](../any/xinetd.md)
5a58ac3…	wyoung	61	* [inetd](../any/inetd.md)
5a58ac3…	wyoung	62
5a58ac3…	wyoung	63	We go into more detail on nginx service setup with Fossil in our
780b58b…	wyoung	64	[Debian/Ubuntu specific guide](../debian/nginx.md), which also
780b58b…	wyoung	65	gets you TLS service.
311f169…	jamsek	66
0fd7302…	jamsek	67	Similarly, our [OpenBSD specific guide](../openbsd/fastcgi.md) details how
311f169…	jamsek	68	to setup a Fossil server using httpd and FastCGI on OpenBSD.
f146e21…	drh	69
f146e21…	drh	70	[Return to the top-level Fossil server article.](../)
5a58ac3…	wyoung	71
5a58ac3…	wyoung	72	[404]: https://en.wikipedia.org/wiki/HTTP_404

Fossil SCM

Keyboard Shortcuts