Skip to main content

Webhook handler that can be used to deploy on push for example

Project description

Thin Deployer

[![Build Status](](
![Docker Build Status](
![GitHub release](
![PyPI - Python Version](
![PyPI - Wheel](

Securely runs your deployment commands triggered by a HTTP call.

Example case:
- POST an information to the /deploy/my-service
- Do the git pull && ./


Free software

Created for an anarchist portal, with aim to propagate the freedom and grass-roots social movements where the human and it's needs is on first place, not the capital and profit.



Default configuration path is ~/.deployer.yml, but can be specified with a switch `--configuration={{ file path }}`


# service definition (and service name there)
# token used to authorize via "token" GET parameter, or "X-Auth-Token" header
token: some-token-goes-here-use-only-at-least-64-characters-long-tokens

# optional: support for notifying Slack and other messengers
# with wolnosciowiec-notification-client
use_notification: true
notification_group: "logs"

# working directory to be in to execute every command
pwd: /var/www/app

# could be empty, if not empty then the deploy will execute
# only if the INCOMING REQUEST BODY will match this regexp
# useful for example to deploy only from a proper branch
request_regexp: "\"branch\": \"([production|stage]+)\""

# commands to execute in order
- git pull
- composer install --no-dev

# (...) there could be more service definitions

Installing via PIP

One of the ways, a traditional one is to install as a Python package on the host machine.

pip install Thin-Deployer
thin-deployer --configuration=/etc/thin-deployer/.deployer.yml

Installing via Docker

Modern and more secure way is to use a docker image to run the thin-deployer inside of an isolated container.

sudo docker run -p 8012:8012 -v ./deployer.yml:/root/.deployer.yml --rm --name thin-deployer wolnosciowiec/thin-deployer

Running dev environment

make install_dependencies

# simplest form with all default params
make run

# or advanced with possibility to add commandline switches
python3 ./bin/

##### Logging to file

Use `--log-file-prefix={{ path_to_log_file }}` switch to save logs to file.

#### Changing port number and bind address

- `--port={{ port_number }}` switch will change server listen port
- `--listen={{ ip_addres }}` makes server listen to given address, defaults to

Example request to trigger the deployment

POST /deploy/phpdenyhosts HTTP/1.1
Host: localhost:8012
X-Auth-Token: some-token-goes-here-use-only-at-least-64-characters-long-tokens


Example response

"output": "Command \"ls -la /nonexisting\" failed, output: \"b''\""

- X-Runs-As: UNIX username of a user on which privileges the server is working on


- Python 3
- python-yaml
- Tornado Framework
- py-healthcheck
- [Wolnościowiec Notification server set up somewhere]( (optionally - only for notifications)
- [Wolnościowiec Notification Shell Client]( (optionally - only for notifications)

Health checking

Service provides a simple monitoring endpoint at GET /technical/healthcheck

Authorization is done in two ways.
Its up to you to use a preferred one in a request to the endpoint.

- A header `X-Auth-Token` with a token as a value
- Basic authorization data, login can be any, as a password please type the token

Examples of headers:
- Authorization: YWFhOnRlc3Q=
- X-Auth-Token: test

#### Configuration

Health check endpoint is configurable via environment variables.

- `HC_TOKEN={{ token }}` health check access token
- `HC_MIN_TOKEN_LENGTH={{ min_length }}` minimum length of a token in every service
- `HC_MAX_DISK_USAGE={{ max_disk_usage_percentage }}` defaults to 90 (it's 90%), when disk usage is higher or equals to this value then an error will be reported


- Webhook:


Each deployment can produce a notification with output, supported notification format is Slack/Mattermost (webhook url required)

Good practices of securing the service

1. Its good to use long tokens
2. Hide the service behind a load balancer with a request rate per second limited (to avoid brute force attacks)
3. Optionally add a basic auth (this may impact usage of the service by external client applications)
4. Use SSL behind load balancer when service is called from the internet

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for Thin-Deployer, version 1.1.0
Filename, size File type Python version Upload date Hashes
Filename, size Thin_Deployer-1.1.0-py3-none-any.whl (14.4 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size Thin-Deployer-1.1.0.tar.gz (16.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page