Note: This tool is no longer maintained. There are a number of newer and better approaches to update jekyll-powered websites. We use Continious Integration (e.g. Travis) as a replacement for jekyll-hook at Development Seed. Read more here: https://jekyllrb.com/docs/deployment-methods/
A server that listens for webhook posts from GitHub, generates a website with Jekyll, 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 HTTP basic auth (see below for an NGINX config with basic auth), or want to host your site directly on a CDN or file host like S3. It's cutomizable with two user-configurable shell scripts and a config file.
This guide is tested on Ubuntu 16.0
First install main dependencies
$: sudo apt-get update
$: sudo apt-get install git nodejs ruby ruby-all-dev npm
$: sudo gem install bundler
Symlink nodejs to node
$: sudo ln -s /usr/bin/nodejs /usr/bin/node
To keep server running we use Forever:
$: sudo npm install -g forever
We also need Jekyll and Nginx
$: sudo gem install jekyll rdiscount json
$: sudo apt-get install nginx
Clone the repo
$: git clone https://github.com/developmentseed/jekyll-hook.git
Install dependencies:
$: cd jekyll-hook
jekyll-hook $: npm install
If you receive an error similar to this npm ERR! Error: EACCES, mkdir '/home/ubuntu/tmp/npm-2223-4myn3niN'
run:
$: sudo chown -R ubuntu:ubuntu /home/ubuntu/tmp
$: npm install
You should replace ubuntu
with your username
Copy config.sample.json
to config.json
in the root directory and customize:
$: cp config.sample.json config.json
$: vim config.json
Configuration attributes:
gh_server
The GitHub server from which to pull code, e.g. github.comtemp
A directory to store code and site filespublic-repo
Whether the repo is public or private (default is public)scripts
[branch-name]
(optional)build
The build script to run for a specific branch.publish
The publish script to run for a specific branch.
#default
build
The build script to run if no match was found for the branch specified in the webhook.publish
The publish script to run if match was found for the branch specified in the webhook.
secret
Optional. GitHub webhook secret.email
Optional. Settings for sending email alertsisActivated
If set to true email will be sent after each triggeruser
Sending email account's user name (e.g.example@gmail.com
)password
Sending email account's passwordhost
SMTP host for sending email account (e.g.smtp.gmail.com
)ssl
true
orfalse
for SSL
accounts
An array of accounts or organizations whose repositories can be used with this server
You can also adjust build.sh
and publish.sh
to suit your workflow. By default,
they generate a site with Jekyll and publish it to an NGINX web directory.
Set a Web hook on your GitHub repository
that points to your jekyll-hook server http://example.com:8080/hooks/jekyll/:branch
, where :branch
is the branch you want to publish. Usually this is gh-pages
or master
for *.github.com
/ *.github.io
repositories.
For every branch you want to build/publish (as defined in the scripts
) you need to set up a different webhook.
The default publish.sh
is setup for nginx and copies _site
folder to /usr/share/nginx/html/rep_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
For more information Google or read this:
$: ./jekyll-hook.js
To launch in background run:
$: forever start jekyll-hook.js
To kill or restart the background job:
$: forever list
info: Forever processes running
data: uid command script forever pid logfile uptime
data: [0] ZQMF /usr/bin/nodejs jekyll-hook.js 4166 4168 /home/ubuntu/.forever/ZQMF.log 0:0:1:22.176
$: forever stop 0
To publish the site on Amazon S3, you need to install S3cmd. On Ubuntu run:
$: sudo apt-get install s3cmd
$: s3cmd --configure
For more information read this.
scripts/publish-s3.sh
does the rest of the job for you. Just make sure to add your bucket name there.
The stock build.sh
copies rendered site files to subdirectories under a web server's www
root directory. For instance, use this script and NGINX with the following configuration file to serve static content behind HTTP basic authentication:
server {
root /usr/share/nginx/www;
index index.html index.htm;
# Make site accessible from http://localhost/
server_name localhost;
location / {
# First attempt to serve request as file, then
# as directory, then fall back to index.html
try_files $uri $uri/ /index.html;
# Optional basic auth restriction
# auth_basic "Restricted";
# auth_basic_user_file /etc/nginx/.htpasswd;
}
}
Replace this script with whatever you need for your particular hosting environment.
You probably want to configure your server to only respond POST requests from GitHub's public IP addresses, found on the webhooks settings page.