Fix #20, updated deployment guide documentation. (#21)

Author: giuseppe-carboni

developer/howto/installing/dependencies.rst

@@ -4,16 +4,28 @@
 Dependencies
 ************
 
-To automatically deploy DISCOS, you need to install four dependencies:
+To automatically deploy DISCOS, you need to install some dependencies:
+`Python 2.7 <https://www.python.org/download/releases/2.7/>`_,
 `Git <https://git-scm.com/>`_, `Ansible <https://www.ansible.com/>`_,
 `Vagrant <https://www.vagrantup.com/>`_ and `VirtualBox
 <https://www.virtualbox.org/>`_.  It usually takes about 15 minutes.
 
 
-.. note:: If you are accustomed to python virtual environments
-   (like `pyenv` or similar), you can install the required pip packages
-   mentioned in the procedure below in your preferred environment,
-   without the need of administrator permissions.
+Install Python 2.7
+==================
+Verify if Python 2.7 is already installed on your system:
+
+.. code-block:: shell
+
+   $ python --version
+   Python 2.7.15rc1
+
+If your system comes bundled with a different Python version, you may want to
+consider installing a Python 2.7 environment such as
+`Anaconda <https://www.anaconda.com/download/#linux>`_,
+`Miniconda <https://conda.io/miniconda.html>`_ or
+`Pyenv <https://github.com/pyenv/pyenv>`_ and its
+`Virtualenv <https://github.com/pyenv/pyenv-virtualenv>`_ plugin.
 
 
 Install Git
@@ -23,20 +35,21 @@ Before installing Git, verify if it is already installed:
 .. code-block:: shell
 
    $ git --version
-   git version 1.9.1
+   git version 2.17.1
 
 You do not need a particular version of Git, but if the command ``git --version``
 fails, than you have to install Git by following the instructions at the `official Git
 website <https://git-scm.com/book/en/v1/Getting-Started-Installing-Git>`_.
 
+
 Install Ansible
 ===============
 Verify if Ansible is already installed:
 
 .. code-block:: shell
 
    ansible --version
-   ansible 2.6.3
+   ansible 2.7.2
 
 If the command ``ansible --version`` fails, than you have to install Ansible.
 
@@ -46,16 +59,19 @@ The suggested way to do this is via `pip`:
 
     $ sudo pip install ansible
 
-In case the last command fails, or if you want to install Ansible in a different way,
-check out the `official ansible website
+.. note:: If you are using a Python virtual environment, you do not need
+   administration permissions to install Ansible.
+
+In case the command fails, or if you want to install Ansible in a different
+way, check out the `official ansible website
 <http://docs.ansible.com/ansible/intro_installation.html#installation>`_.
 
 
 Install VirtualBox and Vagrant
 ==============================
 You need to install VirtualBox and Vagrant only if you want to
-deploy DISCOS on VMs, as in the case of a development environment.
-As a first step, check if VirtualBox is already installed:
+deploy DISCOS on virtual machines, as in the case of a development
+environment. As a first step, check if VirtualBox is already installed:
 
 .. code-block:: shell
 
@@ -65,12 +81,20 @@ As a first step, check if VirtualBox is already installed:
 In case it is not, download the binary file from the
 `official website <https://www.virtualbox.org/wiki/Downloads>`_
 and install it.
-Now verify if Vagrant is already installed:
+
+
+.. note:: The suggested VirtualBox version to install is the 5.1. As of today,
+   the latest release of VirtualBox, version 5.2, seems to introduce some lag
+   in SSH sessions to the deployed virtual machines. Version 5.1 also matches
+   the VirtualBox guest additions already installed in the virtual machines.
+
+
+Now verify if Vagrant is installed:
 
 .. code-block:: shell
 
    $ vagrant --version
-   Vagrant 1.8.6
+   Vagrant 2.2.1
 
 If it is not, download the binary file from
 the `vagrant official website <https://www.vagrantup.com/downloads.html>`_

developer/howto/installing/development.rst

@@ -4,31 +4,73 @@
 Development
 ***********
 
-In the :ref:`deploy_quickstart` section we have seen how
-to deploy a ``manager`` virtual machine.  You can also deploy
-the whole system.  For instance, to deploy a development system
-composed of three virtual machines (``manager``, ``as`` and ``ms``),
-pass ``discos:development`` to the ``discos-deploy`` script:
+Machines deployment
+===================
+In the :ref:`deploy_quickstart` section we have seen how to deploy a
+``manager`` virtual machine. You can also deploy the whole control system.
+For instance, to deploy a development system composed of three virtual machines
+(``manager``, ``console`` and ``storage``), pass the ``discos`` *cluster*,
+followed by the ``development`` system, to the ``discos-deploy`` script:
 
 .. code-block:: shell
 
   $ discos-deploy discos:development
 
-This command will connect via SSH to all development machines
-and provision the whole system (create users, configure networking,
-install yum packages, ACS and its dependencies, utilities, and
-eventually the DISCOS dependencies).  To get a particular
-DISCOS branch you have two options: you can manually execute
-the ``discos-get`` command, as we did in the :ref:`deploy_quickstart`
-section, or you can do it by passing the ``--deploy`` argument,
-followed by the branch you want to deploy, and, in the case of
-development environment, the ``--station`` argument, followed
-by the name of the station, to the ``discos-deploy`` script.
+This command will connect via SSH to all development machines and provision the
+whole system (create users, configure networking, install yum packages,
+configure NIS, Lustre, ACS and its dependencies, install some utilities, and
+finally the DISCOS dependencies).
+
+
+Working without Vagrant
+-----------------------
+If you wish to deploy a development environment on physical machines, or you
+simply want to install the virtual machines by yourself using VirtualBox or
+another virtual machine provider, you can still use the ``discos-deploy``
+script to perform the automatic deployment procedure. You first have to setup
+the machines' network interfaces, in order to enable Ansible access to them via
+the correct IP address, and then start the deployment procedure by passing the
+``--no-vagrant``, ``-n`` flag to the ``discos-deploy`` script:
+
+.. code-block:: shell
+
+   $ discos-deploy discos:development --no-vagrant
+
+This will let the script know that you do not want to create any (other)
+virtual machine on your system, and that you want to apply the whole
+configuration onto an existing, physical or virtual, set of machines.
+
+
+DISCOS setup
+============
+
+Manual setup
+------------
+To download the DISCOS control software, you can use the ``discos-get`` command,
+covered in the :ref:`get_a_discos_branch` section.
+
+.. figure:: images/discos-get.png
+   :figwidth: 100%
+   :align: center
+
+Once the download of the repository is completed, you have to perform the setup
+procedure like we have seen in the :ref:`install_discos` section.
+
+.. figure:: images/make.png
+
+Automatic setup
+---------------
+You can let the deployment procedure perform the DISCOS control system setup
+for you by specifying the ``--branch`` argument to the ``discos-deploy``
+script, followed by the branch name you want to deploy and install. Since the
+procedure will internally call the ``discos-get`` script for you, if you are
+deploying in a development environment, you also have to provide to the script
+the ``--station`` argument, followed by the name of the desired station.
 
 .. code-block:: shell
 
-  $ discos-deploy discos:development --deploy latest64 --station noto
+  $ discos-deploy discos:development --tag discos1.0-rc02 --station noto
 
 You can choose a station among ``medicina``, ``noto`` and ``srt``.
-This command executes the ``discos-get latest64 -s noto`` command on
-all machines of the system, in parallel.
+The ``discos-get`` command gets executed on all machines of the system at the
+same time.