Merge pull request #689 from ESGF/readme_update

Readme update
ESGF · Dec 1, 2018 · b340672 · b340672
2 parents 0a5cb6d + af2e241
commit b340672
Show file tree

Hide file tree

Showing 8 changed files with 377 additions and 339 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # ESGF Installer
 The ESGF Installer is a command line tool for installing the ESGF Software Stack.  
-The software stack is comprised of: Tomcat, Thredds, CDAT & CDMS, PostgreSQL, MyProxy, and several ESGF.org custom software applications running on a LINUX (RedHat/CentOS) operating system.
+The software stack is comprised of: Tomcat, Thredds, CDAT & CDMS, PostgreSQL, MyProxy, and several ESGF custom software applications running on a LINUX (RedHat/CentOS) operating system.
 
 The custom ESGF software includes:
 - [ESGF-dashboard](https://github.com/ESGF/esgf-dashboard)
@@ -14,13 +14,43 @@ The custom ESGF software includes:
 - [ESGF-SLCS-server](https://github.com/ESGF/esgf-slcs-server)
 
 ## Installation
-- Clone this repo using ``git clone https://github.com/ESGF/esgf-installer.git``
-- Checkout the appropriate branch/tag. For example, the 3.0 alpha version can be accessed with the following command: ``git checkout tags/v3.0.0-alpha-release -b 3.0_alpha``.
-   This will checkout out the alpha release tag and create a new branch called 3.0_alpha
-- If Miniconda has not been installed, install Miniconda and other ESGF dependencies from yum and pip by running the ``esg_bootstrap.sh`` script
-- Activate the esgf-pub conda environment using ``source /usr/local/conda/bin/activate esgf-pub``
-- Run an installation by invoking the ``esg_node.py`` script.
-   Example: ``python esg_node.py --install --type data``
+The installation is performed on the Node itself.
+### Clone
+Clone this repo using 
+```
+git clone https://github.com/ESGF/esgf-installer.git && cd esgf-installer
+```
+### Checkout
+Checkout the appropriate branch/tag. For example, the 3.0 beta version can be accessed with the following command: 
+```
+git checkout tags/v3.0b1 -b 3.0_beta
+```
+This will checkout out the beta release tag and create a new branch called 3.0_beta.
+
+### Configure
+Note that, to avoid being prompted for various parameters, the `esgf.properties.template` should be populated with the proper values for your node.
+
+See [the properties file documentation](https://esgf.github.io/esgf-installer/autoinstall_usage.html) for information when populating.
+
+### Bootstrap and Activate
+Install Miniconda and other ESGF dependencies from yum and pip by running the bootstrap script:
+```
+./esg_bootstrap.sh
+```
+If you are migrating to ESGF 3.0 from a previous version of ESGF, add the migrate parameter to the the bootstrap
+```
+./esg_bootstrap.sh migrate
+```
+Activate the esgf-pub conda environment
+```
+source /usr/local/conda/bin/activate esgf-pub
+```
+
+### Install
+Run an installation by invoking the `esg_node.py` script. For example, a data-only node installation:
+```
+python esg_node.py --install --type data
+```
 
 
 More detailed installation instructions can be found on the [wiki](https://github.com/ESGF/esgf-installer/wiki)

diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css
@@ -0,0 +1,9 @@
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: normal;
+}
+
+.wy-table-responsive {
+    margin-bottom: 24px;
+    max-width: 100%;
+    overflow: visible;
+}
diff --git a/docs/autoinstall_usage.rst b/docs/autoinstall_usage.rst
@@ -1,48 +1,224 @@
-The autoinstaller file, esgf.properties, can be used to configure options pre-installation so that the install script will run with no further user input. Below are descriptions of the configuration options.  If an option is left blank, the user will be prompted for input for that option unless otherwise denoted.
-
 Autoinstaller Configuration Options
 ******************************************
-==================================================  =====
-
-==================================================  =====
-esg.root.url                                        - The URL of the distribution mirror that will be used to fetch ESGF resources
-esgf.host.ip                                        - The IP address of the node
-esgf.host                                           - The fully qualified domain name (fqdn) of your server
-node.short.name                                     - Used to set the the Endpoint name in the Globus configuration (see: https://github.com/globus/globus-connect-server/blob/master/source/globus-connect-server.conf)
-node.long.name                                      - More descriptive name of ESGF node (DEPRECATED)
-node.namespace                                      - Set to your reverse fqdn - Ex: gov.llnl (DEPRECATED)
-node.peer.group <esgf-test | esgf-dev | esgf-prod>  - Determines the node's peer group, i.e which federation the node will belong to
-esgf.index.peer                                     - Hostname of the index peer you wish to publish to
-mail.admin.address                                  - Email address that will receive notifications from the ESGF server
-publisher.db.user                                   - Name that will be created as a low privilege user account in Postgres for the ESGF Publisher
-esg.org.name                                        - Organization name that is used as the root ID when running the esgsetup binary. Usually the name of the institution where the node is location (llnl, ipsl, etc.)
-update.java <y | yes | n | no>                      - Determines whether to update Java if previous Java installation is found
-update.ant <y | yes | n | no>                       - Determines whether to update Ant if previous Ant installation is found
-backup.database <y | yes | n | no>                  - Determines whether to create a backup dump of the database if an existing Postgres installation is found
-update.postgres <y | yes | n | no>                  - Determines whether to update Postgres if previous Postgres installation is found
-update.apache <y | yes | n | no>                    - Determines whether to update Apache if previous Apache installation is found
-update.tomcat <y | yes | n | no>                    - Determines whether to update Tomcat if previous Tomcat installation is found
-update.orp <y | yes | n | no>                       - Determines whether to update ORP if previous ORP webapp installation is found
-update.node.manager <y | yes | n | no>              - Determines whether to update Node Manager if previous Node Manager webapp installation is found
-update.thredds <y | yes | n | no>                   - Determines whether to update Thredds if previous Thredds webapp installation is found
-update.dashboard <y | yes | n | no>                 - Determines whether to update Dashboard if previous Dashboard installation is found
-update.publisher <y | yes | n | no>                 - Determines whether to update Publisher if previous Publisher installation is found
-gridftp-config [defaults to:bdm end-user]           - Seems to be nonfunctional (DEPRECATED)
-tomcat.user                                         - Name of tomcat user to be used with Thredds. Defaults to dnode_user if not populated
-add.another.user <y | yes | n | no>                 - Determines whether to update ORP if previous ORP webapp installation is found
-update.esg.search <y | yes | n | no>                - Determines whether to update ESG Search if previous ESG Search webapp installation is found
-update.cog <y | yes | n | no>                       - Determines whether to update CoG if previous CoG installation is found
-update.solr <y | yes | n | no>                      - Determines whether to update Solr if previous Solr installation is found
-backup.idp <y | yes | n | no>                       - Determines whether to update IDP if previous IDP webapp installation is found
-register.myproxy <y | yes | n | no>                 - Determines if the MyProxy server will be registered with Globus
-update.globus <y | yes | n | no>                    - Determines whether to update Globus if previous Globus installation is found
-globus.user                                         - Your Globus Username
-globus.password                                     - Your Globus Password
-myproxy.endpoint                                    - Specifies the hostname of the myproxy-server
-register.gridftp <y | yes | n | no>                 - Determines if the GridFTP server will be registered with Globus
-update.slcs <y | yes | n | no>                      - Determines whether to update SLCS if previous SLCS server installation is found
-install.signed.certs <y | yes | n | no>             - Determines whether to install a commercially signed SSL certificate
-commercial.key.path                                 - Absolute path to commercial key
-commercial.cert.path                                - Absolute path to commercially signed cert
-cachain.path                                        - A comma separated list of the absolute paths that make up the cachain
-==================================================  =====
+
+The autoinstaller file, esgf.properties, can be used to configure options so that the install script will run with no further user input. Below are descriptions of the configuration options.  If an option is left blank, the user will be prompted for input for that option unless otherwise denoted.
+Note that the file that the installer references for these properties is located at `/esg/config/esgf.properties` so make edits there after the initial population of the `esgf.properties.template`.
+
+===============
+Core Parameters
+===============
+
+.. topic:: esg.root.url
+
+    The URL of the distribution mirror that will be used to fetch ESGF resources
+
+.. topic:: esgf.host.ip 
+
+    The IP address of the node
+
+.. topic:: esgf.host
+
+    The fully qualified domain name (fqdn) of your server
+
+.. topic:: node.short.name
+
+    Used to set the the Endpoint name in the Globus configuration (see: https://github.com/globus/globus-connect-server/blob/master/source/globus-connect-server.conf)
+
+.. topic:: node.long.name
+
+    More descriptive name of ESGF node (DEPRECATED)
+
+.. topic:: node.namespace
+
+    Set to your reverse fqdn Ex: gov.llnl (DEPRECATED)
+
+.. topic:: node.peer.group
+
+    <esgf-test | esgf-dev | esgf-prod>
+
+    Determines the node's peer group, i.e which federation the node will belong to
+
+.. topic:: esgf.index.peer
+
+    Hostname of the index peer you wish to publish to
+
+.. topic:: esgf.idp.peer
+
+    Hostname of the IDP peer you wish to authenicate with
+
+.. topic:: mail.admin.address
+
+    Email address that will receive notifications from the ESGF server
+
+.. topic:: publisher.db.user
+
+    Name that will be created as a low privilege user account in Postgres for the ESGF Publisher
+
+.. topic:: esg.org.name
+
+    Organization name that is used as the root ID when running the esgsetup binary. Usually the name of the institution where the node is location (llnl, ipsl, etc.)
+
+.. topic:: register.gridftp
+
+    <y | yes | n | no>
+
+    Determines if the GridFTP server will be registered with Globus
+
+.. topic:: register.myproxy
+
+    <y | yes | n | no>
+
+    Determines if the MyProxy server will be registered with Globus
+
+.. topic:: globus.user
+
+    Your Globus Username
+
+.. topic:: globus.password
+
+    Your Globus Password
+
+.. topic:: publisher.db.user
+
+    Name that will be created as a low privilege user account in Postgres for the ESGF Publisher
+
+============
+Certificates
+============
+
+.. topic:: install.signed.certs
+
+    <y | yes | n | no>
+
+    Determines whether to install a commercially signed SSL certificate
+
+.. topic:: commercial.key.path
+
+    Absolute path to commercial key
+
+.. topic:: commercial.cert.path
+
+    Absolute path to commercially signed cert
+
+.. topic:: cachain.path
+
+    A comma separated list of the absolute paths that make up the cachain
+
+
+==========
+Update
+==========
+
+.. topic:: update.java
+
+    <y | yes | n | no> 
+
+    Determines whether to update Java if previous Java installation is found
+
+.. topic:: update.ant
+
+    <y | yes | n | no> 
+
+    Determines whether to update Ant if previous Ant installation is found
+
+.. topic:: backup.database
+
+    <y | yes | n | no> 
+
+    Determines whether to create a backup dump of the database if an existing Postgres installation is found
+
+.. topic:: update.postgres
+
+    <y | yes | n | no> 
+
+    Determines whether to update Postgres if previous Postgres installation is found
+
+.. topic:: update.apache
+
+    <y | yes | n | no> 
+
+    Determines whether to update Apache if previous Apache installation is found
+
+.. topic:: update.tomcat
+
+    <y | yes | n | no> 
+
+    Determines whether to update Tomcat if previous Tomcat installation is found
+
+.. topic:: update.orp
+
+    <y | yes | n | no> 
+
+    Determines whether to update ORP if previous ORP webapp installation is found
+
+.. topic:: update.node.manager
+
+    <y | yes | n | no> 
+
+    Determines whether to update Node Manager if previous Node Manager webapp installation is found
+
+.. topic:: update.thredds
+
+    <y | yes | n | no> 
+
+    Determines whether to update Thredds if previous Thredds webapp installation is found
+
+.. topic:: update.dashboard
+
+    <y | yes | n | no> 
+
+    Determines whether to update Dashboard if previous Dashboard installation is found
+
+.. topic:: update.publisher
+
+    <y | yes | n | no> 
+
+    Determines whether to update Publisher if previous Publisher installation is found
+
+.. topic:: update.esg.search
+
+    <y | yes | n | no> 
+
+    Determines whether to update ESG Search if previous ESG Search webapp installation is found
+
+.. topic:: update.cog
+
+    <y | yes | n | no> 
+
+    Determines whether to update CoG if previous CoG installation is found
+
+.. topic:: update.solr
+
+    <y | yes | n | no> 
+
+    Determines whether to update Solr if previous Solr installation is found
+
+.. topic:: backup.idp
+
+    <y | yes | n | no> 
+
+    Determines whether to update IDP if previous IDP webapp installation is found
+
+.. topic:: update.globus
+
+    <y | yes | n | no> 
+
+    Determines whether to update Globus if previous Globus installation is found
+
+.. topic:: update.slcs
+
+    <y | yes | n | no> 
+
+    Determines whether to update SLCS if previous SLCS server installation is found
+
+=======================
+Advanced User Settings
+=======================
+
+.. topic:: tomcat.user
+
+    Name of tomcat user to be used with Thredds. Defaults to dnode_user if not populated
+
+.. topic:: myproxy.endpoint
+
+    Specifies the hostname of the myproxy-server
diff --git a/docs/conf.py b/docs/conf.py
@@ -43,7 +43,8 @@
     'sphinx.ext.coverage',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
-    'sphinx.ext.githubpages']
+    'sphinx.ext.githubpages',
+    'sphinxarg.ext']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -67,9 +68,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'3.0.0-alpha'
+version = u'3.0b1'
 # The full version, including alpha/beta/rc tags.
-release = u'alpha'
+release = u'beta'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -109,6 +110,11 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+html_context = {
+    'css_files': [
+        '_static/theme_overrides.css',  # overrides for wide tables in RTD theme
+        ],
+    }
 
 # -- Options for HTMLHelp output ------------------------------------------