mirrors/webhook
1
0
Fork 0
mirror of https://github.com/adnanh/webhook.git synced 2025-06-01 18:22:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: documentation for the systemd socket activation mode

Browse source
This commit is contained in:
Ian Roberts 2024-10-25 13:57:45 +01:00
parent b00e93210e
commit 661a96f3e3
2 changed files with 64 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

3
README.md
View file

@ -117,6 +117,9 @@ Note that when running in this mode the [`ip-whitelist`](docs/Hook-Rules.md#matc
## CORS Headers
If you want to set CORS headers, you can use the `-header name=value` flag while starting [webhook][w] to set the appropriate CORS headers that will be returned with each response.
## Running under `systemd`
On platforms that use [systemd](https://systemd.io), [webhook][w] supports the _socket activation_ mechanism. If [webhook][w] detects that it has been launched from a systemd-managed socket it will automatically use that instead of opening its own listening port. See [the systemd page](docs/Systemd-Activation.md) for full details.
## Interested in running webhook inside of a Docker container?
You can use one of the following Docker images, or create your own (please read [this discussion](https://github.com/adnanh/webhook/issues/63)):
- [almir/webhook](https://github.com/almir/docker-webhook)

61
docs/Systemd-Activation.md Normal file
View file

@ -0,0 +1,61 @@
# Using systemd socket activation
_New in v2.9.0_
On platforms that use [systemd](https://systemd.io), [webhook][w]
supports the _socket activation_ mechanism. In this mode, systemd itself is responsible for managing the listening socket, and it launches [webhook][w] the first time it receives a request on the socket. This has a number of advantages over the standard mode:
- [webhook][w] can run as a normal user while still being able to use a port number like 80 or 443 that would normally require root privilege
- if the [webhook][w] process dies and is restarted, pending connections are not dropped - they just keep waiting until the restarted [webhook][w] is ready
No special configuration is necessary to tell [webhook][w] that socket activation is being used - socket activation sets specific environment variables when launching the activated service, if [webhook][w] detects these variables it will ignore the `-port` and `-socket` options and simply use the systemd-provided socket instead of opening its own.
## Configuration
To run [webhook][w] with socket activation you need to create _two_ separate unit files in your systemd configuration directory (typically `/etc/systemd/system`), one for the socket and one for the service. They must have matching names; in this example we use `webhook.socket` and `webhook.service`. At their simplest, these files should look like:
**webhook.socket**
```
[Unit]
Description=Webhook server socket
[Socket]
# Listen on all network interfaces, port 9000
ListenStream=9000
# Alternatives:
## Listen on one specific interface only
# ListenStream=10.0.0.1:9000
# FreeBind=true
## Listen on a Unix domain socket
# ListenStream=/tmp/webhook.sock
[Install]
WantedBy=multi-user.target
```
**webhook.service**
```
[Unit]
Description=Webhook server
[Service]
Type=exec
ExecStart=webhook -nopanic -hooks /etc/webhook/hooks.yml
# Which user should the webhooks run as?
User=nobody
Group=nogroup
```
You should enable and start the _socket_, but it is not necessary to enable the _service_ - this will be started automatically when the socket receives its first request.
```sh
sudo systemctl enable webhook.socket
sudo systemctl start webhook.socket
```
Systemd unit files support many other options, see the [systemd.socket](https://www.freedesktop.org/software/systemd/man/latest/systemd.socket.html) and [systemd.service](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html) manual pages for full details.
[w]: https://github.com/adnanh/webhook