Update presto-admin documentation

* Remove Presto version from presto-cli-installation docs
* Clarify SSH requirements for presto-admin
* Document adding a connector in the Quick Start Guide
* Add Presto configuration to the Quick Start Guide
* Add warning in Java 8 installation about RPM install
* various grammatical edits
* Move port configs docs after server install.
* Add comma to presto-admin-configuration config.json specification

The user should first run `presto-admin server install` before updating the port, so that
the default values for the configs are already there.

Author: cawallin

docs/installation/java-installation.rst

@@ -7,11 +7,13 @@ Prerequisites: :ref:`presto-admin-installation-label` and :ref:`presto-admin-con
 
 The Oracle Java 1.8 JRE (64-bit), update 45 or higher, is a prerequisite for Presto. If a suitable 64-bit version of Oracle Java 8 is already installed on the cluster, you can skip this step.
 
-The ``presto-admin`` tool simplifies installing Java 8 on all nodes in the Presto cluster. To install the Oracle Java 1.8 (64-bit) RPM for Linux using ``presto-admin``, first download `Oracle Java 8 <http://java.com/en/download/linux_manual.jsp>`_ and copy it to a location accessible by ``presto-admin``. Next, run the following command to install Java 8 on each node in the Presto cluster.
+The simplest way to install Java 8 on all nodes in the Presto cluster is to use ``presto-admin``. To install the Oracle Java 1.8 (64-bit) RPM for Linux using ``presto-admin``, first download `Oracle Java 8 <http://java.com/en/download/linux_manual.jsp>`_ and copy it to a location accessible by ``presto-admin``. Next, run the following command to install Java 8 on each node in the Presto cluster.
 ::
 
  $ sudo ./presto-admin package install <local_path_to_java_rpm>
 
+.. NOTE:: Using this method of installation will cause the default Java on your machine to be Java 8. If that is not desirable, you must download the tarball version of Java 8 and install it manually.
+
 .. NOTE:: The ``server-install-label`` will look for your Oracle Java 1.8 installation at locations where Java is installed normally using the binary or the RPM based installer. Otherwise, you need to have an environment variable called ``JAVA8_HOME`` set with your Java 1.8 install path. If ``JAVA8_HOME`` is not set or is pointing to an incompatible version of Java, the installer will look for the ``JAVA_HOME`` environment variable for a compatible version of Java. If neither of these environmental variables is set with a compatible version, and ``presto-admin`` fails to find Java 8 at any of the normal install locations, then ``server install`` will fail. After successfully running ``server install`` you can find the Java being used by Presto at ``/etc/presto/env.sh``.
 
 .. NOTE:: If installing Java on SLES, you may need to specify the ``--nodeps`` flag, so that the RPM is installed without checking or validating dependencies.

docs/installation/presto-admin-configuration.rst

@@ -26,7 +26,7 @@ file should be owned by root with R/W permissions (i.e. 622).
  "username": "<ssh_user_name>",
  "port": "<ssh_port>",
  "coordinator": "<host_name>",
- "workers": ["<host_name_1>", "<host_name_2>", ... "<host_name_n>"]
+ "workers": ["<host_name_1>", "<host_name_2>", ... "<host_name_n>"],
  "java8_home":"<path/to/java8/on/presto/nodes>"
  }
 
@@ -43,7 +43,7 @@ be used:
 
 Note that ``java8_home`` is not set by default.  It only needs to be set if
 Java 8 is in a non-standard location on the Presto nodes.  The property is used
-to tell the presto rpm where to find Java 8.
+to tell the Presto RPM where to find Java 8.
 
 You can also specify some but not all of the properties. For example, the
 default configuration is for a single-node installation of Presto on the same

docs/installation/presto-admin-installation.rst

@@ -9,9 +9,13 @@ Presto Admin Installation
 To install ``presto-admin``, first copy the  installer
 ``prestoadmin-1.2-offline.tar.bz2`` to the location where you want
 ``presto-admin`` to run. The recommended installation location is ``/opt``.
-Note that ``presto-admin`` does not have to be on same node(s) where Presto
-will run, though it does need to have SSH access to all of them. Next, extract
-and sudo run the installation script from within the ``prestoadmin`` directory.
+
+
+.. NOTE:: 
+    ``presto-admin`` does not have to be on the same node(s) where Presto will run,
+    though it does need to have SSH access to all of the nodes in the cluster.
+
+Next, extract and sudo run the installation script from within the ``prestoadmin`` directory.
 ::
 
  $ tar xvf prestoadmin-1.2-offline.tar.bz2

