Fossil SCM
Updates to the systemd service doc, primarily to refer the reader to the new containerized runner methods, but also to add other tips.
Commit
ad09d3eee0f45b70f6df8cc94ff54dfd9f6c53c89b98d28746f402a2c12adc4a
Parent
45e0475ca70a273…
1 file changed
+61
-25
+61
-25
| --- www/server/debian/service.md | ||
| +++ www/server/debian/service.md | ||
| @@ -1,20 +1,45 @@ | ||
| 1 | 1 | # Serving via systemd on Debian and Ubuntu |
| 2 | 2 | |
| 3 | -[`systemd`][sdhome] is the default service management framework on | |
| 4 | -Debian [since version 8][wpa] and Ubuntu since version 15.04, both | |
| 5 | -released in April 2015. | |
| 6 | - | |
| 7 | -There are multiple ways to get a service to launch under `systemd`. | |
| 8 | -We’re going to show two methods which correspond approximately to two of | |
| 9 | -our generic Fossil server setup methods, the [`inetd`](../any/inetd.md) | |
| 10 | -and [standalone HTTP server](../any/none.md) methods. | |
| 3 | +[`systemd`][sdhome] is the service management framework in all major | |
| 4 | +in-support versions of Linux. There are multiple ways to run Fossil | |
| 5 | +under `systemd`. | |
| 11 | 6 | |
| 12 | 7 | [sdhome]: https://www.freedesktop.org/wiki/Software/systemd/ |
| 13 | 8 | [wpa]: https://en.wikipedia.org/wiki/Systemd#Adoption |
| 14 | 9 | |
| 15 | 10 | |
| 11 | +## Containerized Service | |
| 12 | + | |
| 13 | +Two of the methods for running [containerized Fossil][cntdoc] integrate | |
| 14 | +with `systemd`, potentially obviating the more direct methods below: | |
| 15 | + | |
| 16 | +* If you take [the Podman method][podman] of running containerized | |
| 17 | + Fossil, it opens the `podman create` option for you, exemplified in [the | |
| 18 | + `fslsrv` script][fslsrv] used on this author’s public Fossil-based | |
| 19 | + web site. That script pulls [custom containers][tscnt] from [my Docker | |
| 20 | + Hub repo][dhrepo]. With these elements combined, this scheme allows you to build | |
| 21 | + from source on one machine, then deploy to a server, running Fossil | |
| 22 | + containerized without needing build tools on the server. | |
| 23 | + | |
| 24 | +* If you’re willing to give up [a lot of features][nsweak] relative to | |
| 25 | + Podman, and you’re willing to tolerate a lot more manual | |
| 26 | + administrivia, [the nspawn method][nspawn] has a lot less overhead, | |
| 27 | + being a direct feature of `systemd` itself. | |
| 28 | + | |
| 29 | +Both of these options provide [better security][cntsec] than running | |
| 30 | +Fossil directly under `systemd`, among [other benefits][cntdoc]. | |
| 31 | + | |
| 32 | +[cntdoc]: ../../containers.md | |
| 33 | +[cntsec]: ../../containers.md#security | |
| 34 | +[dhrepo]: https://hub.docker.com/r/tangentsoft/fossil | |
| 35 | +[fslsrv]: https://tangentsoft.com/fossil/dir?name=bin | |
| 36 | +[nspawn]: ../../containers.md#nspawn | |
| 37 | +[nsweak]: ../../containers.md#nspawn-weaknesses | |
| 38 | +[podman]: ../../containers.md#podman | |
| 39 | +[tscnt]: https://tangentsoft.com/fossil/dir/container | |
| 40 | + | |
| 16 | 41 | |
| 17 | 42 | ## User Service |
| 18 | 43 | |
| 19 | 44 | A fun thing you can easily do with `systemd` that you can’t directly do |
| 20 | 45 | with older technologies like `inetd` and `xinetd` is to set a server up |
| @@ -46,14 +71,17 @@ | ||
| 46 | 71 | Unlike with `inetd` and `xinetd`, we don’t need to tell `systemd` which |
| 47 | 72 | user and group to run this service as, because we’ve installed it |
| 48 | 73 | under the account we’re logged into, which `systemd` will use as the |
| 49 | 74 | service’s owner. |
| 50 | 75 | |
| 51 | -We’ve told `systemd` that we want automatic service restarts with | |
| 52 | -back-off logic, making this much more robust than the by-hand launches | |
| 53 | -of `fossil` in the platform-independent Fossil server instructions. The | |
| 54 | -service will stay up until we explicitly tell it to shut down. | |
| 76 | +The result is essentially [the standalone server method](../any/none.md) | |
| 77 | +coupled with an intelligent service manager that will start it | |
| 78 | +automatically in the background on system boot, perform automatic | |
| 79 | +service restarts with back-off logic, and more, making this much more | |
| 80 | +robust than the by-hand launches of `fossil` in the platform-independent | |
| 81 | +Fossil server instructions. The service will stay up until we | |
| 82 | +explicitly tell it to shut down. | |
| 55 | 83 | |
| 56 | 84 | This scheme couples well with [the generic SCGI instructions][scgi] as |
| 57 | 85 | it requires a way to run the underlying repository server in the |
| 58 | 86 | background. Given that its service port is then proxied by SCGI, it |
| 59 | 87 | follows that it doesn’t need to run as a system service. A user service |
| @@ -91,21 +119,27 @@ | ||
| 91 | 119 | |
| 92 | 120 | |
| 93 | 121 | |
| 94 | 122 | ### System Service Alternative |
| 95 | 123 | |
| 96 | -There are a couple of common reasons that you’d have cause to install | |
| 124 | +There are some common reasons that you’d have good cause to install | |
| 97 | 125 | Fossil as a system-level service rather than the prior user-level one: |
| 98 | 126 | |
| 99 | -* You need Fossil to listen on a TCP port under 1024, such as because | |
| 100 | - you’re running it on a private LAN, and the server has no other HTTP | |
| 101 | - service, so you want Fossil to handle the web traffic directly. | |
| 102 | - | |
| 103 | -* You’re proxying Fossil with a system-level service such as | |
| 104 | - [nginx](./nginx.md), so you need to put Fossil into the system-level | |
| 105 | - service dependency chain to make sure things start up and shut down | |
| 106 | - in the proper order. | |
| 127 | +* You’re using [the new `fossil server --cert` feature][sslsrv] to get | |
| 128 | + TLS service and want it to listen directly on port 443, rather than be | |
| 129 | + proxied, as one had to do before Fossil got the ability to act as a | |
| 130 | + TLS server itself. That requires root privileges, so you can’t run | |
| 131 | + it as a user-level service. | |
| 132 | + | |
| 133 | +* You’re proxying Fossil with [nginx](./nginx.md) or similar, allowing | |
| 134 | + it to bind to high-numbered ports, but because it starts as a system | |
| 135 | + service, you can’t get Fossil into the same dependency chain to | |
| 136 | + ensure things start up and shut down in the proper order unless it | |
| 137 | + *also* runs as a system service. | |
| 138 | + | |
| 139 | +* You want to make use of Fossil’s [chroot jail feature][cjail], which | |
| 140 | + requires the server to start as root. | |
| 107 | 141 | |
| 108 | 142 | There are just a small set of changes required: |
| 109 | 143 | |
| 110 | 144 | 1. Install the unit file to one of the persistent system-level unit |
| 111 | 145 | file directories. Typically, these are: |
| @@ -115,18 +149,20 @@ | ||
| 115 | 149 | |
| 116 | 150 | 2. Add `User` and `Group` directives to the `[Service]` section so |
| 117 | 151 | Fossil runs as a normal user, preferably one with access only to |
| 118 | 152 | the Fossil repo files, rather than running as `root`. |
| 119 | 153 | |
| 154 | +[sslsrv]: ../../ssl-server.md | |
| 155 | +[cjail]: ../../chroot.md | |
| 156 | + | |
| 120 | 157 | |
| 121 | 158 | ## Socket Activation |
| 122 | 159 | |
| 123 | 160 | Another useful method to serve a Fossil repo via `systemd` is via a |
| 124 | -socket listener, which `systemd` calls “[socket activation][sa].” | |
| 125 | -It’s more complicated, but it has some nice properties. It is the | |
| 126 | -feature that allows `systemd` to replace `inetd`, `xinetd`, Upstart, and | |
| 127 | -several other competing technologies. | |
| 161 | +socket listener, which `systemd` calls “[socket activation][sa],” | |
| 162 | +roughly equivalent to [the ancient `inetd` method](../any/inetd.md). | |
| 163 | +It’s more complicated, but it has some nice properties. | |
| 128 | 164 | |
| 129 | 165 | We first need to define the privileged socket listener by writing |
| 130 | 166 | `/etc/systemd/system/fossil.socket`: |
| 131 | 167 | |
| 132 | 168 | ```dosini |
| 133 | 169 |
| --- www/server/debian/service.md | |
| +++ www/server/debian/service.md | |
| @@ -1,20 +1,45 @@ | |
| 1 | # Serving via systemd on Debian and Ubuntu |
| 2 | |
| 3 | [`systemd`][sdhome] is the default service management framework on |
| 4 | Debian [since version 8][wpa] and Ubuntu since version 15.04, both |
| 5 | released in April 2015. |
| 6 | |
| 7 | There are multiple ways to get a service to launch under `systemd`. |
| 8 | We’re going to show two methods which correspond approximately to two of |
| 9 | our generic Fossil server setup methods, the [`inetd`](../any/inetd.md) |
| 10 | and [standalone HTTP server](../any/none.md) methods. |
| 11 | |
| 12 | [sdhome]: https://www.freedesktop.org/wiki/Software/systemd/ |
| 13 | [wpa]: https://en.wikipedia.org/wiki/Systemd#Adoption |
| 14 | |
| 15 | |
| 16 | |
| 17 | ## User Service |
| 18 | |
| 19 | A fun thing you can easily do with `systemd` that you can’t directly do |
| 20 | with older technologies like `inetd` and `xinetd` is to set a server up |
| @@ -46,14 +71,17 @@ | |
| 46 | Unlike with `inetd` and `xinetd`, we don’t need to tell `systemd` which |
| 47 | user and group to run this service as, because we’ve installed it |
| 48 | under the account we’re logged into, which `systemd` will use as the |
| 49 | service’s owner. |
| 50 | |
| 51 | We’ve told `systemd` that we want automatic service restarts with |
| 52 | back-off logic, making this much more robust than the by-hand launches |
| 53 | of `fossil` in the platform-independent Fossil server instructions. The |
| 54 | service will stay up until we explicitly tell it to shut down. |
| 55 | |
| 56 | This scheme couples well with [the generic SCGI instructions][scgi] as |
| 57 | it requires a way to run the underlying repository server in the |
| 58 | background. Given that its service port is then proxied by SCGI, it |
| 59 | follows that it doesn’t need to run as a system service. A user service |
| @@ -91,21 +119,27 @@ | |
| 91 | |
| 92 | |
| 93 | |
| 94 | ### System Service Alternative |
| 95 | |
| 96 | There are a couple of common reasons that you’d have cause to install |
| 97 | Fossil as a system-level service rather than the prior user-level one: |
| 98 | |
| 99 | * You need Fossil to listen on a TCP port under 1024, such as because |
| 100 | you’re running it on a private LAN, and the server has no other HTTP |
| 101 | service, so you want Fossil to handle the web traffic directly. |
| 102 | |
| 103 | * You’re proxying Fossil with a system-level service such as |
| 104 | [nginx](./nginx.md), so you need to put Fossil into the system-level |
| 105 | service dependency chain to make sure things start up and shut down |
| 106 | in the proper order. |
| 107 | |
| 108 | There are just a small set of changes required: |
| 109 | |
| 110 | 1. Install the unit file to one of the persistent system-level unit |
| 111 | file directories. Typically, these are: |
| @@ -115,18 +149,20 @@ | |
| 115 | |
| 116 | 2. Add `User` and `Group` directives to the `[Service]` section so |
| 117 | Fossil runs as a normal user, preferably one with access only to |
| 118 | the Fossil repo files, rather than running as `root`. |
| 119 | |
| 120 | |
| 121 | ## Socket Activation |
| 122 | |
| 123 | Another useful method to serve a Fossil repo via `systemd` is via a |
| 124 | socket listener, which `systemd` calls “[socket activation][sa].” |
| 125 | It’s more complicated, but it has some nice properties. It is the |
| 126 | feature that allows `systemd` to replace `inetd`, `xinetd`, Upstart, and |
| 127 | several other competing technologies. |
| 128 | |
| 129 | We first need to define the privileged socket listener by writing |
| 130 | `/etc/systemd/system/fossil.socket`: |
| 131 | |
| 132 | ```dosini |
| 133 |
| --- www/server/debian/service.md | |
| +++ www/server/debian/service.md | |
| @@ -1,20 +1,45 @@ | |
| 1 | # Serving via systemd on Debian and Ubuntu |
| 2 | |
| 3 | [`systemd`][sdhome] is the service management framework in all major |
| 4 | in-support versions of Linux. There are multiple ways to run Fossil |
| 5 | under `systemd`. |
| 6 | |
| 7 | [sdhome]: https://www.freedesktop.org/wiki/Software/systemd/ |
| 8 | [wpa]: https://en.wikipedia.org/wiki/Systemd#Adoption |
| 9 | |
| 10 | |
| 11 | ## Containerized Service |
| 12 | |
| 13 | Two of the methods for running [containerized Fossil][cntdoc] integrate |
| 14 | with `systemd`, potentially obviating the more direct methods below: |
| 15 | |
| 16 | * If you take [the Podman method][podman] of running containerized |
| 17 | Fossil, it opens the `podman create` option for you, exemplified in [the |
| 18 | `fslsrv` script][fslsrv] used on this author’s public Fossil-based |
| 19 | web site. That script pulls [custom containers][tscnt] from [my Docker |
| 20 | Hub repo][dhrepo]. With these elements combined, this scheme allows you to build |
| 21 | from source on one machine, then deploy to a server, running Fossil |
| 22 | containerized without needing build tools on the server. |
| 23 | |
| 24 | * If you’re willing to give up [a lot of features][nsweak] relative to |
| 25 | Podman, and you’re willing to tolerate a lot more manual |
| 26 | administrivia, [the nspawn method][nspawn] has a lot less overhead, |
| 27 | being a direct feature of `systemd` itself. |
| 28 | |
| 29 | Both of these options provide [better security][cntsec] than running |
| 30 | Fossil directly under `systemd`, among [other benefits][cntdoc]. |
| 31 | |
| 32 | [cntdoc]: ../../containers.md |
| 33 | [cntsec]: ../../containers.md#security |
| 34 | [dhrepo]: https://hub.docker.com/r/tangentsoft/fossil |
| 35 | [fslsrv]: https://tangentsoft.com/fossil/dir?name=bin |
| 36 | [nspawn]: ../../containers.md#nspawn |
| 37 | [nsweak]: ../../containers.md#nspawn-weaknesses |
| 38 | [podman]: ../../containers.md#podman |
| 39 | [tscnt]: https://tangentsoft.com/fossil/dir/container |
| 40 | |
| 41 | |
| 42 | ## User Service |
| 43 | |
| 44 | A fun thing you can easily do with `systemd` that you can’t directly do |
| 45 | with older technologies like `inetd` and `xinetd` is to set a server up |
| @@ -46,14 +71,17 @@ | |
| 71 | Unlike with `inetd` and `xinetd`, we don’t need to tell `systemd` which |
| 72 | user and group to run this service as, because we’ve installed it |
| 73 | under the account we’re logged into, which `systemd` will use as the |
| 74 | service’s owner. |
| 75 | |
| 76 | The result is essentially [the standalone server method](../any/none.md) |
| 77 | coupled with an intelligent service manager that will start it |
| 78 | automatically in the background on system boot, perform automatic |
| 79 | service restarts with back-off logic, and more, making this much more |
| 80 | robust than the by-hand launches of `fossil` in the platform-independent |
| 81 | Fossil server instructions. The service will stay up until we |
| 82 | explicitly tell it to shut down. |
| 83 | |
| 84 | This scheme couples well with [the generic SCGI instructions][scgi] as |
| 85 | it requires a way to run the underlying repository server in the |
| 86 | background. Given that its service port is then proxied by SCGI, it |
| 87 | follows that it doesn’t need to run as a system service. A user service |
| @@ -91,21 +119,27 @@ | |
| 119 | |
| 120 | |
| 121 | |
| 122 | ### System Service Alternative |
| 123 | |
| 124 | There are some common reasons that you’d have good cause to install |
| 125 | Fossil as a system-level service rather than the prior user-level one: |
| 126 | |
| 127 | * You’re using [the new `fossil server --cert` feature][sslsrv] to get |
| 128 | TLS service and want it to listen directly on port 443, rather than be |
| 129 | proxied, as one had to do before Fossil got the ability to act as a |
| 130 | TLS server itself. That requires root privileges, so you can’t run |
| 131 | it as a user-level service. |
| 132 | |
| 133 | * You’re proxying Fossil with [nginx](./nginx.md) or similar, allowing |
| 134 | it to bind to high-numbered ports, but because it starts as a system |
| 135 | service, you can’t get Fossil into the same dependency chain to |
| 136 | ensure things start up and shut down in the proper order unless it |
| 137 | *also* runs as a system service. |
| 138 | |
| 139 | * You want to make use of Fossil’s [chroot jail feature][cjail], which |
| 140 | requires the server to start as root. |
| 141 | |
| 142 | There are just a small set of changes required: |
| 143 | |
| 144 | 1. Install the unit file to one of the persistent system-level unit |
| 145 | file directories. Typically, these are: |
| @@ -115,18 +149,20 @@ | |
| 149 | |
| 150 | 2. Add `User` and `Group` directives to the `[Service]` section so |
| 151 | Fossil runs as a normal user, preferably one with access only to |
| 152 | the Fossil repo files, rather than running as `root`. |
| 153 | |
| 154 | [sslsrv]: ../../ssl-server.md |
| 155 | [cjail]: ../../chroot.md |
| 156 | |
| 157 | |
| 158 | ## Socket Activation |
| 159 | |
| 160 | Another useful method to serve a Fossil repo via `systemd` is via a |
| 161 | socket listener, which `systemd` calls “[socket activation][sa],” |
| 162 | roughly equivalent to [the ancient `inetd` method](../any/inetd.md). |
| 163 | It’s more complicated, but it has some nice properties. |
| 164 | |
| 165 | We first need to define the privileged socket listener by writing |
| 166 | `/etc/systemd/system/fossil.socket`: |
| 167 | |
| 168 | ```dosini |
| 169 |