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