docs/installation/presto-cli-installation.rst

@@ -6,21 +6,20 @@ Running Presto Queries
 
 The Presto CLI provides a terminal-based interactive shell for running queries. The CLI is a self-executing JAR file, which means it acts like a normal UNIX executable.
 
-Download the `presto-cli` and copy it to the location you want to run it from. This location may be any node that has network access to the coordinator. Then rename it to presto and make it executable with chmod +x:
+Download the `presto-cli` and copy it to the location you want to run it from. This location may be any node that has network access to the coordinator. Then rename it to presto and make it executable with chmod +x, subsituting your version of Presto for "version":
 ::
 
- $ mv presto-cli-0.115-executable.jar presto
+ $ mv presto-cli-<version>-executable.jar presto
  $ chmod +x presto
 
 .. NOTE:: Presto must run with Java 8, so if Java 7 is the default on your cluster, you will need to explicitly specify the Java 8 executable. For example, ``<path_to_java_8_executable> -jar presto``. It may be helpful to add an alias for the Presto CLI: ``alias presto='<path_to_java_8_executable> -jar <path_to_presto>'``.
 
-By default, ``presto-admin`` installs the TPC-H connector for you, which generates TPC-H data on-the-fly.  Using this connector, issue the following commands to run your first Presto query:
+By default, ``presto-admin`` configures the TPC-H connector, which generates TPC-H data on-the-fly.  Using this connector, issue the following commands to run your first Presto query:
 ::
 
  $ ./presto --catalog tpch --schema tiny
  $ select count(*) from lineitem;
 
-For more on connectors, including how to connect to Hive, see :ref:`connector-add`.
 
 The above command assumes that you installed the Presto CLI on the coordinator, and that the Presto server is on port 8080. If either of these are not the case, then specify the server location in the command:
 ::

docs/installation/presto-configuration.rst

@@ -0,0 +1,47 @@
+
+==================
+Configuring Presto
+==================
+
+Presto has many configuration parameters that can be modified to
+tweak performance or add/remove features. While Presto should work decently well out-of-the-box,
+you still may need to make some changes.
+
+For example, it is often necessary to change the default memory configuration
+based on your cluster's capacity. The default max memory for each Presto server is 16GB, but in
+an environment with less than 16GB available per node, you will have to adjust the settings
+to be lower. Similarly, if you have a lot of memory (say, 120GB/node), you may want to allocate more
+memory to Presto for better performance.
+
+In the second case, in order to update the max memory value to 60GB per node, 
+change the line in ``/etc/opt/prestoadmin/coordinator/jvm.config`` and
+``/etc/opt/prestoadmin/workers/jvm.config`` that says ``-Xmx16G`` to ``-Xmx60G``.
+
+In addition, change the following lines in ``/etc/opt/prestoadmin/coordinator/config.properties``
+and ``/etc/opt/prestoadmin/workers/config.properties``: ::
+
+    query.max-memory-per-node=8GB
+    query.max-memory=50GB
+
+
+to ::
+
+    query.max-memory-per-node=30GB
+    query.max-memory=<30GB * number of nodes>
+
+
+We recommend setting ``query.max-memory-per-node`` to half of the JVM config max memory, though if your workload is highly concurrent, you may want
+to use a lower value for ``query.max-memory-per-node``.
+
+To deploy this configuration change to the cluster, run the following command: ::
+
+    sudo ./presto-admin configuration deploy
+
+
+Then, restart the Presto servers so that the changes get picked up: ::
+
+    sudo ./presto-admin server restart
+
+
+For detailed documentation on ``configuration deploy``, see :ref:`configuration-deploy-label`.
+For more configuration parameters, see the Presto documentation.

docs/installation/presto-connector-installation.rst

