Fossil SCM
Clarified use of scgi_params, SCRIPT_NAME, and service starting in the generic SCGI server setup doc.
Commit
5a58ac3141612f2638d3d02f7d32281851782042852d944220c7c8961820687f
Parent
6c6aae97821d7a9…
1 file changed
+34
-20
+34
-20
| --- www/server/any/scgi.md | ||
| +++ www/server/any/scgi.md | ||
| @@ -11,18 +11,28 @@ | ||
| 11 | 11 | |
| 12 | 12 | A basic nginx configuration to support SCGI with Fossil looks like this: |
| 13 | 13 | |
| 14 | 14 | location /example/ { |
| 15 | 15 | include scgi_params; |
| 16 | - scgi_pass localhost:9000; | |
| 17 | 16 | scgi_param SCRIPT_NAME "/example"; |
| 18 | - scgi_param HTTPS "on"; | |
| 17 | + scgi_pass localhost:9000; | |
| 19 | 18 | } |
| 20 | 19 | |
| 21 | -Start Fossil so that it will respond to nginx’s SCGI calls like this: | |
| 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 `/example` 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 | +`/example` down to an SCGI program on TCP port 9000. We can temporarily | |
| 31 | +set Fossil up as a server on that port like so: | |
| 22 | 32 | |
| 23 | - fossil server /path/to/repo.fossil --scgi --localhost --port 9000 | |
| 33 | + $ fossil server /path/to/repo.fossil --scgi --localhost --port 9000 & | |
| 24 | 34 | |
| 25 | 35 | The `--scgi` option switches Fossil into SCGI mode from its default, |
| 26 | 36 | which is [stand-alone HTTP server mode](./none.md). All of the other |
| 27 | 37 | options discussed in that linked document — such as the ability to serve |
| 28 | 38 | a directory full of Fossil repositories rather than just a single |
| @@ -34,23 +44,27 @@ | ||
| 34 | 44 | |
| 35 | 45 | Giving an explicit non-default TCP port number via `--port` is a good |
| 36 | 46 | idea to avoid conflicts with use of Fossil’s default TCP service port, |
| 37 | 47 | 8080, which may conflict with local uses of `fossil ui` and such. |
| 38 | 48 | |
| 39 | -Fossil requires the `SCRIPT_NAME` environment variable in order to | |
| 40 | -function properly, but nginx does not provide this variable by default, | |
| 41 | -so it is necessary to provide it in the configuration. Failure to do | |
| 42 | -this will cause Fossil to return an error. | |
| 43 | - | |
| 44 | -The [example `fslsrv` script](/file/tools/fslsrv) shows off these same | |
| 45 | -concepts in a more complicated setting. You might want to mine that | |
| 46 | -script for ideas. | |
| 47 | - | |
| 48 | -You might want to next read one of the platform-specific versions of this | |
| 49 | -document, which goes into more detail: | |
| 50 | - | |
| 51 | -* [Debian/Ubuntu](../debian/nginx.md) | |
| 52 | - | |
| 53 | -There is a [separate article](../../tls-nginx.md) showing how to add TLS | |
| 54 | -encryption to this basic SCGI + nginx setup. | |
| 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). Then in [a later | |
| 65 | +article](../../tls-nginx.md) that builds upon that, we show how to add | |
| 66 | +TLS encryption to this basic SCGI + nginx setup on Debian type OSes. | |
| 55 | 67 | |
| 56 | 68 | *[Return to the top-level Fossil server article.](../)* |
| 69 | + | |
| 70 | +[404]: https://en.wikipedia.org/wiki/HTTP_404 | |
| 57 | 71 |
| --- www/server/any/scgi.md | |
| +++ www/server/any/scgi.md | |
| @@ -11,18 +11,28 @@ | |
| 11 | |
| 12 | A basic nginx configuration to support SCGI with Fossil looks like this: |
| 13 | |
| 14 | location /example/ { |
| 15 | include scgi_params; |
| 16 | scgi_pass localhost:9000; |
| 17 | scgi_param SCRIPT_NAME "/example"; |
| 18 | scgi_param HTTPS "on"; |
| 19 | } |
| 20 | |
| 21 | Start Fossil so that it will respond to nginx’s SCGI calls like this: |
| 22 | |
| 23 | fossil server /path/to/repo.fossil --scgi --localhost --port 9000 |
| 24 | |
| 25 | The `--scgi` option switches Fossil into SCGI mode from its default, |
| 26 | which is [stand-alone HTTP server mode](./none.md). All of the other |
| 27 | options discussed in that linked document — such as the ability to serve |
| 28 | a directory full of Fossil repositories rather than just a single |
| @@ -34,23 +44,27 @@ | |
| 34 | |
| 35 | Giving an explicit non-default TCP port number via `--port` is a good |
| 36 | idea to avoid conflicts with use of Fossil’s default TCP service port, |
| 37 | 8080, which may conflict with local uses of `fossil ui` and such. |
| 38 | |
| 39 | Fossil requires the `SCRIPT_NAME` environment variable in order to |
| 40 | function properly, but nginx does not provide this variable by default, |
| 41 | so it is necessary to provide it in the configuration. Failure to do |
| 42 | this will cause Fossil to return an error. |
| 43 | |
| 44 | The [example `fslsrv` script](/file/tools/fslsrv) shows off these same |
| 45 | concepts in a more complicated setting. You might want to mine that |
| 46 | script for ideas. |
| 47 | |
| 48 | You might want to next read one of the platform-specific versions of this |
| 49 | document, which goes into more detail: |
| 50 | |
| 51 | * [Debian/Ubuntu](../debian/nginx.md) |
| 52 | |
| 53 | There is a [separate article](../../tls-nginx.md) showing how to add TLS |
| 54 | encryption to this basic SCGI + nginx setup. |
| 55 | |
| 56 | *[Return to the top-level Fossil server article.](../)* |
| 57 |
| --- www/server/any/scgi.md | |
| +++ www/server/any/scgi.md | |
| @@ -11,18 +11,28 @@ | |
| 11 | |
| 12 | A basic nginx configuration to support SCGI with Fossil looks like this: |
| 13 | |
| 14 | location /example/ { |
| 15 | include scgi_params; |
| 16 | scgi_param SCRIPT_NAME "/example"; |
| 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 `/example` 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 | `/example` 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 |
| @@ -34,23 +44,27 @@ | |
| 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). Then in [a later |
| 65 | article](../../tls-nginx.md) that builds upon that, we show how to add |
| 66 | TLS encryption to this basic SCGI + nginx setup on Debian type OSes. |
| 67 | |
| 68 | *[Return to the top-level Fossil server article.](../)* |
| 69 | |
| 70 | [404]: https://en.wikipedia.org/wiki/HTTP_404 |
| 71 |