Documentation improvements

README.md

@@ -1,15 +1,19 @@
+![Hillview project logo](hillview-logo.pgn)
+
 # Hillview
 
 A big data spreadsheet.
 
+Here is a [short video](https://1drv.ms/v/s!AlywK8G1COQ_jaNkYmIRJyeSuvPeLA) of an
+  early version of the system.
+
 ## Dependences
 
-* Back-end: Ubuntu Linux (Technically we don't depend on Linux, it's
-  just that we have only tested this on Linux and Mac; the
-  instructions here are just for Linux)
+* Back-end: Ubuntu Linux or MacOS
 * Java 8, Maven build system, various Java libraries, in particular RxJava
   (Maven will manage the libraries for you)
 * Front-end: typescript, webpack, Tomcat app server, node.js
+* Management: Ansible
 * Some JavaScript libraries: d3 and rxjs
 * IDEA Intellij for development (optional)
 
@@ -20,16 +24,14 @@ Hillview is currently split into two separate Maven projects.
 * platform: pure Java, includes the entire back-end.  `platform` can be
 developed using the free (community edition) of Intellij IDEA.
 
-* web: the web server, web client and web services; this project links to the
-result produced by the `web` project.  To develop and debug this we have
-used capabilities available only in the paid version of Intellij, Ultimate,
-but only maven is needed to build.
+* web: the web server, web client and web services; this project links
+to the result produced by the `platform` project.  To develop and
+debug this we have used capabilities available only in the paid
+version of Intellij, Ultimate, but only Maven is needed to build.
 
 ## How to run the demo
 
-* If you don't want to run the demo, [here is a short
-  video](https://1drv.ms/v/s!AlywK8G1COQ_jaNkYmIRJyeSuvPeLA) of an
-  early version of the system
+These instructions describe how to run the demo on a single machine.
 
 * First install all software required as described
   [below](#installing-the-software-needed).
@@ -98,6 +100,11 @@ $ ./demo-frontend-start.sh
 
 * when you are done stop the two services by killing the scripts.
 
+## Deploying the Hillview service
+
+Instructions for managing the Hillview cloud service are given
+[here](#deployment/README.md)
+
 ## Contributing code
 
 ### Setup IntelliJ IDEA
@@ -167,7 +174,7 @@ In more detail, here is a step-by-step guide to committing your changes:
 Install Maven and node.js:
 
 ```
-$ sudo apt-get install maven nodejs-legacy
+$ sudo apt-get install maven nodejs-legacy ansible
 ```
 
 ### Installing Java

deployment/README.md

@@ -7,14 +7,18 @@ both `platform` and `web` projects.
 
 The servers also require `java` to be installed.
 
-
 ```
 $: cd deployment
 ```
 
-First, prepare a file named `hosts` and populate it with the hostnames or IP addresses
-of the servers. You need two groups of servers: 1) a `web` group with one server, and
-2) a `backends` group with all the backend servers. For instance:
+The fixed configuration of the Hillview service is obtained from the
+file `config.yaml`.  Currently this file only stores the service port.
+
+A deployment of the service is described by a file named `hosts`;
+create this file and populate it with the hostnames or IP addresses of
+the servers. You need two groups of servers: 1) a `web` group with one
+server, and 2) a `backends` group with all the backend servers. For
+instance:
 
 
 ```
@@ -26,8 +30,6 @@ of the servers. You need two groups of servers: 1) a `web` group with one server
 192.168.1.4
 ```
 
-The port used for the backend servers is specified in `config.yaml`.
-
 Verify that ansible is able to run commands on these servers:
 
 ```