FAB-4246 separate out prereqs

christo4ferris · christo4ferris · commit c01fa7cda3c0 · 2017-06-01T16:09:35.000-04:00
create a separate doc page for prereqs and link from
other parts of the doc.

add CCBY 4.0 to changed files

address gari's comment
address inconsistent comment about go version

Change-Id: I7b044b5d29250d905fba1243a0719ba32e3dc6e6
Signed-off-by: Christopher Ferris &lt;chrisfer@us.ibm.com&gt;
diff --git a/docs/source/CONTRIBUTING.rst b/docs/source/CONTRIBUTING.rst
@@ -8,6 +8,14 @@ First things first, please review the Hyperledger Project's `Code of
 Conduct <https://wiki.hyperledger.org/community/hyperledger-project-code-of-conduct>`__
 before participating. It is important that we keep things civil.
 
+Install prerequisites
+---------------------
+
+Before we begin, if you haven't already done so, you may wish to check that
+you have all the :doc:`prerequisites <prereqs>` installed on the platform(s)
+on which you'll be developing blockchain applications and/or operating
+Hyperledger Fabric.
+
 Getting a Linux Foundation account
 ----------------------------------
 
diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html
@@ -4,4 +4,8 @@
 <br>
 <a href="https://chat.hyperledger.org">Rocket Chat</a>  <a href="https://jenkins.hyperledger.org/">CI</a>
 <a href="http://stackoverflow.com/questions/tagged/hyperledger-fabric">StackOverflow</a>
+<br>
+<a rel="license" href="http://creativecommons.org/licenses/by/4.0/">
+  <img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a>
+  <br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.
 {% endblock %}
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -1,51 +1,35 @@
 Getting Started
 ===============
 
-.. note:: These instructions have been verified to work against the version "1.0.0-alpha2" tagged docker
-          images and the pre-compiled setup utilities within the supplied tarball file.
-          If you run these commands with images or tools from the current master
-          branch, it is possible that you will see configuration and panic errors.
+.. note:: These instructions have been verified to work against the
+          version "1.0.0-alpha2" tagged docker images and the pre-compiled
+          setup utilities within the supplied tarball file. If you run
+          these commands with images or tools from the current master
+          branch, it is possible that you will see configuration and panic
+          errors.
 
 The getting started scenario provisions a sample Fabric network consisting of
-two organizations, each maintaining two peers, and a "solo" ordering service.
+two organizations, each maintaining two peer nodes, and a "solo" ordering
+service.
 
-Prior to launching the network, we will demonstrate the usage of two fundamental tools
-which are necessary to create a functioning transactional network with digital
-signature validation and access control:
+Install prerequisites
+---------------------
 
-- cryptogen - generates the x509 certificates AND keys used to identify and
-  authenticate the various components in the network.
-- `configtxgen <https://github.com/hyperledger/fabric/blob/master/docs/source/configtxgen.rst>`__ -
-  generates the requisite configuration artifacts for orderer bootstrap and
-  channel creation.
-
-Each tool consumes a configuration yaml file, within which we specify the topology
-of our network (cryptogen) and the location of our certificates for various
-configuration operations (configtxgen).  Once the tools have been successfully run,
-we are able to launch our network.  More detail on the tools and the structure of
-the network will be provided later in this document.  For now, let's get going...
-
-Prerequisites and setup
------------------------
-
-- `Docker <https://www.docker.com/products/overview>`__ - v1.12 or higher
-- `Docker Compose <https://docs.docker.com/compose/overview/>`__ - v1.8 or higher
-- `Docker Toolbox <https://docs.docker.com/toolbox/toolbox_install_windows/>`__ - Windows users only
-- `Go <https://golang.org/>`__ - 1.7 or higher
-
-On Windows machines you will also need the following which provides a better alternative to the Windows command prompt:
-
-- `Git Bash <https://git-scm.com/downloads>`__
-- `make for MinGW <http://sourceforge.net/projects/mingw/files/MinGW/Extension/make/make-3.82.90-cvs/make-3.82.90-2-mingw32-cvs-20120902-bin.tar.lzma>`__ to be added to Git Bash
+Before we begin, if you haven't already done so, you may wish to check that
+you have all the :doc:`prereqs` installed on the platform(s)
+on which you'll be developing blockchain applications and/or operating
+Hyperledger Fabric.
 
 Download the artifacts and binaries & pull the docker images
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. note:: If you are running on Windows you will want to make use of your Git
-          Bash shell for the upcoming terminal commands.
+.. note:: If you are running on Windows you will want to make use of the ``Git
+          Bash shell`` extension for the upcoming terminal commands. Visit the
+          :doc:`prereqs` if you haven't previously installed
+          it.
 