@@ -0,0 +1,36 @@
+
+==================
+Adding a Connector
+==================
+
+In Presto, connectors allow you to access different data sources -- e.g.,
+Hive, PostgreSQL, or MySQL.
+
+To add the Hive connector, create a file ``hive.properties`` in ``/etc/opt/prestoadmin/connectors``.
+
+For Cloudera CDH 5, it should have the following content: ::
+
+    connector.name=hive-cdh5
+    hive.metastore.uri=thrift://<metastore-host-or-ip>:<metastore-port>
+
+
+For Hadoop 2.0+ (including HDP), it should have the following content: ::
+
+   connector.name=hive-hadoop2
+   hive.metastore.uri=thrift://<metastore-host-or-ip>:<metastore-port>
+
+
+There are additional properties and possible configurations in the
+`Hive connector documentation <https://prestodb.io/docs/current/connector/hive.html>`_,
+for example if you have a HA Hadoop cluster.
+
+After adding a connector configuration file, :ref:distribute <reference to connector add> it to all of the nodes in the cluster: ::
+
+    sudo ./presto-admin connector add hive
+
+Once the new connector configuration has been distributed, :ref:restart <reference to server restart> Presto: ::
+
+    sudo ./presto-admin server restart
+
+
+For more on what connectors Presto supports, see the `Presto connector documentation <https://prestodb.io/docs/current/connector.html>`_.

docs/installation/presto-port-configuration.rst

@@ -4,7 +4,7 @@
 Presto Port Configuration
 =========================
 
-By default, Presto configuration uses 8080 for the HTTP port. If the port is already used on a given node on your cluster, that server will fail to start.
+By default, Presto uses 8080 for the HTTP port. If the port is already in use on any given node on your cluster, Presto will not start on that node(s).
 You can check if that port is already in use on a node by running the following on that node:
 ::
 
@@ -19,11 +19,5 @@ You can configure the server to use a different port by changing the following p
     http-server.http.port=<port>
     discovery.uri=http://<coordinator_ip_or_host>:<port>
 
-You can add these properties with the new ``port`` to the file ``config.properties`` under each of the directories ``/etc/opt/prestoadmin/coordinator``
-and ``/etc/opt/prestoadmin/workers`` locally, prior to running :ref:`server-install-label`. You may need to create these two directories. 
-If you have already installed Presto using :ref:`server-install-label` then you
-can reconfigure the cluster to use a new port by updating the ``config.properties`` at  ``/etc/opt/prestoadmin/coordinator``
-and ``/etc/opt/prestoadmin/workers`` and then running :ref:`configuration-deploy-label`.
-
-``presto-admin`` :ref:`server-start-label` and :ref:`server-restart-label` will check if the port configured for the server
-is already in use. If the port is in use on a node, then ``presto-admin`` will issue a warning and skip starting the server on that particular node.
+You can add these properties with the new ``port`` to ``/etc/opt/prestoadmin/coordinator/config.properties`` and
+``/etc/opt/prestoadmin/workers/config.properties``. Then, run :ref:`configuration-deploy-label`.

docs/installation/presto-server-installation.rst

@@ -11,7 +11,13 @@ First download the `presto-server-rpm-VERSION.ARCH.rpm` and copy it to a locatio
  $ sudo ./presto-admin server install <local_path_to_rpm>
 
 
-Presto! Presto is now installed on the coordinator and workers specified in your ``/etc/opt/prestoadmin/config.json`` file. Before you can issue your first query, you must start Presto:
+Presto! Presto is now installed on the coordinator and workers specified in your ``/etc/opt/prestoadmin/config.json`` file. 
+
+The default port for Presto is 8080.  If that port is already in use on your cluster, you will not be able to start Presto.
+In order to change the port that Presto uses, and if necessary check what ports are in use, proceed to :ref:`presto-port-configuration-label`.
+
+Now, you are ready to start Presto:
+
 ::
 
  $ sudo ./presto-admin server start

docs/presto-admin-commands.rst

@@ -249,7 +249,7 @@ once, you could run ::
     sudo ./presto-admin server restart
 
 Adding a Custom Connector
---------------------------
+-------------------------
 In order to install a custom connector not included with Presto, the jar must be
 added to the Presto plugin location using the ``plugin add_jar`` command before
 running the ``connector add`` command.

docs/quick-start-guide.rst

@@ -12,8 +12,9 @@ For a detailed explanation of all of the commands and their options, see :ref:`c
     installation/presto-admin-installation
     installation/presto-admin-configuration
     installation/java-installation
-    installation/presto-port-configuration
     installation/presto-server-installation
     installation/presto-cli-installation
+    installation/presto-connector-installation
+    installation/presto-configuration 
     installation/troubleshooting-installation
 

docs/user-guide.rst

@@ -11,6 +11,7 @@ A full explanation of the commands and features of ``presto-admin``.
 
     quick-start-guide
     installation/advanced-installation-options
+    installation/presto-port-configuration
     ssh-configuration
     presto-admin-commands
     presto-admin-cli-options