Write documentation for setting up and running a production instance of h

[robertknight]

A number of parties have come to us looking to do small/medium-scale deployments of h, eg. within an organization. Our documentation at https://h.readthedocs.io currently only explains how to run h locally in development, it doesn't say anything about how to do a production deployment.

While different sizes of deployments are going to have some differences with respect to how a deployment works, a lot of what needs to happen (eg. building and running Docker containers, supplying configuration via env vars, setting up Postgres/ES/RabbitMQ) will be the same regardless of the infrastructure.

This documentation should cover topics such as:

• Building and running the Docker image of h (or perhaps using our existing Docker image)
• Setting up and connecting h to the required services
• Setting up the database and ES indexes
• Handling authentication
• Updating to a newer version of h
• Supplying configuration via environment variables
• What needs to be backed up and what doesn't ... and no doubt a bunch of other things I haven't mentioned here

There are other issues to think about as well, such as how we manage versions designed to be used by third parties.

[seanh]

We did once have public docs for how to deploy h in production, but we deliberately removed them.

I don't think we should support or encourage people hosting their own instances of h (now or ever).

It is a long-term (but not a short-term) aim to have a generic "annotations service" that people can host their own instances of. But this web app (hypothesis/h) isn't intended to be that service. Rather it's largely "the Hypothesis web service", a Hypothesis-specific SAAS product that we host. It contains a lot of stuff that is specific to Hypothesis the organization, the particular instance of the service that we run, our particular client, etc.

We had the h / memex split and then re-merge. Memex, not h, was the thing you would host your own instance of. But we backed out of doing Memex because it wasn't the time yet.

I also don't think we can realistically / practically support people hosting their own h right now. Providing support for people who host their own instances is a big task that we're not really focused on or set up to do. To give just one example: we don't release versions of h, maintain a changelog, support backwards compatibility and ongoing support for older versions, etc. We deliberately set up not to do these things because we're set up, instead, to ship changes quickly and frequently to the one instance of the service that we run. In many ways the two things are opposites.

[segdeha]

I agree that there are implications for our internal processes to supporting, in any formal way, installed instances out in the wild. I want to make clear that there is a difference here between hobbyists (for lack of a better term) and paid partners. Some of the same complications arise, but in the case of close partners, we can work together to figure some of those things out based on their actual needs (e.g., they may not need us to do semver releases of our API, we won't know for sure without direct experience). My hope is that by working with a limited set of partners we can get sorted some of the issues you bring up in order to make it easier for us in the future to better/more fully support hobbyist/non-paying partners to make reasonable use of our software as well.

I do know we get a lot of questions in our open Slack team about getting h up and running, so—if people are going to be installing it, anyway (and that's their right given it's free & open source)—we may want to reduce the support burden on ourselves by documenting how to stand up a simple instance.

[seanh]

"there is a difference here between hobbyists (for lack of a better term) and paid partners" <- Completely agree with this