JIRA DOMINO-23

new directory structure
new API description
split documents

Change-Id: Iedffd5266c19f9713930011ef8fde7e55fd3ae66
Signed-off-by: Ulas Kozat <ulas.kozat@gmail.com>

5 files changed, 299 insertions, 0 deletions

diff --git a/docs/release/installation/featureconfig.rst b/docs/release/installation/featureconfig.rst
new file mode 100644
index 0000000..5364dbe
--- /dev/null
+++ b/docs/release/installation/featureconfig.rst
@@ -0,0 +1,40 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. image:: ../etc/opnfv-logo.png
+  :height: 40
+  :width: 200
+  :alt: OPNFV
+  :align: left
+.. these two pipes are to seperate the logo from the first title
+|
+|
+Domino Configuration
+====================
+Domino Server and Clients can be configured via (i) passing command line options
+(see API documentation) and (ii) the configuration file "domino_conf.py" under the
+main directory.
+
+* The default file for logging is set as none and log level set as "WARNING".
+
+Domino Server
+-------------
+* The default server unique user ID is set as 0 in the configuration file.
+
+* The default TCP port for RPC calls is set as 9090 in the configuration file.
+
+* The default database file for Domino Server is set as "dominoserver.db" under the main directory
+
+* The default folder for keeping published TOSCA files and pushed parts is set as "toscafiles" in the configuration file via variable TOSCADIR.
+
+Domino Client
+-------------
+* The default mode of CLI is non-interactive (i.e., Domino CLI Utility is used). This can be changed when the DominoClient is launched by passing the flags --log or -l followed by the
+log level choice from the set {ERROR, WARNING, INFO, DEBUG} (not case sensitive). This overwrites the log level default specified in the configuration file.
+
+* The default Domino Server IP is set as "localhost". This can be overwritten at the time of launching DominoClient via the option flags -i or --ipaddr followed by the IP address of the actual server hosting the Domino Server.
+
+* The default Domino Client TCP port for RPC calls is set as 9091 in the configuration file. It can be overwritten when the DominoClient is launched by passing the flags --port or -p followed by the port number.
+
+* The default folder for keeping preceived TOSCA files is set as "toscafiles" in the configuration file via variable TOSCA_RX_DIR.
+
diff --git a/docs/release/installation/index.rst b/docs/release/installation/index.rst
new file mode 100644
index 0000000..f77c38a
--- /dev/null
+++ b/docs/release/installation/index.rst
@@ -0,0 +1,21 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. image:: ../etc/opnfv-logo.png
+  :height: 40
+  :width: 200
+  :alt: OPNFV
+  :align: left
+|
+|
+**********************
+Installation procedure
+**********************
+Colorado 1.0
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   installation.instructions.rst
+   featureconfig.rst
diff --git a/docs/release/installation/installation.instructions.rst b/docs/release/installation/installation.instructions.rst
new file mode 100644
index 0000000..4e18491
--- /dev/null
+++ b/docs/release/installation/installation.instructions.rst
@@ -0,0 +1,50 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+===================
+Domino Installation
+===================
+
+Note: The steps below are tested for Ubuntu (16.04, 14.04) and OS X El Capitan.
+
+Prerequisites
+-------------
+* git
+* python-pip
+* python (version =2.7)
+* tosca-parser (version >=0.4.0)
+* heat-translator (version >=0.5.0)
+
+Installation Steps (Single Node)
+--------------------------------
+
+* Step-0: Prepare Environment
+
+.. code-block:: bash
+
+  > $sudo pip install tosca-parser
+  > $sudo pip install heat-translator
+  > $sudo pip install requests
+
+* Step-1: Get the Domino code
+
+.. code-block:: bash
+
+  git clone https://gerrit.opnfv.org/gerrit/domino -b stable/danube
+
+* Step-2: Go to the main domino directory
+
+.. code-block:: bash
+
+  cd domino
+
+You should see DominoClient.py, DominoServer.py, and domino-cli.py as executables.
+
+Installation Steps (Multiple Node)
+----------------------------------
+
+Repeat the installation steps for single node on each node. The script
+run_multinode.sh under ./domino/tests directory deploys the Domino Code on three
+hosts from a deployment node and tests RPC calls. The private key location and
+remote host IP addresses must be manually entered and IS_IPandKEY_CONFIGURED=false
+must be changed to IS_IPandKEY_CONFIGURED=true.
diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst
new file mode 100644
index 0000000..920c2ec
--- /dev/null
+++ b/docs/release/userguide/feature.userguide.rst
@@ -0,0 +1,177 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+============================================
+Domino and API Usage Guidelines and Examples
+============================================
+
+Using domino-cli Client
+=======================
+
+Prerequisites:
+
+1. Make sure that domino-cli.py is in +x mode.
+
+2. Change directory to where domino-cli.py, DominoClient.py and DominoServer.py are located or include file path in the PATH environment variable.
+
+3. Start the Domino Server:
+
+.. code-block:: bash
+
+  ./DominoServer.py --log=debug
+
+4. Start the Domino Client:
+
+.. code-block:: bash
+
+  ./DominoClient.py -p <portnumber> --cliport <cli-portnumber> --log=debug
+
+Note1: The default log level is WARNING and omitting --log option will lead to minimal/no logging on the console
+
+Note2: domino_conf.py file includes most of the default values
+
+* Registration Command
+
+Command line input:
+
+.. code-block:: bash
+
+  ./domino-cli.py <cli-portnumber> register
+
+This message has the following fields that are automatically filled in.
+
+.. code-block:: bash
+
+  Message Type (= REGISTER)
+  DESIRED UDID (= if not allocated, this will be assigned as Unique Domino ID)
+  Sequence Number (=incremented after each RPC call)
+  IP ADDR (= IP address of DOMINO Client to be used by DOMINO Server for future RPC Calls to this client)
+  TCP PORT (= TCP port of DOMINO Client to be used by DOMINO Server for future RPC Calls to this client)
+  Supported Templates (= Null, this field not used currently)
+
+* Heart Beat Command
+
+Command line input:
+
+.. code-block:: bash
+
+  ./domino-cli.py <cli-portnumber> heartbeat
+
+This message has the following fields that are automatically filled in.
+
+.. code-block:: bash
+
+  Message Type (= HEART_BEAT)
+  UDID (= Unique Domino ID assigned during registration)
+  Sequence Number (=incremented after each RPC call)
+
+* Label and Template Type Subscription Command
+
+.. code-block:: bash
+
+  ./domino-cli.py <cli-portnumber> subscribe -l <labelname> -t <templatetype>
+
+Note that -l can be substituted by --label and -t can be substituted by --ttype.
+
+More than one label or template type can be subscribed within the same command line as comma separated labels or template types
+
+.. code-block:: bash
+
+  ./domino-cli.py <cli-portnumber> subscribe -l <label1>,<label2>,<labeln> -t <ttype1>,<ttype2>,<ttypen>
+
+To subscribe more than one label or template type, one can also repeat the options -l and -t, e.g.:
+
+.. code-block:: bash
+
+  ./domino-cli.py <cli-portnumber> subscribe -l <label1> -l <label2> -l <labeln> -t <ttype1> -t <ttype2> -t <ttypen>
+
+It is safe to call subscribe command multiple times with duplicate labels.
+
+This message has the following fields that are automatically filled in.
+
+.. code-block:: bash
+
+  Message Type (= SUBSCRIBE)
+  UDID (= Unique Domino ID assigned during registration)
+  Sequence Number (=incremented after each RPC call)
+  Template Operation (= APPEND)
+  Label Operation (= APPEND)
+
+The following fields are filled in based on arguments passed on via -l/--label and -t/--ttype flags
+
+Subscribe RPC also supports options for label using
+  --lop=APPEND/DELETE/OVERWRITE
+and for supported template types using
+  --top=APPEND/DELETE/OVERWRITE.
+When unspecified, the default is APPEND.
+DELETE deletes existing labels (template types) specified in the current call via key -l/--label (-t/--ttype).
+OVERWRITE removes the current set of labels (template types) and sets it to the new set of values passed in the same RPC call.
+
+By default, no translation service is provided. Currently, only TOSCA to Heat
+Orchestration Template (HOT) translation is supported using OpenStack
+heat-translator library. A domain that requires HOT files must subscribe HOT
+template type using
+
+.. code-block:: bash
+
+  ./domino-cli.py <cli-portnumber> subscribe -t hot
+
+* Template Publishing Command
+
+.. code-block:: bash
+
+  ./domino-cli.py <cli-portnumber> publish -t <toscafile>
+
+Note that -t can be substituted with --tosca-file.
+
+If -t or --tosca-file flag is used multiple times, the last tosca file passed as input will be used. This usage is not recommended as undefined/unintended results may emerge as the Domino client will continue to publish.
+
+This message has the following fields that are automatically filled in.
+
+.. code-block:: bash
+
+  Message Type (= PUBLISH)
+  UDID (= Unique Domino ID assigned during registration)
+  Sequence Number (=incremented after each RPC call)
+  Template Type (= TOSCA)
+  Template File
+
+Since Danube release, Domino Server supports stateful updates for template publishing. The following command can be used to update the service template for an existing Template Unique ID (TUID):
+
+.. code-block:: bash
+
+  ./domino-cli.py <cli-portnumber> publish -t <toscafile> -k <TUID>
+
+Note that -k can be substituted with --tuid. When Domino Server receives this command, it verifies whether
+the client previously published the provided TUID. If such TUID does not exist, then Domino Server returns
+FAILED response back to the client. If such TUID exists, Domino Server recomputes which resources are
+mapped onto which domains and updates each domain with the new VNF and NS descriptors. If a previously
+utilized domain is no longer targeted, it is updated with a null descriptor.
+
+* Template Listing Command
+
+.. code-block:: bash
+
+  ./domino-cli.py <cli-portnumber> list-tuids
+
+Queries all the Template Unique IDs (TUIDs) published by the Domino Client from the Domino Server.
+
+Interactive CLI mode
+--------------------
+
+To enter this mode, start Domino Client with interactive console option set as true, i.e., --iac=true:
+
+.. code-block:: bash
+
+  ./DominoClient -p <portnumber> --iax=true --log=DEBUG
+
+The rest of the API calls are the same as in the case of using domino-cli.py except that at the prompt there is no need to write "domino-cli.py <cli-portnumber>, e.g.,:
+
+.. code-block:: bash
+
+  >>register
+  >>heartbeat
+  >>subscribe -l <label1> -t <ttype1>
+  >>publish -t <toscafile>
+
+The interactive CLI mode is mainly supported for manual testing.
diff --git a/docs/release/userguide/index.rst b/docs/release/userguide/index.rst
new file mode 100644
index 0000000..2092cf7
--- /dev/null
+++ b/docs/release/userguide/index.rst
@@ -0,0 +1,11 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+*****************
+Domino User Guide
+*****************
+
+.. toctree::
+   :maxdepth: 3
+
+   feature.userguide.rst