weblug/README.md

# weblug

`weblug` is is a configurable webhook receiver that allows users to run arbitrary programs and script when a webhook is triggered.

The configuration happens via a [yaml file](weblug.yml). Read the [usage caveats](#caveats)!

`weblug` supports multiple webhooks via different URL paths, concurrency limitations, background execution and running webhooks as separate user (`uid`/`gid`).

## Usage

Webooks are defined via a yaml file. See [weblug.yml](weblug.yml) for an example configuration. Pass the yaml file(s) to `weblug` to starting the webserver and waiting for incoming webhooks:

    ./weblug YAML-FILE

`weblug` can run as any user, however for custom `uid`/`gid` webhooks, the program needs to run as root.

### Caveats

1. `weblug` does not support https encryption

weblug is expected to run behind a http reverse proxy (e.g. `apache` or `nginx`) which handles transport encryption. The program it self does not support https, nor are there any plans to implement this in the near future.

CAVE: Don't expose secrets and credentials by running this without any transport encryption!

2. Do not run this without reverse proxy

`weblug` relies on the standart go http implementation. To avoid a whole class of security issues, `weblug` should never run on the open internet without a http reverse proxy.

3. `weblug` runs as root, when using custom UID/GIDs

In it's current implementation, `weblug` requires to remain running as root without dropping privileges when using custom UID/GIDs.

## Build

    make               # Build weblug
    make static        # Make a static binary

Alternatively you there is also a [Taskfile](https://taskfile.dev)

    task
    task static        # Build static binary

## Run as systemd unit

This repository provides an example [weblug.service](weblug.service), which can be used to start `weblug` as systemd service.
This file can be placed in `/etc/systemd/system/weblug.service` and in conjunction with an adequate `weblug.yml` file e.g. in `/etc/weblug.yml` this provides a way of running weblug as a native systemd service.
Initial commit 2022-02-08 08:55:38 +00:00			`# weblug`

Improve the readability Change the wording and construction of the README file for better readability. 2023-09-23 08:57:47 +00:00			`weblug` is is a configurable webhook receiver that allows users to run arbitrary programs and script when a webhook is triggered.
Add usage instructions 2022-02-08 10:50:38 +00:00
Add caveats Add usage caveats to the README file and manpage. 2023-05-28 09:45:17 +00:00			`The configuration happens via a [yaml file](weblug.yml). Read the [usage caveats](#caveats)!`
Improve documentation 2022-12-29 15:12:39 +00:00
Improve the readability Change the wording and construction of the README file for better readability. 2023-09-23 08:57:47 +00:00			`weblug` supports multiple webhooks via different URL paths, concurrency limitations, background execution and running webhooks as separate user (`uid`/`gid`).
Add usage instructions 2022-02-08 10:50:38 +00:00
			`## Usage`

Improve the readability Change the wording and construction of the README file for better readability. 2023-09-23 08:57:47 +00:00			Webooks are defined via a yaml file. See [weblug.yml](weblug.yml) for an example configuration. Pass the yaml file(s) to `weblug` to starting the webserver and waiting for incoming webhooks:
Add usage instructions 2022-02-08 10:50:38 +00:00
			`./weblug YAML-FILE`

Improve the documentation Improve the wording to make it more clear, that weblug can run rootless. Also adjust the yaml layout. 2023-04-22 08:58:40 +00:00			`weblug` can run as any user, however for custom `uid`/`gid` webhooks, the program needs to run as root.
Improve documentation 2022-12-29 15:12:39 +00:00
Add caveats Add usage caveats to the README file and manpage. 2023-05-28 09:45:17 +00:00			`### Caveats`

Improve the readability Change the wording and construction of the README file for better readability. 2023-09-23 08:57:47 +00:00			1. `weblug` does not support https encryption
Add caveats Add usage caveats to the README file and manpage. 2023-05-28 09:45:17 +00:00
			weblug is expected to run behind a http reverse proxy (e.g. `apache` or `nginx`) which handles transport encryption. The program it self does not support https, nor are there any plans to implement this in the near future.

			`CAVE: Don't expose secrets and credentials by running this without any transport encryption!`

			`2. Do not run this without reverse proxy`

Improve the readability Change the wording and construction of the README file for better readability. 2023-09-23 08:57:47 +00:00			`weblug` relies on the standart go http implementation. To avoid a whole class of security issues, `weblug` should never run on the open internet without a http reverse proxy.
Add caveats Add usage caveats to the README file and manpage. 2023-05-28 09:45:17 +00:00
			3. `weblug` runs as root, when using custom UID/GIDs

Improve the readability Change the wording and construction of the README file for better readability. 2023-09-23 08:57:47 +00:00			In it's current implementation, `weblug` requires to remain running as root without dropping privileges when using custom UID/GIDs.
Add caveats Add usage caveats to the README file and manpage. 2023-05-28 09:45:17 +00:00
Add usage instructions 2022-02-08 10:50:38 +00:00			`## Build`

			`make # Build weblug`
Improve documentation 2022-12-29 15:12:39 +00:00			`make static # Make a static binary`
Add systemd documentation Add a section about running weblug as systemd service. 2023-04-21 16:59:13 +00:00
Add Taskfile Adds a taskfile to compile weblug. Signed-off-by: phoenix <felix@feldspaten.org> 2023-09-04 18:50:30 +00:00			`Alternatively you there is also a [Taskfile](https://taskfile.dev)`

			`task`
			`task static # Build static binary`

Add systemd documentation Add a section about running weblug as systemd service. 2023-04-21 16:59:13 +00:00			`## Run as systemd unit`

			This repository provides an example [weblug.service](weblug.service), which can be used to start `weblug` as systemd service.
Add Taskfile Adds a taskfile to compile weblug. Signed-off-by: phoenix <felix@feldspaten.org> 2023-09-04 18:50:30 +00:00			This file can be placed in `/etc/systemd/system/weblug.service` and in conjunction with an adequate `weblug.yml` file e.g. in `/etc/weblug.yml` this provides a way of running weblug as a native systemd service.