.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. (c) OPNFV, Huawei Technologies Co.,Ltd and others.

===============================
Running Dovetail by RESTful API
===============================

Overview
--------

Dovetail framework provides RESTful APIs for end users to run all OVP test cases.
Also it provides a Swagger UI for users to find out all APIs and try them out.


Definitions and abbreviations
-----------------------------

- REST - Representational State Transfer
- API - Application Programming Interface
- OVP - OPNFV Verification Program
- UI - User Interface


Environment Preparation
-----------------------


Install Docker
^^^^^^^^^^^^^^

The main prerequisite software for Dovetail is Docker. Please refer to `official
Docker installation guide <https://docs.docker.com/install/>`_ which is relevant
to your Test Host's operating system.


Configuring the Test Host Environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For convenience and as a convention, we will create a home directory for storing
all Dovetail related config items and results files:

.. code-block:: bash

   $ mkdir -p ${HOME}/dovetail
   $ export DOVETAIL_HOME=${HOME}/dovetail


Installing Dovetail API
-----------------------

The Dovetail project maintains a Docker image that has both Dovetail API and
Dovetail CLI preinstalled. This Docker image is tagged with versions.
Before pulling the Dovetail image, check the OPNFV's OVP web page first to
determine the right tag for OVP testing.


Downloading Dovetail Docker Image
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The first version of Dovetail API is ovp-3.x.x.

.. code-block:: bash

   $ sudo docker pull opnfv/dovetail:latest
   latest: Pulling from opnfv/dovetail
   6abc03819f3e: Pull complete
   05731e63f211: Pull complete
   0bd67c50d6be: Pull complete
   3f737f5d00b2: Pull complete
   c93fd0792ebd: Pull complete
   77d9a9603ec6: Pull complete
   9463cdd9c628: Pull complete
   Digest: sha256:45e2ffdbe217a4e6723536afb5b6a3785d318deff535da275f34cf8393af458d
   Status: Downloaded newer image for opnfv/dovetail:latest


Deploying Dovetail API
^^^^^^^^^^^^^^^^^^^^^^

The Dovetail API can be deployed by running a Dovetail container with the Docker
image downloaded before.

.. code-block:: bash

   $ docker run -itd -p <swagger_port>:80 -p <api_port>:5000 --privileged=true \
     -e SWAGGER_HOST=<host_ip>:<swagger_port> -e DOVETAIL_HOME=/home/ovp \
     -v /home/ovp:/home/ovp -v /var/run/docker.sock:/var/run/docker.sock \
     opnfv/dovetail:<version>


In the container, it uses 2 ports for Swagger UI (port 80) and API (port 5000)
respectively. So in order to access to these 2 services outside the container,
it needs to map them to the host ports. It can be any available ports in the host.

The env SWAGGER_HOST is optional. If you will access the Swagger UI webpage with
the same host deploying this container, there is no need to set SWAGGER_HOST.
Otherwise, if you will access the Swagger UI webpage from other machines, then
it needs to set SWAGGER_HOST.


Using Dovetail API
------------------

Here give the guide of where to find out all APIs and how to use them.


Swagger UI Webpage
^^^^^^^^^^^^^^^^^^

After deploying Dovetail container, the Swagger UI webpage can be accessed with
any browser. The url is `http://localhost:<swagger_port>/dovetail-api/index.html`
if accessing from the same host as deploying this container. Otherwise, the url
is `http://<host_ip>:<swagger_port>/dovetail-api/index.html`.