Fossil

Check-in [5a58ac31]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Clarified use of scgi_params, SCRIPT_NAME, and service starting in the generic SCGI server setup doc.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 5a58ac3141612f2638d3d02f7d32281851782042852d944220c7c8961820687f
User & Date: wyoung 2019-08-25 11:52:21.457
Context
2019-08-25
12:29
Swapped the simple foo.net "whole site is Fossil" example in www/server/debian/nginx.md for the more complicated example.com one where only /code is served by Fossil. This is probably going to be more common, and it shows off the important detail of setting SCRIPT_NAME properly. Made a minor adjustment to any/scgi.md to track this change, so there is not a pointless difference between these two nginx configs. ... (check-in: 653e90ca user: wyoung tags: trunk)
11:52
Clarified use of scgi_params, SCRIPT_NAME, and service starting in the generic SCGI server setup doc. ... (check-in: 5a58ac31 user: wyoung tags: trunk)
2019-08-24
18:32
Merge fork ... (check-in: 6c6aae97 user: andygoth tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to www/server/any/scgi.md.
︙︙
9
10
11
12
13
14
15
16
17
18
19
20








21



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

45

46
47

48
49
50
51
52


53
54
55
56



This can be used with a web server such as [nginx](http://nginx.org)
which does not support [Fossil’s CGI mode](./cgi.md).

A basic nginx configuration to support SCGI with Fossil looks like this:

        location /example/ {
            include scgi_params;
            scgi_pass localhost:9000;
            scgi_param SCRIPT_NAME "/example";
            scgi_param HTTPS "on";
        }









Start Fossil so that it will respond to nginx’s SCGI calls like this:




        fossil server /path/to/repo.fossil --scgi --localhost --port 9000

The `--scgi` option switches Fossil into SCGI mode from its default,
which is [stand-alone HTTP server mode](./none.md). All of the other
options discussed in that linked document — such as the ability to serve
a directory full of Fossil repositories rather than just a single
repository — work the same way in SCGI mode.

The `--localhost` option is simply good security: we’re using nginx to
expose Fossil service to the outside world, so there is no good reason
to allow outsiders to contact this Fossil SCGI server directly.

Giving an explicit non-default TCP port number via `--port` is a good
idea to avoid conflicts with use of Fossil’s default TCP service port,
8080, which may conflict with local uses of `fossil ui` and such.

Fossil requires the `SCRIPT_NAME` environment variable in order to
function properly, but nginx does not provide this variable by default,
so it is necessary to provide it in the configuration.  Failure to do
this will cause Fossil to return an error.

The [example `fslsrv` script](/file/tools/fslsrv) shows off these same

concepts in a more complicated setting. You might want to mine that

script for ideas.


You might want to next read one of the platform-specific versions of this
document, which goes into more detail:

*   [Debian/Ubuntu](../debian/nginx.md)



There is a [separate article](../../tls-nginx.md) showing how to add TLS
encryption to this basic SCGI + nginx setup.

*[Return to the top-level Fossil server article.](../)*










<

|


>
>
>
>
>
>
>
>
|
>
>
>

|















|
<
<
|
|
<
>
|
>
|

>
|
|
|
|

>
>
|
|


>
>

9
10
11
12
13
14
15

16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


50
51

52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

This can be used with a web server such as [nginx](http://nginx.org)
which does not support [Fossil’s CGI mode](./cgi.md).

A basic nginx configuration to support SCGI with Fossil looks like this:

        location /example/ {
            include scgi_params;

            scgi_param SCRIPT_NAME "/example";
            scgi_pass localhost:9000;
        }

The `scgi_params` file comes with nginx, and it simply translates nginx
internal variables to `scgi_param` directives to create SCGI environment
variables for the proxied program; in this case, Fossil. Our explicit
`scgi_param` call to define `SCRIPT_NAME` adds one more variable to this
set, which is necessary for this configuration to work properly, because
our repo isn’t at the root of the URL hierarchy. Without it, when Fossil
generates absolute URLs, they’ll be missing the `/example` part at the
start, which will typically cause [404 errors][404].

The final directive simply tells nginx to proxy all calls to URLs under
`/example` down to an SCGI program on TCP port 9000. We can temporarily
set Fossil up as a server on that port like so:

        $ fossil server /path/to/repo.fossil --scgi --localhost --port 9000 &

The `--scgi` option switches Fossil into SCGI mode from its default,
which is [stand-alone HTTP server mode](./none.md). All of the other
options discussed in that linked document — such as the ability to serve
a directory full of Fossil repositories rather than just a single
repository — work the same way in SCGI mode.

The `--localhost` option is simply good security: we’re using nginx to
expose Fossil service to the outside world, so there is no good reason
to allow outsiders to contact this Fossil SCGI server directly.

Giving an explicit non-default TCP port number via `--port` is a good
idea to avoid conflicts with use of Fossil’s default TCP service port,
8080, which may conflict with local uses of `fossil ui` and such.

We characterized the SCGI service start command above as “temporary”


because running Fossil in the background like that means it won’t start
back up on a reboot of the server. A simple solution to that is to add

that command to `/etc/rc.local` on systems that have it. However, you
might want to consider setting Fossil up as an OS service instead, so
that you get the benefits of the platform’s service management
framework:

*   [Linux (systemd)](../debian/service.md)
*   [Windows service](../windows/service.md)
*   [macOS (launchd)](../macos/service.md)
*   [xinetd](../any/xinetd.md)
*   [inetd](../any/inetd.md)

We go into more detail on nginx service setup with Fossil in our
[Debian/Ubuntu specific guide](../debian/nginx.md). Then in [a later
article](../../tls-nginx.md) that builds upon that, we show how to add
TLS encryption to this basic SCGI + nginx setup on Debian type OSes.

*[Return to the top-level Fossil server article.](../)*

[404]: https://en.wikipedia.org/wiki/HTTP_404