From 086ca2848f1147c71395689d8488162aa67590c4 Mon Sep 17 00:00:00 2001 From: Scisco Date: Thu, 17 Jul 2014 12:30:45 -0400 Subject: Updated readme file with more helpful help --- readme.md | 42 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 36 insertions(+), 6 deletions(-) (limited to 'readme.md') diff --git a/readme.md b/readme.md index 948f474..3f59f4b 100644 --- a/readme.md +++ b/readme.md @@ -2,21 +2,48 @@ 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 14.0* + +## Dependencies Installation + +First install main dependencies + + $: sudo apt-get update + $: sudo apt-get install git nodejs ruby ruby1.9.1-dev npm + +To keep server running we use Forever: + + $: sudo npm install -g forever + +We also need Jekyll and Nginx + + $: sudo gem install jekyll + $: sudo gem install rdiscount + $: sudo gem install json + $: sudo apt-get install nginx + ## Installation -- run `$ npm install` to install app dependencies -- 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. +Clone the repo + + $: git clone https://github.com/developmentseed/jekyll-hook.git + +Install dependencies: + $: npm install + +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. ## Configuration -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. +Copy `config.sample.json` to `config.json` in the root directory and customize: -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 +- `gh_server` The GitHub server from which to pull code, e.g. github.com - `temp` A directory to store code and site files - `scripts` - `build` A script to run to build the site @@ -24,9 +51,12 @@ Configuration attributes: - `email` Optional. Settings for sending email alerts - `user` Sending email account's user name (e.g. `example@gmail.com`) - `password` Sending email account's password - - `host` SMTP host for sending email account (e.g. `smtp.gmail.com`) + - `host` SMTP host for sending email account (e.g. `smtp.gmail.com`) - `ssl` `true` or `false` 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. + ## Usage - run as executable: `$ ./jekyll-hook.js` -- cgit v1.2.3 From 671fb1a650b0e5ae62e425b348742043a4069b95 Mon Sep 17 00:00:00 2001 From: Scisco Date: Thu, 17 Jul 2014 13:43:11 -0400 Subject: Updated readme/help --- readme.md | 106 +++++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 60 insertions(+), 46 deletions(-) (limited to 'readme.md') diff --git a/readme.md b/readme.md index 3f59f4b..eaaf462 100644 --- a/readme.md +++ b/readme.md @@ -1,6 +1,12 @@ # jekyll-hook -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. +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 14.0* @@ -11,15 +17,17 @@ First install main dependencies $: sudo apt-get update $: sudo apt-get install git nodejs ruby ruby1.9.1-dev npm +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 - $: sudo gem install rdiscount - $: sudo gem install json + $: sudo gem install jekyll rdiscount json $: sudo apt-get install nginx ## Installation @@ -30,9 +38,15 @@ Clone the repo Install dependencies: - $: npm install + $: 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 -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. +*You should replace `ubuntu` with your username* ## Configuration @@ -45,21 +59,55 @@ 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 +- `public-repo` Whether the repo is public or private (default is public) - `scripts` - `build` A script to run to build the site - `publish` A script to run to publish the site - `email` Optional. Settings for sending email alerts + - `isActivated` If set to true email will be sent after each trigger - `user` Sending email account's user name (e.g. `example@gmail.com`) - `password` Sending email account's password - `host` SMTP host for sending email account (e.g. `smtp.gmail.com`) - `ssl` `true` or `false` for SSL -- `accounts` An array of accounts or organizations whose repositories can be used with this server +- `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. + +## Webhook Setup on Github + +Set a [Web hook](https://developer.github.com/webhooks/) 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. + +## Configure a webserver (nginx) + +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](https://www.digitalocean.com/community/tutorials/how-to-configure-the-nginx-web-server-on-a-virtual-private-server): + +## Launch + + $: ./jekyll-hook.js -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. +To launch in background run: -## Usage + $: forever start jekyll-hook.js -- run as executable: `$ ./jekyll-hook.js` +To kill 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 +``` ## Publishing content @@ -87,39 +135,5 @@ server { 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. - -## Dependencies - -Here's a sample script to install the approriate dependencies on an Ubuntu server: - -```sh -#!/bin/sh - -# Install node and depencencies -sudo apt-get update -y -sudo apt-get install python-software-properties python g++ make -y -# On Ubuntu 12.10 and greater, add-apt-repository is provided by the software-properties-common package -#sudo apt-get install software-properties-common -y -sudo add-apt-repository ppa:chris-lea/node.js -y -sudo apt-get update -y -sudo apt-get install nodejs -y - -# Forever to keep server running -sudo npm install -g forever - -# Git -sudo apt-get install git -y - -# Ruby -sudo apt-get install ruby1.8 -y -sudo apt-get install rubygems -y - -# Jekyll -sudo gem install jekyll --version "0.12.0" -sudo gem install rdiscount -- version "1.6.8" -sudo gem install json --version "1.6.1" - -# Nginx for static content -sudo apt-get install nginx -y -``` +You probably want to configure your server to only respond POST requests from GitHub's +public IP addresses, found on the webhooks settings page. -- cgit v1.2.3 From dfa0e4dd18bc637d883f2264ed6eb8680e99ded4 Mon Sep 17 00:00:00 2001 From: Scisco Date: Thu, 17 Jul 2014 14:16:11 -0400 Subject: minor fix in readme --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'readme.md') diff --git a/readme.md b/readme.md index eaaf462..1aad748 100644 --- a/readme.md +++ b/readme.md @@ -99,7 +99,7 @@ To launch in background run: $: forever start jekyll-hook.js -To kill the background job: +To kill or restart the background job: ``` $: forever list -- cgit v1.2.3 From 3df8dcf63b875f16629d8c428b4a136c7004d5bd Mon Sep 17 00:00:00 2001 From: Scisco Date: Thu, 17 Jul 2014 15:05:10 -0400 Subject: Another fix in the readme file --- readme.md | 1 + 1 file changed, 1 insertion(+) (limited to 'readme.md') diff --git a/readme.md b/readme.md index 1aad748..464d906 100644 --- a/readme.md +++ b/readme.md @@ -45,6 +45,7 @@ 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* -- cgit v1.2.3 From 54d4b6cc127a786506cbf4b0abc0ee8e8cc55c56 Mon Sep 17 00:00:00 2001 From: Scisco Date: Thu, 17 Jul 2014 15:52:43 -0400 Subject: Added S3 help to readme --- readme.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'readme.md') diff --git a/readme.md b/readme.md index 464d906..44d91e9 100644 --- a/readme.md +++ b/readme.md @@ -112,6 +112,19 @@ To kill or restart the background job: ## Publishing content +### S3 + +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](http://xmodulo.com/2013/06/how-to-access-amazon-s3-cloud-storage-from-command-line-in-linux.html). + +`scripts/publish-s3.sh` does the rest of the job for you. Just make sure to add your bucket name there. + +### More details on build.sh + 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: ``` -- cgit v1.2.3