webhaak 0.6.1

Simple webhook service to update and deploy sites and do other maintenance and automatic tasks

webhaak is a simple webhook service to update and deploy sites and do other maintenance without having to ssh to a node.

webhaak is on ReadTheDocs

webhaak supports git push hooks from GitHub, BitBucket, gitea, and gogs; for these it can automatically update checkouts. It also recognises Sentry notifications, and of course regular calls.

Installation

From PyPI

Assuming you already are inside a virtualenv:

pip install webhaak

From Git

Create a new virtualenv (if you are not already in one) and install the necessary packages:

git clone https://codeberg.org/diginaut/webhaak.git
cd webhaak
mkvirtualenv webhaak # or whatever project you are working on
# If you just want to run it, no need for development dependencies
uv sync --active --no-dev
# Otherwise, install everything in the active virtualenv
uv sync --active

Usage

Copy example.yaml from example_config to a directory you will use for configuration and configure to your needs. This is a yaml file with the projects to serve (see next section).

Run webhaak as a service under nginx or apache and call the appropriate url’s when wanted (e.g., on push to repository).

webhaak can also be run from the command line: uvicorn webhaak:app --reload

Be sure to export/set the SECRETKEY environment variable before running, it’s needed for some management URI’s.

Run gunicorn -k uvicorn.workers.UvicornWorker for production. For an example of how to set up a server see this article with configuration for nginx, uvicorn, systemd, security and such.

The RQ background worker can be run from the command line: rq worker --with-scheduler webhaak

Url’s are of the form https://hook.example.com/app/<appkey>/<triggerkey>

API documentation is auto-generated, and can be browsed at https://hook.example.com/docs

Example configuration

See the example hook settings for syntax of how to configure repositories, commands and directories.

Call webhaak on its endpoint /admin/SECRETKEY/get_app_key to generate a random new key for usage in the projects yaml file (so, for example https://hook.example.com/admin/abc123/get_app_key)

By default, webhaak clones projects in a directory under its REPOS_CACHE_DIR directory, but there is support for a per-repo parent dir settings with repo_parent in the yaml.

This means that webhaak then doesn’t clone this repo into its default cache dir, but in a subdirectory of the directory configured in repo_parent, so <repo_parent>/repo_name (e.g., /srv/custom_parent/myproject).

Server configuration

• supervisord RQ worker which uses the RQ config

• systemd for webhaak API which uses the gunicorn config

• nginx for webhaak API

• more config

What’s new?

See the Changelog.

Developing

Running in PyCharm: tbd :)