Hypothes.is brings community peer review to The Internet. It is a web application which enables rich annotation of web content. The project acts as a community aggregator for annotations and identity provider¹ for annotators. It also serves embed code for an annotation agent designed with modern web browsers in mind.

See INSTALL.rst for installation instructions. Platform specific instructions can be found in the install documents as well.

Installation has, hopefully, gone smoothly. If you ran into any problems, be sure to seek help on IRC or the mailing list. To run the server, simply use the run command:

$ ./run

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

The project builds heavily on components developed for the Annotator Project and is structured to encourage upstream contribution where possible. However, work is required to make Annotator more extensible in order to facilitate contribution.

Additionally, work is underway to support the data model described by the Open Annotation Core specification document.

See the project wiki for the roadmap and additional information and join us in #hypothes.is on freenode for discussion.

Those wishing to contribute to the project should also subscribe to the development mailing list and read about contributing. Then consider getting started on one of the issues that are ready for work. Issues tagged with the label 'New Contributor Friendly' are ideal for those just getting started.

The debugtoolbar package is loaded by default in the development environment. This will provide stack traces for exceptions and allow basic debugging. A more advanced profiler can also be accessed at the /_debug_toolbar path.

http://localhost:5000/_debug_toolbar/

Check out the documentation for information on how to use and configure it.

To run the test suite, ensure the assets are built and then invoke the tests in the usual fashion of Python:

$ ./bin/python setup.py test

As a convenience, there is a make target for this:

$ make test

Run the following command at the prompt to build the Chrome extension:

$ ./bin/hypothesis extension development.ini chrome http://localhost:5000

Or, to load the assets from within the extension:

$ ./bin/hypothesis extension development.ini chrome http://localhost:5000 \
chrome-extension://extensionid/public

To build the Firefox extension, run the following:

$ ./bin/hypothesis extension development.ini firefox \
http://localhost:5000 resource://firefox-at-hypothes-dot-is/hypothesis/data

If you are managing your virtual environment yourself, the script may not be located in the bin directory, but should be available in your path when the virtual environment is activated.

The fourth argument is the base URL for the application. An optional (for the Chrome extension), fifth argument may be passed to override the URL prefix used for static assets.

At this point, a working extension should exist in either ./build/chrome or ./build/firefox but with the development configuration the static assets are still loaded from the server. Start the application and ensure that the assets are built by visiting the home page or by running ./bin/hypothesis assets.

Note: Bundling the assets in the extension only works at the moment when the webassets.debug setting is falsy.

Deployment is mostly left as an exercise to the reader until we document this better. Using Docker or the shell environment it is easy to customize a few different deployment options.

The following docker link names are supported for automatic configuration of services:

• elasticsearch
• mail
• redis
• statsd

The following shell environment variables are supported:

• DATABASE_URL in the format used by Heroku
• SESSION_SECRET a unique string secret for cookie validation

By default, Hypothesis instantiates the Annotator.Host class defined in the injected code loaded by embed.js. It is possible to change this by assigning an alternate constructor to window.hypothesisRole. To customize the plugins that are loaded, define a function window.hypothesisConfig which returns an options object. This is then passed to the constructor as the second argument:

window.hypothesisConfig = function () {
  return {
    app: 'https://example.com/custom_sidebar_iframe',
    Toolbar: {container: '.toolbar-wrapper'}
  };
};

With the exception of app, the properties for the options object are the names of Annotator plugins and their values are the options passed to the individual plugin constructors.

The app property should be a url pointing to the HTML document that will be embedded in the page.

The full range of possibilities here is still in need of documentation and we would appreciate any help to improve that.

To build the documentation, ensure that Sphinx is installed and issue the `make html` command from the docs directory:

$ cd docs/
$ make html

Hypothes.is is released under the 2-Clause BSD License, sometimes referred to as the "Simplified BSD License" or the "FreeBSD License". Some third-party components are included. They are subject to their own licenses. All of the license information can be found in the included LICENSE file.