Hypothesis Direct-Link Bouncer Service

Installing bouncer in a development environment

You will need

• Git

• Node and npm. On Linux you should follow nodejs.org's instructions for installing node because the version of node in the standard Ubuntu package repositories is too old. On macOS you should use Homebrew to install node.

• pyenv Follow the instructions in the pyenv README to install it. The Homebrew method works best on macOS.

Clone the Git repo

git clone https://github.com/hypothesis/bouncer.git

This will download the code into an bouncer directory in your current working directory. You need to be in the bouncer directory from the remainder of the installation process:

cd bouncer

Start the development server

make dev

The first time you run make dev it might take a while to start because it'll need to install the application dependencies and build the assets.

This will start the server on port 8000 (http://localhost:8000), reload the application whenever changes are made to the source code, and restart it should it crash for some reason.

That's it! You’ve finished setting up your bouncer development environment. Run make help to see all the commands that're available for running the tests, linting, code formatting, etc.

Configuration

You can set various environment variables to configure bouncer:

CHROME_EXTENSION_ID

The ID of the Hypothesis Chrome extension that bouncer will communicate with (default: the ID of the official Hypothesis Chrome extension)

DEBUG

If DEBUG is set (to any value) then tracebacks will be printed to the terminal for any unexpected Python exceptions. If there is no DEBUG variable set in the environment then unexpected Python exceptions will be reported to Sentry and a generic error page shown to the user.

ELASTICSEARCH_URL

The url (host and port) of the Elasticsearch server that bouncer will read annotations from (default: http://localhost:9200)

ELASTICSEARCH_INDEX

The name of the Elasticsearch index that bouncer will read annotations from (default: hypothesis)

HYPOTHESIS_AUTHORITY

The domain name of the Hypothesis service's first party authority. This is usually the same as the domain name of the Hypothesis service (default: localhost).

HYPOTHESIS_URL

The URL of the Hypothesis front page that requests to bouncer's front page will be redirected to (default: https://hypothes.is)

SENTRY_DSN

The DSN (Data Source Name) that bouncer will use to report crashes to Sentry

VIA_BASE_URL

The base URL of the Via service that bouncer will redirect users to if they don't have the Hypothesis Chrome extension installed (default: https://via.hypothes.is)

Route Syntax/API

Share Annotations on Page/URL (/go)

Go to a specified URL and display annotations there. Optionally filter which annotations are displayed.

Querystring parameters:

• url (required): URL of target page/document
• group (optional): group ID. Show annotations within a specified group.
• q (optional): Search query. Filter annotations at URL to those that match this search query.

Share an Annotation (/{id} or /{id}/{url})

Go to an individual annotation, where id is the annotation's unique ID.

Optional url path parameter: URL of the annotation's target document. This is intended to enhance the readability of shared annotation URLs and is functionally identical to the /{id} route.