.. Benchmarking Suite
.. Copyright 2014-2020 Engineering Ingegneria Informatica S.p.A.

.. Licensed under the Apache License, Version 2.0 (the "License");
.. you may not use this file except in compliance with the License.
.. You may obtain a copy of the License at
.. http://www.apache.org/licenses/LICENSE-2.0

.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS,
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.. See the License for the specific language governing permissions and
.. limitations under the License.

.. Developed in the ARTIST EU project (www.artist-project.eu), the
.. CloudPerfect EU project (https://cloudperfect.eu/) and EasyCloud,
.. an innovation activity supported by EIT Digital 
.. (https://www.eitdigital.eu)


############
Installation
############

This section discusses the hardware and software requirements as well as the process of installing the Benchmarking Suite.

CLI installation
----------------

The Benchmarking Suite is package and distributed through PyPI_.

.. important::

    The Benchmarking Suite requires Python 3.5+. If it is not the default version in you system, it is recommended
    to create a virtualenv:

        .. code-block:: bash

            virtualenv -p /usr/bin/python3.5 benchmarking-suite
            source benchsuite/bin/activate

Let's start by installing the command line tool and the standard library:

.. code-block:: bash

  $ pip install benchsuite.stdlib benchsuite.cli

This will make available the ``benchsuite`` bash command and will copy the standard benchmark tests configuration into the default configuration location (located under ``~/.config/benchmarking-suite/benchmarks``).

Service installation
--------------------

The Benchmarking Suite has also been packaged as a SaaS solution to fit different usage scenarios. This way, once installed on a server, all functionalities will be available through your web browser in a multi-tenant environment.

The Benchmarking Suite is distributed as a multi-container Docker application defined through Docker Compose.
Individual components are shipped as Docker images, while the whole suite can be deployed and orchestrated through Docker Swarm.

For each individual service in the 'docker-compose.yml' here is the list of the variables to configure. A description of each service can be found in the next sections.

Note that the template 'docker-compose.yml' in the code repository references a '.env' configuration file where all secrets are configured.

1) Clone the repository:

.. code-block:: bash

    git clone https://gitlab.res.eng.it/benchsuite/benchsuite-compose.git

2) Create a `.env` file with the following content:

.. code-block:: bash

   # Keycloak
   DB_USER=keycloak-user
   DB_PASSWORD=keycloak-pass
   KEYCLOAK_USER=admin
   KEYCLOAK_PASSWORD=admin
   
   # Postgres (for Keycloak)
   POSTGRES_USER=keycloak-user
   POSTGRES_PASSWORD=keycloak-password
   
   #Grafana
   GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET=<some temporary secret>
   
   #Influx
   INFLUXDB_ADMIN_USER=influx-user
   INFLUXDB_ADMIN_PASSWORD=influx-password
   
   #Benchsuite API
   BENCHSUITE_OIDC_CLIENT_SECRET=<some temporary secret>
   BENCHSUITE_DEV_KEY=aSecretDevKey
   # AES_KEY must be 16 characters long!
   AES_KEY=This_is_a_key123
   
   # Syndication Client
   MARKETPLACE_USER=marketplace-user
   MARKETPLACE_PASSWORD=marketplace-password
   MARKETPLACE_SYNDICATION_EVENT_SIGNATURE_TOKEN=marketplace-token
   MARKETPLACE_BENCHSUITE_SKU=marketplace-sku
   GRAFANA_USERNAME=grafana-admin-user
   GRAFANA_PASSWORD=grafana-admin-password
   KEYCLOAK_ADMIN_CLIENT_SECRET_KEY=<some temporary secret>

Further details about the Marketplace Syndication are available at: https://docs.cloudesire.com/docs/syndication.html

3) Make sure that INFLUXDB_ADMIN_USER and INFLUXDB_ADMIN_PASSWORD match the values `username` and `password` in the storage.conf file

4) Make sure that DB_USER and DB_PASSWORD match POSTGRES_USER and POSTGRES_PASSWORD

5) Set stack name and network domain env variables:
   
.. code-block:: bash

    $ export STACK_NAME=bes1
    
    $ export NET_DOMAIN=benchsuite.acme.org

6) Create the `traefik.yaml` file for the Traefik dynamic configuration:


.. code-block:: bash

    tls:
      options:
        default:
          minVersion: VersionTLS12
          cipherSuites:
            - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
            - TLS_RSA_WITH_AES_256_GCM_SHA384
   
7) Create an empty file with permission 600 called `traefik-acme.json`. It will contain the certificates generated by Traefik
  
   
8) Deploy the stack
   
.. code-block:: bash

    sudo NET_DOMAIN=$NET_DOMAIN STACK_NAME=$STACK_NAME docker stack deploy -c docker-compose.yml $STACK_NAME
   
9) Setup Keycloak
   
   a) Access https://$NET_DOMAIN/auth/
   
   #) Create a realm named "benchsuite"
   
   #) Set frontend url in realm settings to "https://$NET_DOMAIN/auth/"
   
   #) create a client named "grafana"
   
      1) set redirect uri to https://$NET_DOMAIN/charts/\*
      #) make it 'confidential'
      #) create roles admin, viewer and editor
      #) create a mapper for the role (type: "User Client Role", token claim name: "roles", json type: "string")
   
   #) copy grafana client secret and set the env var
   
   #) create "benchsuite-api" client
   
      1) set redirect uri to "https://$NET_DOMAIN/\*"
      #) make it 'confidential'
   
   #) create a user, assign grafana role

10) Update the .env with client secrets as generated/set in Keycloak. The following variables must be set:

.. code-block:: bash

   GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET
   
   BENCHSUITE_OIDC_CLIENT_SECRET
   
   KEYCLOAK_ADMIN_CLIENT_SECRET_KEY

11) Redeploy the stack
   
.. code-block:: bash

    $ sudo docker stack rm $STACK_NAME
    
    $ sudo NET_DOMAIN=$NET_DOMAIN STACK_NAME=$STACK_NAME docker stack deploy -c docker-compose.yml $STACK_NAME
   
.. _PyPI: https://pypi.org/