From 5f8fb2fcc5ccaede8cadcac8bb0344b00143528e Mon Sep 17 00:00:00 2001
From: Mike Gerwitz <gerwitzm@lovullo.com>
Date: Mon, 28 Aug 2017 14:20:47 -0400
Subject: [PATCH] doc: Server invocation and configuration

* doc/server.texi (Liza Server): Add information on starting the
    server.
  (Server Configuration): Add subsection.
---
 doc/server.texi | 50 ++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 41 insertions(+), 9 deletions(-)

diff --git a/doc/server.texi b/doc/server.texi
index ca9d777..10a3229 100644
--- a/doc/server.texi
+++ b/doc/server.texi
@@ -39,31 +39,63 @@ An example script to start the server is shown in @ref{f:server-start}.
        use @srcrefjs{server/daemon,DevDaemon},
        which uses a dummy encryption service.}
 
+To start the server,
+  invoke @srcref{bin/server}.
+You may also invoke @srcref{bin/server.js} directly using Node.js,
+  but the use of @srcref{bin/server} is recommended,
+    as it uses the Node.js executable determined at configure-time,
+    along with any command-line options required for Liza@tie{}Server
+      to function correctly.
+Additional options can be provided to Node.js using the
+  @var{NODE_FLAGS} environment variable,
+    which will be @emph{appended} to the configure-time flags.
+This environment variable is @emph{not} escaped or quoted,
+  so be mindful of word expansion.
+
 @float Figure, f:server-start
 @example
-  const @{ Daemon @}   = require( 'liza' ).server.daemon;
-  const port         = 8080;
-  const log_priority = 10;
+  $ bin/server -c path/to/config.json
 
-  Daemon( port, log_priority ).start();
+  # providing additional options to node
+  $ NODE_FLAGS=--debug bin/server -c path/to/config.json
 @end example
-@caption{Starting the server daemon}
+@caption{Starting the Liza Server}
 @end float
 
+
+
 @cindex HTTP Server
 The HTTP server is managed by
   @srcrefjs{server/daemon,http_server}.
 
 
 @menu
-* Requests::                    Handling HTTP requests.
-* Posting Data::                Handling step saves and other posts.
-* Server-Side Data API Calls::  Accessing external resources on the server.
-* Encryption Service::          Managing sensitive data.
+* Configuration:Server Configuration. Server configuration.
+* Requests::                          Handling HTTP requests.
+* Posting Data::                      Handling step saves and other posts.
+* Server-Side Data API Calls::        Accessing external resources on the server.
+* Encryption Service::                Managing sensitive data.
 @end menu
 
 
 
+@node Server Configuration
+@section Configuration
+@helpwanted{}
+
+@cindex Configuration
+Liza is migrating to actual configuration file in place of environment
+  variables.
+If no configuration is explicitly specified,
+  it uses @srcrefraw{conf/vanilla-server.json}.
+
+Configuration loading is handled by @srcrefjs{conf,ConfLoader}.
+The configuration store @srcrefjs{conf,ConfStore} is asyncrhonous,
+  so loading configuration from any external system is supported.@footnote{
+    Provided that you write the code to load from that system,
+      that is.}
+
+
 @node Requests
 @section HTTP Requests
 @helpwanted{}