-- Download the `cURL <https://curl.haxx.se/download.html>`__ tool if not already installed.
-- Determine a location on your machine where you want to place the artifacts and binaries.
+Determine a location on your machine where you want to place the artifacts
+and binaries.
 
 .. code:: bash
 
@@ -63,7 +47,7 @@ extract all of the necessary artifacts to set up your network and place them
 into a folder named ``release``.
 
 It also retrieves the two platform-specific binaries - ``cryptogen`` and
-``configtxgen`` - which are briefly described above. Finally, the script will
+``configtxgen`` - which we'll use later. Finally, the script will
 download the Hyperledger Fabric docker images into your local Docker registry.
 
 The script lists out the docker images upon conclusion.  You should see the
@@ -112,9 +96,10 @@ and requirements to build a fully-functional Fabric.
 Crypto Generator
 ----------------
 
-We will use the cryptogen tool to generate the cryptographic material (x509 certs)
-for our various network entities.  The certificates are based on a standard PKI
-implementation where validation is achieved by reaching a common trust anchor.
+We will use the ``cryptogen`` tool to generate the cryptographic material
+(x509 certs) for our various network entities.  The certificates are based on
+a standard PKI implementation where validation is achieved by reaching a
+common trust anchor.
 
 How does it work?
 ^^^^^^^^^^^^^^^^^
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -34,6 +34,7 @@ Before diving in, watch how Fabric is `Building a Blockchain for Business
    :maxdepth: 2
    :caption: Getting Started
 
+   prereqs
    getting_started
 
 .. toctree::
diff --git a/docs/source/prereqs.rst b/docs/source/prereqs.rst
@@ -0,0 +1,80 @@
+Prerequisites
+=============
+
+Install cURL
+------------
+
+Download the `cURL <https://curl.haxx.se/download.html>`__ tool if not
+already installed.
+
+Docker and Docker Compose
+-------------------------
+
+You will need the following installed on the platform on which you will be
+operating, or developing on (or for), Hyperledger Fabric:
+
+  - MacOSX, *nix, or Windows 10: `Docker <https://www.docker.com/products/overview>`__
+    v1.12 or greater is required.
+  - Older versions of Windows: `Docker
+    Toolbox <https://docs.docker.com/toolbox/toolbox_install_windows/>`__ -
+    again, Docker version v1.12 or greater is required.
+
+You can check the version of Docker you have installed with the following
+command from a terminal prompt:
+
+.. code:: bash
+
+  docker --version
+
+.. note:: Installing Docker for Mac or Windows, or Docker Toolbox will also
+          install Docker Compose. If you already had Docker installed, you
+          should check that you have Docker Compose version 1.8 or greater
+          installed. If not, we recommend that you install a more recent
+          version of Docker.
+
+You can check the version of Docker Compose you have installed with the
+following command from a terminal prompt:
+
+.. code:: bash
+
+  docker-compose --version
+
+Go Programming Language
+-----------------------
+
+Hyperledger Fabric uses the Go programming language 1.7.x for many of its
+components.
+
+.. note: Go version 1.8.x will yield test failures
+
+  - `Go <https://golang.org/>`__ - version 1.7.x
+
+Node.js Runtime and NPM
+-----------------------
+
+If you will be developing applications for Hyperledger Fabric leveraging the
+Fabric SDK for Node.js, you will need to have version 6.9.x of Node.js
+installed.
+
+.. note:: Node.js version 7.x is not supported at this time.
+
+  - `Node.js <https://nodejs.org/en/download/>`__ - version 6.9.x or greater
+
+.. note:: Installing Node.js will also install NPM, however it is recommended
+          that you update the default version of NPM installed. You can upgrade
+          the ``npm`` tool with the following command:
+
+.. code:: bash
+
+  npm install npm@latest -g
+
+Windows extras
+--------------
+
+If you are developng on Windows, you may also need the following which
+provides a better alternative to the built-in Windows tools:
+
+  - `Git Bash <https://git-scm.com/downloads>`__
+  - `make for MinGW <http://sourceforge.net/projects/mingw/files/MinGW/Extension/make/make-3.82.90-cvs/make-3.82.90-2-mingw32-cvs-20120902-bin.tar.lzma>`__ to be added to Git Bash
+
+.. Licensed under Creative Commons Attribution 4.0 International License
