Write deployment documentation

[danielmewes]

trafficstars

https://github.com/rethinkdb/horizon-docs/blob/master/deploy.md is currently a stub

We don't need this for the 1.0 launch, but will need it when we publicly launch Horizon Cloud.

[chipotle]

I'm going to need a bit of guidance on a few bits of this:

• prerequisites for production mode rather than dev mode (i.e., start RethinkDB server separately, etc.)
• how to use hz make-token to get the admin user admin-ing
• basic advice about self-hosted deployment (i.e., is hz serve production ready or should they run a "real" web server and proxy to it, other general node stuff)
• anything about Horizon Cloud and DO support that's impending

[danielmewes]

prerequisites for production mode

• Starting your own RethinkDB server, or setting the start-rethinkdb option explicitly
• An SSL key/certificate pair (unless you want to run with secure=false)
• A schema file that includes all collections, indexes and permissions, which you can install through hz set-schema
• In fact you need to run hz set-schema once before you start the Horizon servers so that it can initialize the internal Horizon databases in RethinkDB.
• The correct bind setting to expose Horizon publicly

how to use hz make-token to get the admin user admin-ing

We will improve this interface, but at the moment you have to do the following:

1. Run hz make-token <project path> admin. This will print a token that is valid for one day.
2. Start the Horizon server if you haven't done so yet
3. In the browser, open the Horizon application. Then open the JavaScript console and run the following command:

horizon.utensils.tokenStorage.set("<the token from make-token>")

I assume here that the application defined a horizon object which is an instance of the Horizon class. If the instance has a different name, use that instead. Or if there isn't one, you have to instantiate Horizon first:

var hz = Horizon();
hz.utensils.tokenStorage.set("<the token from make-token>");

1. The application should now be authenticated as "admin" and can perform any administrative task through the browser (e.g. modifying the users collection in order to add users to groups)

Open question: Assume that the user wants to do the administrative task(s) through a node.js script rather than through the browser. How would one require the Horizon client in a node script and set the token in there? @deontologician ideas on if/how that could work?

self-hosted deployment

I believe it's fine to run hz serve by itself. There might be some questions about rate limiting to protect against DoS attacks. There also is the question of how to log requests, and how to start the server on system startup etc. I'm not sure if we have developed any best practices for these things yet. @encryptio @mlucy might have some tips.

Horizon Cloud and DO support

Horizon cloud will soon offer extremely a very simple way for deploying Horizon apps in the cloud. DigitalOcean offers a one-click Horizon droplet, see https://www.digitalocean.com/community/tutorials/how-to-use-the-horizon-one-click-install-image

[deontologician]

We need to provide a better interface in the client for using a token to authenticate. Right now we can use the utensils thing (which is really a non-official api), but it would be nice if users could create a horizon client instance and specify the token they want to use, without forcing the client to talk to localStorage. I'll open an issue for this