pdf.js-bot

This bot is used by pdf.js reviewers to run regression tests. The bot lives in server.js and requires node.js. See instructions below on how to set it up.

Reviewer workflow

Performing regression test

1. User submits pull request to main repo
2. Reviewer leaves comment @pdfjsbot test
3. @pdfjsbot clones repo of requester; checks out top SHA of pull request; pulls pdf.js-ref repo containing snapshots; runs make test in requester repo; and comments back with the results of test

Generating reference snapshots

1. User submits pull request to main repo containing new features
2. Reviewer leaves comment @pdfjsbot makeref
3. @pdfjsbot clones repo of requester; checks out top SHA of pull request; runs make master in requester repo; and (force-)pushes snapshots to pdf.js-ref repo

Troubleshooting

Logging into EC2

To log into the server:

$ ssh -i <ssh_key_file.pem> ubuntu@<ec2_machine_address>

The two unknowns above should be known by the bot collaborators.

Log file

This is the first place to take a peek at:

/tmp/bot.log

(TODO: place file in /var/log and configure logrotate)

Updating and restarting bot

There's a script for that:

$ cd pdf.js-bot/
$ ./update

Restarting bot

$ cd pdf.js-bot/
$ forever stop 0
$ forever start -o /tmp/bot.log server.js

And cross your fingers :)

Setting up bot server

Distro and basics

The instructions below assume we'll be deploying on Ubuntu 11.04. See http://alestic.com/ for a list of EC2 images.

1. $ sudo apt-get update
2. Install via apt-get: make, g++

Browser, Xvfb

1. Install via apt-get: firefox, xvfb (necessary as we will run browsers without a display)

2. Test xvfb via $ xvfb-run firefox. Firefox shouldn't bail out with a no-display message.

3. Configure xvfb by appending to /etc/profile:

    /usr/bin/Xvfb :1 1>/dev/null 2>/dev/null &
    export DISPLAY=:1
   

Git, Github

1. Install via apt-get: git

2. Create Github ssh key in ~/.ssh: $ ssh-keygen -t rsa -C "pdfjsbot@gmail.com"

3. DO NOT ADD AN SSH PASSWORD TO THE KEY. This requires setting up ssh-agent and a password prompt upon every boot.

4. Log into Github as @pdfjsbot, add public ssh key from file ~/.ssh/id_rsa.pub

5. Test ssh key: $ ssh -T git@github.com

6. Set up ssh agent to avoid repeated password entry: $ exec ssh-agent bash, $ ssh-add ~/.ssh/id_rsa

7. Configure git signatures: $ git config --global user.name "pdfjs bot", git config --global user.email "pdfjsbot@gmail.com"

8. Set Github API credentials by appending to /etc/profile:

    export GITHUB_CREDENTIALS=pdfjsbot:<password_here>
   

9. Run $ /etc/profile, or $ sudo reboot to effect profile changes

Node.js

1. Install nodejs and nodejs-dev from binaries: https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager
2. Make sure nodejs-dev and g++ are installed before proceeding!
3. Install node.js package manager npm: $ curl http://npmjs.org/install.sh | sudo sh
4. Install global node utility forever: $ sudo npm install -g forever

Bot

1. Clone repo into home dir: $ git clone <pdf.js-bot-URL>
2. Install required node packages: $ cd pdf.js-bot; npm install
3. Configure browser manifest file: test-files/browser_manifest.json

Launch: Production

1. Check if default parameters are OK: config.json
2. Start bot with $ forever start -o /tmp/bot.log server.js
3. (You can stop server with $ forever stop 0)

Launch: Staging

(Use this for local tests)

1. Configure parameters for your own tests in: config_staging.json
2. Set environment variable $ export PDFJSBOT_STAGING=yes
3. Start bot with $ node server.js