# webhaak

[![PyPI version](https://img.shields.io/pypi/v/webhaak.svg)](https://pypi.python.org/pypi/webhaak/)
[![PyPI license](https://img.shields.io/github/license/aquatix/webhaak.svg)](https://pypi.python.org/pypi/webhaak/)


## 📚 Overview

[webhaak][webhaak] is a simple [webhook][webhook] service to update and deploy sites, updates, get monitoring pings and do other maintenance without having to ssh to a node.

[webhaak is on ReadTheDocs](https://webhaak.readthedocs.io/en/latest/)

webhaak supports `git push` hooks from Forgejo, Gitea, Gogs, GitHub and BitBucket; for these it can automatically update checkouts. It also recognises Sentry, RSS and Statuspage notifications, monitoring updates from HetrixTools and Freshping, and of course regular webhook calls.


## 📥 Installation

There are a few ways to install webhaak to your computer or server.

### From PyPI

Assuming you already are inside a virtualenv:

```bash
# Using the wonderfully fast uv
uv pip install webhaak

# Alternatively, use Python pip
pip install webhaak
```

### From Git

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

```bash
git clone https://codeberg.org/diginaut/webhaak.git
cd webhaak
# Create a virtualenv with uv
uv venv
# When venv already exists, activate it
source .venv/bin/activate
# Or, when using fish shell:
source .venv/bin/activate.fish
# 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
```

Instead of manually activating the virtualenv, `direnv` can be used by copying the `.envrc.example` file to `.envrc` and using the `layout_uv()` snippet from this [direnvrc](https://codeberg.org/diginaut/dotfiles/src/branch/master/.config/direnv/direnvrc).

This will automatically enable (and create if necessary) the `.venv` virtualenv inside the project directory.


## 🛠️ 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](https://www.slingacademy.com/article/deploying-fastapi-on-ubuntu-with-nginx-and-lets-encrypt/) 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` but it's recommended to use supervisord (see 'Server configuration' section) or systemd.

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][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][supervisord RQ worker] which uses the [RQ config][RQ config]
- [systemd for webhaak API][systemd for webhaak API] which uses the [gunicorn config][gunicorn config]
- [nginx for webhaak API][nginx for webhaak API]
- [more configurations][more config]


## ✨ What's new?

See the [Changelog][Changelog].


## Developing

Running in PyCharm: tbd :)


[webhaak]: https://codeberg.org/diginaut/webhaak
[webhook]: https://en.wikipedia.org/wiki/Webhook
[hook settings]: https://codeberg.org/diginaut/webhaak/src/branch/master/example_config/examples.yaml
[supervisord RQ worker]: https://codeberg.org/diginaut/webhaak/src/branch/master/example_config/supervisord/webhaak_rq_worker.conf
[RQ config]: https://codeberg.org/diginaut/webhaak/src/branch/master/example_config/rq_settings.example.py
[systemd for webhaak API]: https://codeberg.org/diginaut/webhaak/src/branch/master/example_config/systemd/webhaak.service
[gunicorn config]: https://codeberg.org/diginaut/webhaak/src/branch/master/example_config/gunicorn_webhaak_conf.py
[more config]: https://codeberg.org/diginaut/webhaak/src/branch/master/example_config
[nginx for webhaak API]: https://codeberg.org/diginaut/webhaak/src/branch/master/example_config/nginx/hook.example.com.conf
[Changelog]: CHANGELOG.md