Describe how to run Horizon server without the `hz` CLI

[rethinkdb]

Describe how to run Horizon server without the `hz` CLI

[Tryneus]

Here's a complete example script showing how to attach a Horizon server to multiple HTTP servers and add an auth endpoint (twitch) at the end. This assumes that a RethinkDB instance is running on localhost:28015, and that it has been initialized with hz set-schema.

'use strict';
const horizon = require('@horizon/server');

const fs = require('fs');
const http = require('http');
const https = require('https');

// Attach the horizon server to two http servers
// one on [::]:8181 over HTTPS and one on 127.0.0.1:8282 over HTTP
const on_http_request = (req, res) => {
  res.writeHead(404);
  res.end('File not found.');
};

const public_server = https.createServer({
  key: fs.readFileSync('key.pem'),
  cert: fs.readFileSync('cert.pem'),
}, on_http_request);

const loopback_server = http.createServer(on_http_request);

public_server.listen(8181);
loopback_server.listen(8282, '127.0.0.1');

const horizon_server =
  horizon([ public_server, loopback_server ], 
          {             
            project_name: 'foo',
            auth: {       
              token_secret: 'bar',
              allow_anonymous: true,
              allow_unauthenticated: true,
            },            
          });           

// Add twitch authentication
horizon_server.add_auth_provider(horizon.auth.twitch,
                                 {
                                   path: 'twitch',
                                   id: '0000000000000000000000000000000',
                                   secret: '0000000000000000000000000000000',
                                 });

// Shut down the server after 60 seconds
setTimeout(() => {
  horizon_server.close();
  public_server.close();
  loopback_server.close();
}, 60000);

[danielmewes]

It also looks like this technique always requires setting up your own HTTP server first. I'm not sure what the requirements on the http_servers argument actually are.

@Tryneus Could you add some details about this please?

[danielmewes]

A related question came up on the horizon issue tracker about how to run the Horizon server within Express: rethinkdb/horizon#425 (comment)

[danielmewes]

One non-obvious aspect of this is configuring OAuth providers. You can't pass the provider options directly into the Server constructor, but need to call a separate add_auth_endpoint method on the server.

Here's some example code:

var horizon_server = require('@horizon/server');

var horizon_options = {
    auth: {
        token_secret: 'xxxx',
        allow_anonymous: true,
        allow_unauthenticated: true
    }
};

// ...
// Code to construct the http_server, e.g. with Express
// ...

var horizon_instance = horizon_server(http_server, horizon_options);

// Add an OAuth endpoint for GitHub
horizon_instance.add_auth_provider(
    horizon_server.auth["github"],
    {id: "xxxx", secret: "xxxx", path: "github"});

[danielmewes]

We should also list the other supported options that can be passed into the server constructor.
The full list is represented here: https://github.com/rethinkdb/horizon/blob/next/server/src/schema/server_options.js

[danielmewes]

@Tryneus What is the meaning of these three options in the auth field?

duration: Joi.alternatives(Joi.string(), Joi.number().positive()).default('1d'),
create_new_users: Joi.boolean().default(true),
new_user_group: Joi.string().default('authenticated'),