hazybluedot / jekyll-html-hook

:anchor: Webhook listener for deploying Jekyll or static HTML sites

jekyll-html-hook

A server that listens for webhook posts from GitHub, generates a website with Jekyll, or just copies files in the case of a static HTML site and moves it somewhere to be published.

Use this to run your own GitHub Pages-style web server. Great for when you need to serve your websites behind a firewall, need extra server-level features like HTTPS for your domain or HTTP basic auth. It's cutomizable with a config file.

The original concept for this is heavily influenced by Development Seed's NodeJS based project, jekyll-hook.

Dependencies Installation

First install main dependencies

sudo apt-get update
sudo apt-get install git python3.4-dev ruby ruby1.9.1-dev redis-server nginx

We also need Jekyll

sudo gem install jekyll rdiscount json

Installation

We recommend using virtualenv and virtualenvwrapper for working in a virtualized development environment. Read how to set up virtualenv. One thing to remember is that this app requires at least Python 3.4.

Once you have virtualenvwrapper set up,

mkvirtualenv jekyll-html-hook
git clone https://github.com/hazybluedot/jekyll-html-hook.git
cd jekyll-html-hook
pip install -r requirements.txt

Afterwards, whenever you want to work on jekyll-html-hook,

workon jekyll-html-hook

Configuration

Copy app_config.py.example to app_config.py in the root directory and customize:

cp app_config.py.example app_config.py
vim app_config.py

Configuration attributes:

• GH_SERVER The GitHub server from which to pull code, e.g. github.com
• TEMP A directory to store code and site files
• SECRET Optional. GitHub webhook secret.
• SCRIPTS A dictionary where the keys are the names of the kinds of sites you have (by default this app can handle generating a Jekyll site or just handle static HTML) and the values are the relative paths to the scripts that are used to build and/or deploy those sites.
• ACCOUNTS A list of organizations whose repositories can be used with this server.
• SENTRY_DSN Optional. DSN to configure Sentry logging.

You can also adjust the default scripts in the scripts directory to suit your workflow. By default, they generate a site with Jekyll or just copy static HTML files and publish it to an NGINX web directory.

Webhook Setup on Github

Set a Web hook on your GitHub repository that points to your jekyll-html-hook server https://example.com/hooks/:site_type/:branch, where :site_type one of the site types you configured in the SCRIPTS variable above (by default either jekyll or static) :branch is the branch you want to publish. So, for example, if you'd like to configure a webhook for a Jekyll site and only deploy when you push to the deploy branch, your webhook URL would look like this:

https://example.com/hooks/jekyll/deploy

Configure a webserver (nginx)

The default publish.sh is setup for nginx and copies the generated (or static) HTML to /usr/share/nginx/html/<repo_name>.

If you would like to copy the website to another location, make sure to update nginx virtual hosts which is located at /etc/nginx/nginx/site-available on Ubuntu 14.

You also need to update publish.sh

An example Nginx configuration (complete with Gzip and SSL/TLS settings based upon using Let's Encryt) is in the scripts folder

Run the app

There are two processes, one to handle incoming webhooks and one to actually generate and/or deploy the site.

python app.py
python worker.py

As an an example of how you might daemonize the app and worker, an example Supervisor configuration file is in the scripts folder.

Run in production

For production-like environments we need something a little more robust than running the app and worker manually. Files in etc contain templates for systemd services that will start the main app via gunicorn and the worker process. For convenience install.sh is provided which will write the files to the appropriate system directories. Be sure to edit install.sh first to set the three variables appropriately:

• LOGPATH The path to the logging directory. It should be writable by the user the service will run as.
• VENV_BIN The path to the virtual environment bin directory. Python and gunicorn will be run from this location.

Other random stuff

You probably want to configure your server to only respond POST requests from GitHub's public IP addresses, found on the webhooks settings page.

Team

• Eric van Zanten - developer
• Derek Eder - developer

Errors / Bugs

If something is not behaving intuitively, it is a bug, and should be reported. Report it here: https://github.com/datamade/jekyll-html-hook/issues

Note on Patches/Pull Requests

• Fork the project.
• Make your feature addition or bug fix.
• Send a pull request. Bonus points for topic branches.

Copyright

Copyright (c) 2016 DataMade. Released under the MIT License.