Add support for ONAP documentation project

Provided the mandatory doc structure:
  docs/
    index.rst
    ...

Added a couple of .gitignore for better testing and development.

Change-Id: I722806681e4844e0ea915006bc7de6018d3073d7
Issue-ID: OOM-1672
Signed-off-by: Petr Ospalý <p.ospaly@partner.samsung.com>

4 files changed, 786 insertions, 0 deletions

diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 00000000..19fe1aa0
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,2 @@
+conf.py*
+_static
diff --git a/docs/BuildGuide.rst b/docs/BuildGuide.rst
new file mode 100644
index 00000000..4cf8d97c
--- /dev/null
+++ b/docs/BuildGuide.rst
@@ -0,0 +1,352 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2019 Samsung Electronics Co., Ltd.
+
+OOM ONAP Offline Installer Package Build Guide
+=============================================================
+
+This document is describing procedure for building offline installer packages. It is supposed to be triggered on server with internet connectivity and will download all artifacts required for ONAP deployment based on our static lists. The server used for the procedure in this guide is preferred to be separate build server.
+
+Procedure was completely tested on RHEL 7.4 as it’s tested target platform, however with small adaptations it should be applicable also for other platforms.
+
+Part 1. Preparations
+--------------------
+
+We assume that procedure is executed on RHEL 7.4 server with \~300G disc space, 16G+ RAM and internet connectivity
+
+More-over following sw packages has to be installed:
+
+* for the Preparation (Part 1), the Download artifacts for offline installer (Part 2) and the application helm charts preparation and patching (Part 4)
+    -  git
+    -  wget
+
+* for the Download artifacts for offline installer (Part 2) only
+    -  createrepo
+    -  dpkg-dev
+    -  python2-pip
+
+* for the Download artifacts for offline installer (Part 2) and the Populate local nexus (Part 3)
+    -  nodejs
+    -  jq
+    -  docker (exact version docker-ce-17.03.2)
+
+* for the Download artifacts for offline installer (Part 2) and for the Application helm charts preparation and patching (Part 4)
+    -  patch
+
+* for the Populate local nexus (Part 3)
+    -  twine
+
+This can be achieved by following commands:
+
+::
+
+    # Register server
+    subscription-manager register --username <rhel licence name> --password <password> --auto-attach
+
+    # enable epel for npm and jq
+    rpm -ivh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
+
+    # enable rhel-7-server-e4s-optional-rpms in /etc/yum.repos.d/redhat.repo
+
+    # install following packages
+    yum install -y expect nodejs git wget createrepo python2-pip jq patch
+
+    pip install twine
+
+    # install docker
+    curl https://releases.rancher.com/install-docker/17.03.sh | sh
+
+Then it is necessary to clone all installer and build related repositories and prepare the directory structure.
+
+::
+
+    # prepare the onap build directory structure
+    cd /tmp
+    git clone -b casablanca https://gerrit.onap.org/r/oom/offline-installer
+    cd onap-offline
+
+Part 2. Download artifacts for offline installer
+------------------------------------------------
+
+**Note: Skip this step if you have already all necessary resources and continue with Part 3. Populate local nexus**
+
+All artifacts should be downloaded by running the download script as follows:
+
+./build/download_offline_data_by_lists.sh <project>
+
+For example:
+
+``$ ./build/download_offline_data_by_lists.sh onap_3.0.0``
+
+Download is as reliable as network connectivity to internet, it is highly recommended to run it in screen and save log file from this script execution for checking if all artifacts were successfully collected. Each start and end of script call should contain timestamp in console output. Downloading consists of 10 steps, which should be checked at the end one-by-one.
+
+**Verify:** *Please take a look on following comments to respective
+parts of download script*
+
+[Step 1/10 Download collected docker images]
+
+=> image download step is quite reliable and contain retry logic
+
+E.g
+
+::
+
+    == pkg #143 of 163 ==
+    rancher/etc-host-updater:v0.0.3
+    digest:sha256:bc156a5ae480d6d6d536aa454a9cc2a88385988617a388808b271e06dc309ce8
+    Error response from daemon: Get https://registry-1.docker.io/v2/rancher/etc-host-updater/manifests/v0.0.3: Get
+    https://auth.docker.io/token?scope=repository%3Arancher%2Fetc-host-updater%3Apull&service=registry.docker.io: net/http: TLS handshake timeout
+    WARNING [!]: warning Command docker -l error pull rancher/etc-host-updater:v0.0.3 failed.
+    Attempt: 2/5
+    INFO: info waiting 10s for another try...
+    v0.0.3: Pulling from rancher/etc-host-updater
+    b3e1c725a85f: Already exists
+    6a710864a9fc: Already exists
+    d0ac3b234321: Already exists
+    87f567b5cf58: Already exists
+    16914729cfd3: Already exists
+    83c2da5790af: Pulling fs layer
+    83c2da5790af: Verifying Checksum
+    83c2da5790af: Download complete
+    83c2da5790af: Pull complete
+
+[Step 2/10 Build own nginx image]
+
+=> there is no hardening in this step, if it failed needs to be
+retriggered. It should end with **Successfully built <id>**
+
+[Step 3/10 Save docker images from docker cache to tarfiles]
+
+=> quite reliable, retry logic in place
+
+[Step 4/10 move infra related images to infra folder]
+
+=> should be safe, precondition is not failing step(3)
+
+[Step 5/10 Download git repos]
+
+=> potentially unsafe, no hardening in place. If it not download all git repos. It has to be executed again. Easiest way is probably to comment-out other steps in load script and run it again.
+
+E.g.
+
+::
+
+    Cloning into bare repository
+    'github.com/rancher/community-catalog.git'...
+    error: RPC failed; result=28, HTTP code = 0
+    fatal: The remote end hung up unexpectedly
+    Cloning into bare repository 'git.rancher.io/rancher-catalog.git'...
+    Cloning into bare repository
+    'gerrit.onap.org/r/testsuite/properties.git'...
+    Cloning into bare repository 'gerrit.onap.org/r/portal.git'...
+    Cloning into bare repository 'gerrit.onap.org/r/aaf/authz.git'...
+    Cloning into bare repository 'gerrit.onap.org/r/demo.git'...
+    Cloning into bare repository
+    'gerrit.onap.org/r/dmaap/messagerouter/messageservice.git'...
+    Cloning into bare repository 'gerrit.onap.org/r/so/docker-config.git'...
+
+[Step 6/10 Download http files]
+
+[Step 7/10 Download npm pkgs]
+
+[Step 8/10 Download bin tools]
+
+=> work quite reliably, If it not download all artifacts. Easiest way is probably to comment-out other steps in load script and run it again.
+
+[Step 9/10 Download rhel pkgs]
+
+=> this is the step which will work on rhel only, for other platform different packages has to be downloaded.
+
+Following is considered as sucessfull run of this part:
+
+::
+
+      Available: 1:net-snmp-devel-5.7.2-32.el7.i686 (rhel-7-server-rpms)
+        net-snmp-devel = 1:5.7.2-32.el7
+      Available: 1:net-snmp-devel-5.7.2-33.el7_5.2.i686 (rhel-7-server-rpms)
+        net-snmp-devel = 1:5.7.2-33.el7_5.2
+    Dependency resolution failed, some packages will not be downloaded.
+    No Presto metadata available for rhel-7-server-rpms
+    https://ftp.icm.edu.pl/pub/Linux/fedora/linux/epel/7/x86_64/Packages/p/perl-CDB_File-0.98-9.el7.x86_64.rpm:
+    [Errno 12\] Timeout on
+    https://ftp.icm.edu.pl/pub/Linux/fedora/linux/epel/7/x86_64/Packages/p/perl-CDB_File-0.98-9.el7.x86_64.rpm:
+    (28, 'Operation timed out after 30001 milliseconds with 0 out of 0 bytes
+    received')
+    Trying other mirror.
+    Spawning worker 0 with 230 pkgs
+    Spawning worker 1 with 230 pkgs
+    Spawning worker 2 with 230 pkgs
+    Spawning worker 3 with 230 pkgs
+    Spawning worker 4 with 229 pkgs
+    Spawning worker 5 with 229 pkgs
+    Spawning worker 6 with 229 pkgs
+    Spawning worker 7 with 229 pkgs
+    Workers Finished
+    Saving Primary metadata
+    Saving file lists metadata
+    Saving other metadata
+    Generating sqlite DBs
+    Sqlite DBs complete
+
+[Step 10/10 Download sdnc-ansible-server packages]
+
+=> there is again no retry logic in this part, it is collecting packages for sdnc-ansible-server in the exactly same way how that container is doing it, however there is a bug in upstream that image in place will not work with those packages as old ones are not available and newer are not compatible with other stuff inside that image
+
+Part 3. Populate local nexus
+----------------------------
+
+Prerequisites:
+
+- All data lists and resources which are pushed to local nexus repository are available
+- Following ports are not occupied buy another service: 80, 8081, 8082, 10001
+- There's no docker container called "nexus"
+
+**Note: In case you skipped the Part 2 for the artifacts download,
+please ensure that the copy of resources data are untarred in
+./install/onap-offline/resources/**
+
+Whole nexus blob data tarball will be created by running script
+build\_nexus\_blob.sh. It will load the listed docker images, run the
+Nexus, configure it as npm and docker repository. Then it will push all
+listed npm packages and docker images to the repositories. After all is
+done the repository container is stopped and from the nexus-data
+directory is created tarball.
+
+There are mandatory parameters need to be set in configuration file:
+
++------------------------------+------------------------------------------------------------------------------------------+
+| Parameter                    | Description                                                                              |
++==============================+==========================================================================================+
+| NXS\_SRC\_DOCKER\_IMG\_DIR   | resource directory of docker images                                                      |
++------------------------------+------------------------------------------------------------------------------------------+
+| NXS\_SRC\_NPM\_DIR           | resource directory of npm packages                                                       |
++------------------------------+------------------------------------------------------------------------------------------+
+| NXS\_SRC\_PYPI\_DIR          | resource directory of npm packages                                                       |
++------------------------------+------------------------------------------------------------------------------------------+
+| NXS\_DOCKER\_IMG\_LIST       | list of docker images to be pushed to Nexus repository                                   |
++------------------------------+------------------------------------------------------------------------------------------+
+| NXS\_DOCKER\_WO\_LIST        | list of docker images which uses default repository                                      |
++------------------------------+------------------------------------------------------------------------------------------+
+| NXS\_NPM\_LIST               | list of npm packages to be published to Nexus repository                                 |
++------------------------------+------------------------------------------------------------------------------------------+
+| NXS\_PYPI\_LIST              | list of pypi packages to be published to Nexus repository                                |
++------------------------------+------------------------------------------------------------------------------------------+
+| NEXUS\_DATA\_TAR             | target tarball of Nexus data path/name                                                   |
++------------------------------+------------------------------------------------------------------------------------------+
+| NEXUS\_DATA\_DIR             | directory used for the Nexus blob build                                                  |
++------------------------------+------------------------------------------------------------------------------------------+
+| NEXUS\_IMAGE                 | Sonatype/Nexus3 docker image which will be used for data blob creation for this script   |
++------------------------------+------------------------------------------------------------------------------------------+
+
+Some of the docker images using default registry requires special
+treatment (e.g. they use different ports or SSL connection), therefore
+there is the list NXS\_DOCKER\_WO\_LIST by which are the images retagged
+to be able to push them to our nexus repository.
+
+**Note: It's recomended to use abolute paths in the configuration file
+for the current script**
+
+Example of the configuration file:
+
+::
+
+    NXS_SRC_DOCKER_IMG_DIR="/tmp/onap-offline/resources/offline_data/docker_images_for_nexus"
+    NXS_SRC_NPM_DIR="/tmp/onap-offline/resources/offline_data/npm_tar"
+    NXS_DOCKER_IMG_LIST="/tmp/onap-me-data_lists/docker_img.list"
+    NXS_DOCKER_WO_LIST="/tmp/onap-me-data_lists/docker_no_registry.list"
+    NXS_NPM_LIST="/tmp/onap-offline/bash/tools/data_list/npm_list.txt"
+    NXS_SRC_PYPI_DIR="/tmp/onap-offline/resources/offline_data/pypi"
+    NXS_DOCKER_IMG_LIST="/tmp/onap-me-data_lists/docker_img.list"
+    NXS_DOCKER_WO_LIST="/tmp/onap-me-data_lists/docker_no_registry.list"
+    NXS_NPM_LIST="/tmp/onap-offline/bash/tools/data_list/onap_3.0.0-npm.list"
+    NEXUS_DATA_TAR="/root/nexus_data.tar"
+    NEXUS_DATA_DIR="/tmp/onap-offline/resources/nexus_data"
+    NEXUS_IMAGE="/tmp/onap-offline/resources/offline_data/docker_images_infra/sonatype_nexus3_latest.tar"
+
+Once everything is ready you can run the script as following example:
+
+``$ ./install/onap-offline/build_nexus_blob.sh /root/nexus_build.conf``
+
+Where the nexus\_build.conf is the configuration file and the
+/root/nexus\_data.tar is the destination tarball
+
+**Note: Move, link or mount the NEXUS\_DATA\_DIR to the resources
+directory if there was different directory specified in configuration or
+use the resulting nexus\_data.tar for movement between machines.**
+
+Once the Nexus data blob is created, the docker images and npm packages
+can be deleted to reduce the package size as they won't be needed in the
+installation time:
+
+E.g.
+
+::
+
+    rm -f /tmp/onap-offline/resources/offline_data/docker_images_for_nexus/*
+    rm -rf /tmp/onap-offline/resources/offline_data/npm_tar
+
+Part 4. Application helm charts preparation and patching
+--------------------------------------------------------
+
+This is about to clone oom repository and patch it to be able to use it
+offline. Use the following command:
+
+./build/fetch\_and\_patch\_charts.sh <helm charts repo>
+<commit/tag/branch> <patchfile> <target\_dir>
+
+For example:
+
+``$ ./build/fetch_and_patch_charts.sh https://gerrit.onap.org/r/oom 3.0.0-ONAP /tmp/offline-installer/patches/casablanca_3.0.0.patch /tmp/oom-clone``
+
+Part 5. Creating offline installation package
+---------------------------------------------
+
+For the packagin itself it's necessary to prepare configuration. You can
+use ./build/package.conf as template or
+directly modify it.
+
+There are some parameters needs to be set in configuration file.
+Example values below are setup according to steps done in this guide to package ONAP.
+
++---------------------------------------+------------------------------------------------------------------------------+
+| Parameter                             | Description                                                                  |
++=======================================+==============================================================================+
+| HELM\_CHARTS\_DIR                     | directory with Helm charts for the application                               |
+|                                       |                                                                              |
+|                                       | Example: /tmp/oom-clone/kubernetes                                           |
++---------------------------------------+------------------------------------------------------------------------------+
+| APP\_CONFIGURATION                    | application install configuration (application_configuration.yml) for        |
+|                                       | ansible installer and custom ansible role code directories if any.           |
+|                                       |                                                                              |
+|                                       | Example::                                                                    |
+|                                       |                                                                              |
+|                                       |  APP_CONFIGURATION=(                                                         |
+|                                       |     /tmp/offline-installer/config/application_configuration.yml              |
+|                                       |     /tmp/offline-installer/patches/onap-casablanca-patch-role                |
+|                                       |  )                                                                           |
+|                                       |                                                                              |
++---------------------------------------+------------------------------------------------------------------------------+
+| APP\_BINARY\_RESOURCES\_DIR           | directory with all (binary) resources for offline infra and application      |
+|                                       |                                                                              |
+|                                       | Example: /tmp/onap-offline/resources                                         |
++---------------------------------------+------------------------------------------------------------------------------+
+| APP\_AUX\_BINARIES                    | additional binaries such as docker images loaded during runtime   [optional] |
++---------------------------------------+------------------------------------------------------------------------------+
+
+Offline installer packages are created with prepopulated data via
+following command run from offline-installer directory
+
+./build/package.sh <project> <version> <packaging target directory>
+
+E.g.
+
+``$ ./build/package.sh onap 1.0.1 /tmp/package"``
+
+
+So in the target directory you should find tar files with
+
+offline-<PROJECT\_NAME>-<PROJECT\_VERSION>-sw.tar
+
+offline-<PROJECT\_NAME>-<PROJECT\_VERSION>-resources.tar
+
+offline-<PROJECT\_NAME>-<PROJECT\_VERSION>-aux-resources.tar
diff --git a/docs/InstallGuide.rst b/docs/InstallGuide.rst
new file mode 100644
index 00000000..f34ee03e
--- /dev/null
+++ b/docs/InstallGuide.rst
@@ -0,0 +1,421 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2019 Samsung Electronics Co., Ltd.
+
+.. _oooi_installguide:
+
+OOM ONAP Offline Installer - Installation Guide
+===============================================
+
+This document describes the correct offline installation procedure for `OOM ONAP`_, which is done by the ansible based `offline-installer <https://gerrit.onap.org/r/#/admin/projects/oom/offline-installer>`_.
+
+Before you dive into the installation you should prepare the offline installer itself - the installer consists of at least two packages/resources. You can read about it in the `Build Guide`_, which provides the instructions for creating them.
+
+This current version of the *Installation Guide* supports `Casablanca release`_.
+
+-----
+
+.. _oooi_installguide_preparations:
+
+Part 1. Prerequisites
+---------------------
+
+OOM ONAP deployment has certain hardware resource requirements - `Casablanca requirements`_:
+
+- 14 VM (1 Rancher, 13 K8s nodes) - 8 vCPU - 16 GB RAM
+- 160 GB Storage
+
+That means the full deployment footprint is about ``224 GB RAM`` and ``112 vCPUs``. We will not follow strictly this setup due to such demanding resource consumption and so we will deploy our installation across four nodes (VMs) instead of fourteen. Our simplified setup is definitively not supported or recommended - you are free to diverge - you can follow the official guidelines or make completely different layout, but the minimal count of nodes should not drop below three - otherwise you may have to do some tweaking to make it work, which is not covered here (there is a pod count limit for a single kubernetes node - you can read more about it in this `discussion <https://lists.onap.org/g/onap-discuss/topic/oom_110_kubernetes_pod/25213556>`_).
+
+.. _oooi_installguide_preparations_k8s_cluster:
+
+Kubernetes cluster
+~~~~~~~~~~~~~~~~~~
+
+The four nodes/VMs will be running these services:
+
+- **infra-node**::
+
+    - nexus
+    - nginx proxy
+    - dns
+    - rancher server
+
+- **kubernetes node 1-3**::
+
+    - rancher agent
+
+You don't need to care about these services now - that is the responsibility of the installer (described below). Just start four VMs as seen in this table (or according to your needs as we hinted above):
+
+.. _Overview table of the kubernetes cluster:
+
+Kubernetes cluster overview
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+=================== ========= ==================== ============== ============ ===============
+KUBERNETES NODE     OS        NETWORK              CPU            RAM          STORAGE
+=================== ========= ==================== ============== ============ ===============
+**infra-node**      RHEL 7    ``10.8.8.100/24``    ``8 vCPUs``    ``8 GB``     ``100 GB``
+**kube-node1**      RHEL 7    ``10.8.8.101/24``    ``16 vCPUs``   ``48+ GB``   ``100 GB``
+**kube-node2**      RHEL 7    ``10.8.8.102/24``    ``16 vCPUs``   ``48+ GB``   ``100 GB``
+**kube-node3**      RHEL 7    ``10.8.8.103/24``    ``16 vCPUs``   ``48+ GB``   ``100 GB``
+SUM                                                ``56 vCPUs``   ``152+ GB``  ``400 GB``
+================================================== ============== ============ ===============
+
+Unfortunately, the offline installer supports only **RHEL 7.x** distribution as of now. So, your VMs should be preinstalled with this operating system - the hypervisor and platform can be of your choosing. It is also worth knowing that the exact RHEL version (major and minor number - 7.6 for example) should match for the package build procedure and the target installation. That means: if you are building packages on RHEL 7.6 release your VMs should be RHEL 7.6 too.
+
+We will expect from now on that you installed four VMs and they are connected to the shared network. All VMs must be reachable from our *install-server* (below), which can be the hypervisor, *infra-node* or completely different machine. But in either of these cases the *install-server* must be able to connect over ssh to all of these nodes.
+
+.. _oooi_installguide_preparations_installserver:
+
+Install-server
+~~~~~~~~~~~~~~
+
+We will use distinct *install-server* and keep it separate from the four-node cluster. But if you wish so, you can use *infra-node* for this goal (if you use the default ``'chroot'`` option of the installer), but in that case double the size of the storage requirement!
+
+Prerequisites for the *install-server*:
+
+- packages described in `Build Guide`_
+- extra ``100 GB`` storage (to have space where to store these packages)
+- installed ``'chroot'`` and/or ``'docker'`` system commands
+- network connection to the nodes - especially functioning ssh client
+
+Our *install-server* will have ip: ``10.8.8.4``.
+
+**NOTE:** All the subsequent commands below, are executed from within this *install-server*.
+
+-----
+
+.. _oooi_installguide_config:
+
+Part 2. Preparation and configuration
+-------------------------------------
+
+We *MUST* do all the following instructions from the *install-server* and also we will be running them as a user ``root``. But that is not necessary - you can without any problem pick and use a regular user. The ssh/ansible connection to the nodes will also expect that we are connecting as a ``root`` - you need to elevate privileges to be able to install on them. Although it can be achieved by other means (sudo), we decided here to keep instructions simple.
+
+.. _oooi_installguide_config_packages:
+
+Installer packages
+~~~~~~~~~~~~~~~~~~
+
+As was stated above you must have prepared the installer packages (names will differ - check out the `Build Guide`_):
+
+- offline-onap-3.0.1-resources.tar
+- offline-onap-3.0.1-aux-resources.tar
+- offline-onap-3.0.1-sw.tar
+
+**NOTE:** ``'offline-onap-3.0.1-aux-resources.tar'`` is optional and if you don't have use for it, you can ignore it.
+
+We will store them in the ``/data`` directory on the *install-server* and then we will unpack the ``'sw'`` package to your home directory for example::
+
+    $ mkdir ~/onap-offline-installer
+    $ tar -C ~/onap-offline-installer -xf /data/offline-onap-3.0.1-sw.tar
+
+.. _oooi_installguide_config_app:
+
+Application directory
+~~~~~~~~~~~~~~~~~~~~~
+
+Change the current directory to the ``'ansible'``::
+
+    $ cd ~/onap-offline-installer/ansible
+
+You can see multiple files and directories inside - this is the *offline-installer*. It is implemented as a set of ansible playbooks.
+
+If you created the ``'sw'`` package according to the *Build Guide* then you should had have the ``'application'`` directory populated with at least the following files:
+
+- ``application_configuration.yml``
+- ``hosts.yml``
+
+**NOTE:** The following paragraph describes a way how to create or fine-tune your own ``'application_configuration.yml'`` - we are discouraging you from executing this step. The recommended way is to use the packaged files inside the ``'application'`` directory.
+
+**NOT RECOMMENDED:** If for some reason you don't have these files inside the ``'application'`` directory or you simply want to do things the hard way then you can recreate them from their templates. It is better to keep the originals (templates) intact - so we will copy them to the ``'application'`` directory::
+
+    $ cp ../config/application_configuration.yml application/
+    $ cp inventory/hosts.yml application/
+
+.. _oooi_installguide_config_hosts:
+
+hosts.yml
+~~~~~~~~~
+
+We need to setup the ``'hosts.yml'`` first, the template looks like this::
+
+    ---
+    # This group contains hosts with all resources (binaries, packages, etc.)
+    # in tarball.
+    all:
+      vars:
+        # this key is supposed to be generated during setup.yml playbook execution
+        # change it just when you have better one working for all nodes
+        ansible_ssh_private_key_file: /root/.ssh/offline_ssh_key
+        ansible_ssh_common_args: '-o StrictHostKeyChecking=no'
+
+      children:
+        resources:
+          hosts:
+            resource-host:
+              ansible_host: 10.8.8.5
+
+        # This is group of hosts where nexus, nginx, dns and all other required
+        # services are running.
+        infrastructure:
+          hosts:
+            infrastructure-server:
+              ansible_host: 10.8.8.13
+              #IP used for communication between infra and kubernetes nodes, must be specified.
+              cluster_ip: 10.8.8.13
+
+        # This is group of hosts which are/will be part of Kubernetes cluster.
+        kubernetes:
+          hosts:
+            kubernetes-node-1:
+              ansible_host: 10.8.8.19
+              #ip of the node that it uses for communication with k8s cluster.
+              cluster_ip: 10.8.8.19
+
+        nfs-server:
+          hosts:
+            kubernetes-node-1
+
+There is some ssh configuration under the ``'vars'`` section - we will deal with ssh setup a little bit later in the `SSH authentication`_.
+
+We need to first correct the ip addresses and add a couple of kubernetes nodes to match our four-node cluster:
+
+- Under the ``'resource-host'`` set the ``'ansible_host'`` address to the ip of your server, where the packages are stored - it must be reachable by ssh from the *install-server* (for ansible to run playbooks on it)  **AND** *infra-node* (to extract resource data from *resource-host* to *infra-node* over ssh). In our scenario the *resource-host* is the same as the *install-server*: ``'10.8.8.4'``
+- Similarly, set the ``'ansible_host'`` to the address of the *infra-node* under the ``'infrastructure-server'``.
+- Copy the whole ``'kubernetes-node-1'`` subsection and paste it twice directly after.  Change the numbers to ``'kubernetes-node-2'`` and ``'kubernetes-node-3'`` respectively and fix the addresses in the ``'ansible_host'`` variables again to match *kube-node1*, *kube-node2* and *kube-node3*.
+
+As you can see, there is another ``'cluster_ip'`` variable for each node - this serve as a designated node address in the kubernetes cluster. Make it the same as the respective ``'ansible_host'``.
+
+**NOTE:** In our simple setup we have only one interface per node, but that does not need to be a case for some other deployment - especially if we start to deal with a production usage. Basically, an ``'ansible_host'`` is an entry point for the *install-server's* ansible (*offline-installer*), but the kubernetes cluster can be communicating on a separate network to which *install-server* has no access. That is why we have this distinctive variable, so we can tell the installer that there is a different network, where we want to run the kubernetes traffic and what address each node has on such a network.
+
+After all the changes, the ``'hosts.yml'`` should look similar to this::
+
+    ---
+    # This group contains hosts with all resources (binaries, packages, etc.)
+    # in tarball.
+    all:
+      vars:
+        # this key is supposed to be generated during setup.yml playbook execution
+        # change it just when you have better one working for all nodes
+        ansible_ssh_private_key_file: /root/.ssh/offline_ssh_key
+        ansible_ssh_common_args: '-o StrictHostKeyChecking=no'
+
+      children:
+        resources:
+          hosts:
+            resource-host:
+              ansible_host: 10.8.8.4
+
+        # This is group of hosts where nexus, nginx, dns and all other required
+        # services are running.
+        infrastructure:
+          hosts:
+            infrastructure-server:
+              ansible_host: 10.8.8.100
+              #IP used for communication between infra and kubernetes nodes, must be specified.
+              cluster_ip: 10.8.8.100
+
+        # This is group of hosts which are/will be part of Kubernetes cluster.
+        kubernetes:
+          hosts:
+            kubernetes-node-1:
+              ansible_host: 10.8.8.101
+              #ip of the node that it uses for communication with k8s cluster.
+              cluster_ip: 10.8.8.101
+            kubernetes-node-2:
+              ansible_host: 10.8.8.102
+              #ip of the node that it uses for communication with k8s cluster.
+              cluster_ip: 10.8.8.102
+            kubernetes-node-3:
+              ansible_host: 10.8.8.103
+              #ip of the node that it uses for communication with k8s cluster.
+              cluster_ip: 10.8.8.103
+
+        nfs-server:
+          hosts:
+            kubernetes-node-1
+
+.. _oooi_installguide_config_appconfig:
+
+application_configuration.yml
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here, we will be interested in the following variables:
+
+- ``resources_dir``
+- ``resources_filename``
+- ``aux_resources_filename``
+- ``app_data_path``
+- ``aux_data_path``
+- ``app_name``
+
+``'resource_dir'``, ``'resources_filename'`` and ``'aux_resources_filename'`` must correspond to the file paths on the *resource-host* (variable ``'resource_host'``), which is in our case the *install-server*.
+
+The ``'resource_dir'`` should be set to ``'/data'``, ``'resources_filename'`` to ``'offline-onap-3.0.1-resources.tar'`` and ``'aux_resources_filename'`` to ``'offline-onap-3.0.1-aux-resources.tar'``. The values should be the same as are in the `Installer packages`_ section.
+
+``'app_data_path'`` is the absolute path on the *infra-node* to where the package ``'offline-onap-3.0.1-resources.tar'`` will be extracted and similarly ``'aux_data_path'`` is another absolute path for ``'offline-onap-3.0.1-aux-resources.tar'``. Both the paths are fully arbitrary, but they should point to the filesystem with enough space - the storage requirement in `Overview table of the kubernetes cluster`_.
+
+**NOTE:** As we mentioned in `Installer packages`_ - the auxiliary package is not mandatory and we will not utilize it in here either.
+
+The last variable ``'app_name'`` should be short and descriptive. We will set it simply to: ``onap``.
+
+It can look all together something like this::
+
+    resources_dir: /data
+    resources_filename: offline-onap-3.0.1-resources.tar
+    app_data_path: /opt/onap
+    app_name: onap
+
+.. _oooi_installguide_config_ssh:
+
+SSH authentication
+~~~~~~~~~~~~~~~~~~
+
+We are almost finished with the configuration and we are close to start the installation, but we need to setup password-less login from *install-server* to the nodes.
+
+You can use the ansible playbook ``'setup.yml'`` like this::
+
+    $ ./run_playbook.sh -i application/hosts.yml setup.yml -u root --ask-pass
+
+You will be asked for password per each node and the playbook will generate a unprotected ssh key-pair ``'~/.ssh/offline_ssh_key'``, which will be distributed to the nodes.
+
+Another option is to generate a ssh key-pair manually. We strongly advise you to protect it with a passphrase, but for simplicity we will showcase generating of a private key without any such protection::
+
+    $ ssh-keygen -N "" -f ~/.ssh/identity
+
+The next step will be to distribute the public key to these nodes and from that point no password is needed::
+
+    $ for ip in 100 101 102 103 ; do ssh-copy-id -i ~/.ssh/identity.pub root@10.8.8.${ip} ; done
+
+This command behaves almost identically to the ``'setup.yml'`` playbook.
+
+If you generated the ssh key manually then you can now run the ``'setup.yml'`` playbook like this and achieve the same result as in the first execution::
+
+    $ ./run_playbook.sh -i application/hosts.yml setup.yml
+
+This time it should not ask you for any password - of course this is very redundant, because you just distributed two ssh keys for no good reason.
+
+We can finally edit and finish the configuration of the ``'hosts.yml'``:
+
+- if you used the ``'setup.yml'`` playbook then you can just leave this line as it is::
+
+    ansible_ssh_private_key_file: /root/.ssh/offline_ssh_key
+
+- if you created a ssh key manually then change it like this::
+
+    ansible_ssh_private_key_file: /root/.ssh/identity
+
+-----
+
+.. _oooi_installguide_install:
+
+Part 3. Installation
+--------------------
+
+We should have the configuration complete and be ready to start the installation. The installation is done via ansible playbooks, which are run either inside a **chroot** environment (default) or from the **docker** container. If for some reason you want to run playbooks from the docker instead of chroot then you cannot use *infra-node* or any other *kube-node* as the *install-server* - otherwise you risk that installation will fail due to restarting of the docker service.
+
+If you built your ``'sw'`` package well then there should be the file ``'ansible_chroot.tgz'`` inside the ``'docker'`` directory. If not then you must create it - to learn how to do that and to get more info about the scripts dealing with docker and chroot, go to `Appendix 1. Ansible execution/bootstrap`_
+
+We will use the default chroot option so we don't need any docker service to be running.
+
+Installation is actually very straightforward now::
+
+    $ ./run_playbook.sh -i application/hosts.yml -e @application/application_configuration.yml site.yml
+
+This will take a while so be patient.
+
+``'site.yml'`` playbook actually runs in the order the following playbooks:
+
+- ``upload_resources.yml``
+- ``infrastructure.yml``
+- ``rancher_kubernetes.yml``
+- ``application.yml``
+
+After all the playbooks are finished, it will still take a lot of time until all pods will be up and running. You can monitor your newly created kubernetes cluster for example like this::
+
+    $ ssh -i ~/.ssh/offline_ssh_key root@10.8.8.4 # tailor this command to connect to your infra-node
+    $ watch -d -n 5 'kubectl get pods --all-namespaces'
+
+-----
+
+.. _oooi_installguide_appendix1:
+
+Appendix 1. Ansible execution/bootstrap
+---------------------------------------
+
+There are two ways how to easily run the installer's ansible playbooks:
+
+- If you already have or can install a docker then you can build the provided ``'Dockerfile'`` for the ansible and run playbooks in the docker container.
+- Another way to deploy ansible is via chroot environment which is bundled together within this directory.
+
+(Re)build docker image and/or chroot archive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Inside the ``'docker'`` directory is the ``'Dockerfile'`` and ``'build_ansible_image.sh'`` script. You can run ``'build_ansible_image.sh'`` script on some machine with the internet connectivity and it will download all required packages needed for building the ansible docker image and for exporting it into a flat chroot environment.
+
+Built image is exported into ``'ansible_chroot.tgz'`` archive in the same (``'docker'``) directory.
+
+This script has two optional arguments:
+
+#. ansible version
+#. docker image name
+
+**Note:** if optional arguments are not used, docker image name will be set to ``'ansible'`` by default.
+
+Launching ansible playbook using chroot environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the default and preferred way of running ansible playbooks in an offline environment as there is no dependency on docker to be installed on the system. Chroot environment is already provided by included archive ``'ansible_chroot.tgz'``.
+
+It should be available in the ``'docker'`` directory as the end-result of the packaging script or after manual run of the ``'build_ansible_image.sh'`` script referenced above.
+
+All playbooks can be executed via ``'./run_playbook.sh'`` wrapper script.
+
+To get more info about the way how the ``'./run_playbook.sh'`` wrapper script should be used, run::
+
+    $ ./run_playbook.sh
+
+The main purpose of this wrapper script is to provide the ansible framework to a machine where it was bootstrapped without need of installing additional packages. The user can run this to display ``'ansible-playbook'`` command help::
+
+    $ ./run_playbook.sh --help
+
+Developers notes
+~~~~~~~~~~~~~~~~
+
+* There are two scripts which work in tandem for creating and running chroot
+* First one can convert docker image into chroot directory
+* Second script will automate chrooting (necessary steps for chroot to work and cleanup)
+* Both of them have help - just run::
+
+    $ cd docker
+    $ ./create_docker_chroot.sh help
+    $ ./run_chroot.sh help
+
+Example usage::
+
+    $ sudo su
+    $ docker/create_docker_chroot.sh convert some_docker_image ./new_name_for_chroot
+    $ cat ./new_name_for_chroot/README.md
+    $ docker/run_chroot.sh execute ./new_name_for_chroot cat /etc/os-release 2>/dev/null
+
+Launching ansible playbook using docker container (ALTERNATIVE APPROACH)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This option is here just to keep support for the older method which relies on a running docker service. For the offline deployment use the chroot option as indicated above.
+
+You will not need ``'ansible_chroot.tgz'`` archive anymore, but the new requirement is a prebuilt docker image of ansible (based on the provided ``'Dockerfile'``). It should be available in your local docker repository (otherwise the default name ``'ansible'`` may fetch unwanted image from default registry!).
+
+To trigger this functionality and to run ``'ansible-playbook'`` inside a docker container instead of the chroot environment, you must first set the ``ANSIBLE_DOCKER_IMAGE`` variable. The value must be a name of the built ansible docker image.
+
+Usage is basically the same as with the default chroot way - the only difference is the existence of the environment variable::
+
+    $ ANSIBLE_DOCKER_IMAGE=ansible ./run_playbook.sh --help
+
+-----
+
+.. _Build Guide: ./BuildGuide.rst
+.. _Casablanca requirements: https://onap.readthedocs.io/en/casablanca/guides/onap-developer/settingup/index.html#installing-onap
+.. _Casablanca release: https://docs.onap.org/en/casablanca/release/
+.. _OOM ONAP: https://wiki.onap.org/display/DW/ONAP+Operations+Manager+Project
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 00000000..a43eedf5
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,11 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+OOM offline-installer
+=====================
+
+.. toctree::
+   :maxdepth: 2
+
+   BuildGuide.rst
+   InstallGuide.rst
+