Server
The Kestrel Server setup requires three things:
- A GitHub "team" designating members who have S3 publish privileges.
- A server running Snow Owl Server. This will mirror your watched projects and be your staging web server for them. It will also deploy your projects to S3.
- The command-line interface installed on your local machine.
We'll be creating some permission access tokens so open up a blank text document as your scratch pad.
To generate an access token, go to the Tokens panel of your account settings. The permissions it needs are:
-
repo- used to read and update private repos. -
public_repo- same as above but for public repos. -
read:org- (recommended) used to authenticate whether the committer has publish privileges.
Make note of this token since we'll be entering it for config.json.
Kestrel is a workflow tool, at its heart, to minimize mistakes and improve security when publishing to the web. What this translates to for you is setting up permissions so that only those who are allowed to publish can publish.
This step is optional but highly recommended. You'll be making a team on GitHub that includes only users that can publish to the web. This step is useful if you are working with a freelancer or another reporter who is going to be committing code and thus needs full push access to the repo, but you don't want to risk accidentally publishing anything. Because the publish interface gives you flexibility about your remote path, i.e. you get to pick the name of the folder you publish into, you could accidentally overwrite old projects or, through a typo, create a random directory.
To make a team, go to your organization's "Teams" page, choose your desired name (I like "Publishers") and add your members. Now, let's get the team id.
To get the team id, use the GitHub API to retrieve the list of your organization's teams from the following url, replacing :org with your organization's name and :access_token with an administrator's access token you made in the previous step. Note: the account that owns the access token also has to be a member of the team.
https://api.github.com/orgs/:org/teams?access_token=:access_token
For Al Jazeera America this URL would look like this (with a dummy access token of course):
https://api.github.com/orgs/ajam/teams?access_token=6YvTV287ULA8x6zas&Mv4g]KMLMJ
Make note of the id number. It should look like this:
Install the server on some other machine. Tested on an Amazon EC2 instance running Ubuntu 12.04.
sudo apt-get update
sudo apt-get install -y python-software-properties python g++ make python-pip
sudo apt-get install tmux
sudo add-apt-repository ppa:chris-lea/node.js
sudo apt-get update
sudo apt-get install nodejs
sudo apt-get install mailutils # For crontab logs, say okay to all prompts
sudo apt-get install git-core
I like to install things in a folder called tasks .
mkdir tasks
cd tasks
git clone https://github.com/mhkeller/kestrel && cd kestrel
sudo npm install
sudo pip install awscli
Rename config.sample.json to config.json and set your values. If you want to publish your files to S3, set up your aws credentials.
Install the Forever module
npm install forever -g
This will set up the sever that listens for changes in GitHub to run all the time. The paths assume you've installed it on Ubuntu 12.04, your username is ubuntu and you've installed the server files in a folder called tasks
forever start /home/ubuntu/tasks/kestrel/src/server.js
Also make sure the server starts up on reboot by opening up your crontab with crontab -e
Add this line in your file. This assume Forever module was installed in /usr/bin/. To test on your machine, run which forever.
@reboot /usr/bin/forever start /home/ubuntu/tasks/kestrel/src/server.js
Install the previewer, which is a library called git-static-diffuse
sudo npm install -g git-static-diffuse
The previewer works by being passed a folder containing git repositories using the moire start command.
forever start /usr/bin/moire start --repositories /home/ubuntu/tasks/kestrel/repositories
And, like we did before, make sure it starts on reboot
@reboot /usr/bin/forever start /usr/bin/moire start --repositories /home/ubuntu/tasks/kestrel/repositories
Make sure the ports you've selected for each of these servers are open. If you're running on Amazon EC2, do this in the Security Group. If you haven't changed the default ports, the listener will be on 9001 and the preview server will be on 3000.
If you go to http://<your-kestrel-server-url>:9001 you should see something like the picture below. You won't have any repositories yet, though.
Now you should follow the command-line interface set-up to keep going.
You're on a roll!