Skip to content

Commit 4232c34

Browse files
dolejska-danieldolejska-daniel
committed
📖 README.md Updated, Added example Nginx configs
1 parent 411400e commit 4232c34

File tree

4 files changed

+167
-4
lines changed

4 files changed

+167
-4
lines changed

‎README.md‎

Lines changed: 96 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,103 @@
22
> v0.1
33
44
## Introduction
5-
_TBD_
5+
Welcome to this mini-project repository!
6+
The aim of this project is to provide **extensible**, **lightweight** and **easy to configure** webhook processor.
7+
This implementation allows extremely simple webhook event binding and their processing.
8+
Automate anything you want with a _single configuration file_.
9+
10+
The implementation is highly modular and also allows straightforward implementation of custom Python handler scripts.
611

712
## Downloading
8-
_TBD_
13+
The easiest way to start is to clone the repository locally and then run it using `pipenv`.
14+
```shell
15+
# clone the repository
16+
git clone https://github.com/dolejska-daniel/lightweight-git-deployment.git
17+
cd lightweight-git-deployment
18+
19+
# create local configuration
20+
cp config/app.dist.yaml config/app.yaml
21+
cp config/logging.dist.yaml config/logging.yaml
22+
23+
# install dependencies
24+
pipenv install
25+
```
26+
27+
After you have configured all the bindings in the `config/app.yaml` configuration file, start the application by:
28+
```shell
29+
./scripts/start.sh
30+
```
31+
32+
### Requirements
33+
This project requires [`Python >= 3.9`](https://www.python.org/downloads/).
34+
With [`pipenv`](https://pypi.org/project/pipenv/), the project should be working out-of-the-box.
935

1036
## Usage
11-
_TBD_
37+
The `bindings` key in `config/app.yaml` is of `list[Binding]` type.
38+
39+
**`Binding`**<br>
40+
The `Binding`s are configured by providing corresponding **conditions** and **actions**.
41+
The structure is as follows:
42+
43+
| Key | Type | Description |
44+
|--------------|-------------------|--------------------------------------------------------------------------|
45+
| `conditions` | `list[Condition]` | Binding conditions determining whether the actions should be run or not. |
46+
| `actions` | `list[Action]` | Binding actions to be run if conditions are met. |
47+
48+
**`Condition`**<br>
49+
The `Condition` definition is of `dict[str, Any]` type.
50+
Its keys refer to fields of the received webhook event.
51+
Its values refer to the required values of the corresponding event field.
52+
53+
```yaml
54+
- created: false
55+
ref: refs/heads/master
56+
repository.full_name: dolejska-daniel/lightweight-git-deployment
57+
- sender.id: 10078080
58+
repository.full_name: dolejska-daniel/lightweight-git-deployment
59+
```
60+
61+
This example defines two `Condition`s.
62+
If any one of the two is met, the actions are run.
63+
For the `Condition` to be met all its rules must evaluate to `true`.
64+
The example will run the binding's action iff:
65+
- the event is a commit push to repository `dolejska-daniel/lightweight-git-deployment`
66+
- the event is sent by user with id `10078080` to repository `dolejska-daniel/lightweight-git-deployment`
67+
68+
**`Action`**<br>
69+
The `Action` object defines which actions are to be run iff the conditions were a match.
70+
The structure is as follows:
71+
72+
| Key | Typ | Description |
73+
|----------|------------------|-------------------------------------------------------------------|
74+
| `call` | `str` | Defines which method from which module should be called. |
75+
| `args` | `list[Any]` | Defines positional arguments to be supplied to the called method. |
76+
| `kwargs` | `dict[str, Any]` | Defines keyword arguments to be supplied to the called method. |
77+
78+
```yaml
79+
- call: plugin.git.pull
80+
args:
81+
- /opt/torscraper
82+
- origin
83+
- call: plugin.shell.command
84+
args:
85+
- make image
86+
```
87+
88+
This example defines two `Action`s.
89+
First action will run method `pull` in the `plugin.git` module.
90+
This method will perform a `git pull` from provided origin in the given repository.
91+
Then, the second action is run the same way.
92+
The method `plugin.shell.command` simply runs the provided command in a shell.
93+
94+
### Supported Events
95+
96+
#### GitHub Webhooks
97+
| Name | Description |
98+
|-----------|-------------|
99+
| `create` | [API Docs](https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#create)
100+
| `delete` | [API Docs](https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#delete)
101+
| `ping` | [API Docs](https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#ping)
102+
| `push` | [API Docs](https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#push)
103+
| `release` | [API Docs](https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#release)
104+

‎config/nginx.http.dist.conf‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
server {
2+
listen 80;
3+
listen [::]:80;
4+
5+
server_name example.com;
6+
server_tokens off;
7+
8+
# allow certbot challenges to go through to a local file system
9+
location /.well-known/acme-challenge {
10+
alias /var/www/example.com/public_html/.well-known/acme-challenge;
11+
}
12+
13+
# enforce https
14+
location / {
15+
return 301 https://$host$request_uri;
16+
}
17+
}

‎config/nginx.https.dist.conf‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
server {
2+
listen 443 ssl http2;
3+
listen [::]:443 ssl http2;
4+
5+
access_log /var/log/nginx/access.log;
6+
error_log /var/log/nginx/error.log;
7+
8+
access_log /var/www/example.com/logs/access.log;
9+
error_log /var/www/example.com/logs/error.log;
10+
11+
root /var/www/example.com/public_html;
12+
13+
# Add index.php to the list if you are using PHP
14+
index index.html index.htm;
15+
16+
server_name example.com;
17+
server_tokens off;
18+
19+
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
20+
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
21+
22+
# set max upload size
23+
client_max_body_size 512M;
24+
fastcgi_buffers 64 4K;
25+
26+
gzip on;
27+
gzip_types text/plain text/css application/javascript application/json image/x-icon application/octet-stream application/wasm;
28+
gzip_vary on;
29+
gzip_proxied no-cache no-store private expired auth;
30+
gzip_min_length 512;
31+
32+
location /deployer/ {
33+
proxy_redirect off;
34+
proxy_set_header Host $host;
35+
proxy_set_header X-Real-IP $remote_addr;
36+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
37+
proxy_set_header X-Forwarded-Proto $scheme;
38+
39+
rewrite ^/deployer/(.*)$ /$1 break;
40+
proxy_pass http://127.0.0.1:8080;
41+
}
42+
43+
location / {
44+
proxy_redirect off;
45+
proxy_set_header Host $host;
46+
proxy_set_header X-Real-IP $remote_addr;
47+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
48+
proxy_set_header X-Forwarded-Proto $scheme;
49+
50+
proxy_pass http://127.0.0.1:8080;
51+
}
52+
}

‎deployer/http/server.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
from deployer.config import AppConfig
88

99
log = logging.getLogger("deployer.http.server")
10+
alog = logging.getLogger("deployer.http.server.access")
1011

1112

1213
class Server(object):
@@ -15,7 +16,7 @@ class Server(object):
1516
def __init__(self):
1617
self._app = web.Application(logger=log)
1718
self._app.middlewares.append(self.error_middleware)
18-
self._runner = web.AppRunner(self._app, access_log=log, access_log_format='"%r" %s %b %Tf "%{User-Agent}i"')
19+
self._runner = web.AppRunner(self._app, access_log=alog, access_log_format='"%r" %s %b %Tf "%{User-Agent}i"')
1920
self._site: Union[web.TCPSite, None] = None
2021

2122
@classmethod

0 commit comments

Comments
 (0)