WebHawk - A Webhook Microframework

What is WebHawk?

WebHawk is a simple micro-framework which helps you create webhooks for Continuous Deployment of your Bitbucket/Github hosted projects.

What's in the box?

WebHawk comes with:

A RESTful API which exposes the WebHook Endpoints
Command line tool to trigger Build-Tasks manually
Support for git Repositories
Support for Bitbucket WebHooks

WebHawk does not come with:

WebUI to create the build descriptions (called Recipes).
Support for svn, mercurial, or other VCS.
Support for git events other than PUSH.

WebHawk also comes with a few secondary features:

It's easy to extend; with a bit of coding you can add support to other VCS systems and/or WebBased VCS hosting services.
It can run the builds on a different server than the one it runs on.

How does it work?

WebHawk implements a RESTful API which is capable of reading POST payloads from BitBuckt (and soon Github).

Then:

Translates the payload into a build task and spawns a builder.
Reads a corresponding build recipe.
Checks out your git project.
Launches the build command.
That's it really.

What do I need to get started?

You need:

The project you want to build hosted on Bitbucket (and soon Github)
A public-facing server with the following pre-installed:
1. Python 2.7
2. pip
3. (optionally) SSH
A tiny bit of configuration

How do I get started?

You basically need to perform three major actions:

Prepare your Recipe file
Start WebHawk
Create your webhooks on Bitcubket or Github

1. Prepare your recipe file

The recipe file is a yaml file that contains information on what should WebHawk do when it receives a payload.

Here's an example:

#
# WebHawk Recipies Configuration File
#
myapp-dev:
  repository:
    name: myapp
    branch: dev
    url: "git@bitbucket.org:stek.io/website.git"
    vcs: git
  command: "python ./bin/fabfile.py -f -s -a build"

The example above contains 1 Recipes with ID "myapp-develop" which specifies the details of a Repository and the build command. Few things you need to consider:

The Repository defines 4 properties: name, branch, url and the vcs (Version Control System)
The Name, the Branch and the URL must be the same as your project in Bitbucket.
You do not specify an SSH Key in the Recipe, but you must configure your ~/.ssh/config if the Repository is exposed via SSH. Read this article for more details.

A very important configuration is the command. As you may have guessed, this is the command that will be executed on a shell after your project is checked out. The command always runs from inside the root directory of your project. This means that you can either choose to invoke a script that comes with your project, or a script that you have placed somewhere else on the build server.

For example, you could upload a script on /home/steve/scripts/build_website.sh and setup a recipe like this:

mywebsite:
  repository:
    name: acme-website
    branch: master
    url: "git@bitbucket.org:acme.online/acme-website.git"
    vcs: git
  command: "/home/steve/scripts/build_website.sh ./"

Although the directory which WebHawk checks out your project is different everytime (WebHawk creates a directory with a random name before checking out code), it ensures that the build command will run from within your project's directory.

After you have created your Recipe file with your Recipes, proceed to the next step.

2. Start WebHawk

Before you start WebHawk, you need to bootstrap the environment. The following command will setup a Python Virtual Environment and install all python libraries:

$ ./bin/bootstrap.sh

To activate this environment on your console, run:

$ source webhawk-venv/bin/activate

When the virtual env is active, you will see your prompt changing into something like this:

(webhawk-venv)dimi@Neutron~/workspaces/webhawk$

Tip: You can always exit the virtual environment by typing the command deactivate on your console.

Now you can start WebHawk with two ways:

Using the start.py script which starts a single threaded WebServer. This should be enough for a single project and a small team.
Using gunicorn which scales much better when you have many Recipes and many triggers via webhooks.

2.1 Using start.py

If you have your webhawk-venv Python Environment activated, simply run: $ ./webhawk/start.py within the project root directory.

You will see something like this on your console:

2016-09-08 16:46:53,780 - webhawk         - 19407 - INFO   - === WebHawk Services Starting ===
2016-09-08 16:46:53,789 - webhawk         - 19407 - INFO   - Loading Recipes from file 'config/recipes.yaml'
2016-09-08 16:46:53,789 - webhawk         - 19407 - INFO   - Initializing Git VCS Managers
2016-09-08 16:46:53,789 - webhawk         - 19407 - INFO   - Initializing Builder
2016-09-08 16:46:53,791 - webhawk         - 19407 - INFO   - WebHawk RESTful API Initiated
2016-09-08 16:46:53,796 - werkzeug        - 19407 - INFO   -  * Running on http://0.0.0.0:5000/ (Press CTRL+C to quit)

2.2 Using gunicorn

TBD

3. Setup Webhooks on your Project hosting service.

TBD

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

dtsolis/webhawk