How to setup Hypothesis locally for development on Arch Linux

What is Hypothesis

Hypothesis is a web annotator. It allows users to create notes on any web page and PDF. As it says on the project website:

Our team is building an open platform for discussion on the web. It leverages annotation to enable sentence-level critique or note-taking on top of news, blogs, scientific articles, books, terms of service, ballot initiatives, legislation and more.

It is currently available as a Chrome extension, Firefox add-on, and a bookmarklet. Being open-source anyone can contribute to the project and make the web easier for peer review.

The Operating system. Antergos -> Arch Linux

The operating system I am using is called Arch Linux. Since I wanted to get up and running quickly, I used Antergos for the installation media. Antergos is Linux distribution based on Arch Linux. It provides an easy way to install and get started with Arch. It also provides 6 different options for desktop environments. And it does not add any unnecessary bloat-ware on top of the base OS. Unlike other Arch based OSs, Antergos leaves the Arch base intact and simply uses its own repository to provide some packages that Antergos devs think should be provided.

Installing required software

The following software is required to run Hypothesis locally:

  • GIT

    sudo pacman -S git
  • Python 2.7

    sudo pacman -S python2
  • Node.js

    sudo pacman -S nodejs
  • NPM (is provided separately in Arch)

    sudo pacman -S npm
  • Ruby

    sudo pacman -S ruby
  • Compass

    gem install compass
  • ElasticSearch

    sudo pacman -S elasticsearch
  • ICU Analysis for Elasticsearch (The version number can change. Check here for up-to-date plugin install path)

    sudo elasticsearch-plugin -i lasticsearch/elasticsearch-analysis-icu/2.5.0
  • NSQ (Must be built from AUR)

    yaourt -S nsq
  • libevent

    sudo pacman -S libevent
  • libffi

    sudo pacman -S libffi
  • libpq

    sudo pacman -S libpq
  • libyaml

    sudo pacman -S libyaml
  • python-pip

    sudo pacman -S python-pip
  • python-virtualenv

    sudo pacman -S python-virtualenv

Setting up the development environment

The set up process is a little different from the instructions provided by the project. For setting up in Arch follow these steps:

  1. Clone the Hypothesis repository from GitHub

    git clone
  2. Change into the newly created ‘h’ directory

    cd h
  3. Create a python virtual environment to work in

    virtualenv --python=python2.7 h

    (–python=python2.7 is used in case there are multiple python versions present)

  4. Activate the virtual environment

    source h/bin/activate

    (At any point if you wish to deactivate just type deactivate)

  5. Get the python and node dependencies

    make deps

Starting Hypothesis locally

Now that all the software is installed, we are going to start Hypothesis with the following steps:

  1. Start ElasticSearch using systemctl

    sudo systemctl start elasticsearch
  2. Start NSQ. Type the following in terminal

  3. Now start the server from within you ‘h’ directory

    make dev
  4. Open a web browser and enter http://localhost:5000/. Your local version of Hypothesis should load

Stopping everything after development

Once your development is finished and you would like to stop the servers and daemons, you can enter the following commands:

  • To stop the Hypothesis

    ctrl+C in the terminal tab/window that was running it
  • To stop NSQ

    ctrl+C in the terminal tab/window you ran it in
  • To stop ElasticSearch

    sudo systemctl stop elasticsearch

Happy Hacking 🙂


2 replies »

  1. Hi. Thanks for this post – I am very interested in getting my own instance of running if possible. Could you please advise if you know whether the browser extensions can also be configured to use the self-hosted instance to store a stream? Thanks again.


    • There is an option in the Makefile of Hypothesis to build a Docker image.

      make docker

      I believe you should be able to create an image and deploy it to your local servers.

      I haven’t tried it though.