Guia de instalação

Esta página contém informação de como instalar a dojot utilizando o docker-compose. O suporte à instalação em ambientes Kubernetes e Google Cloud estão em andamento no projeto.

Requisitos de hardware

Para que a dojot seja executada apropriadamente, os requisitos mínimos de hardware são:

  • 4GB de RAM
  • 10GB de espaço livre em disco
  • Acesso à rede
  • As seguintes portas devem estar abertas:
    • TCP (conexões de entrada): 1883 (MQTT), 8883 (MQTT seguro, se utilizado), 8000 (acesso à interface web)
    • TCP (conexões de saída): 25 (se envio de email nos fluxos for utilizado)

Docker-compose

Este documento contém instruções de como criar um ambiente para instalação trivial da dojot em um único host utilizando o docker-compose como o processo de orquestração da plataforma.

Muito simples, esta opção de instalação é a que melhor se adapta para desenvolvimento e verificação da plataforma dojot, mas não é aconselhável para ambientes de produção.

Este guia foi verificado utilizando-se o sistema operacional Ubuntu 16.04 LTS.

As seções seguintes descrevem todas as dependências do docker-compose.

Docker engine (motor do docker)

Informações atualizadas e procedimentos de instalação para o docker engine podem ser encontrados na documentação do projeto:

https://docs.docker.com/engine/installation/

Nota

Um passo adicional no processo de instalação e configuração do docker em um determinado equipamento é definir quem será elegível para criar/iniciar instâncias do docker.

Caso os passos pós-instalação não tiverem sido executados (mais especificamente o “Manage docker como usuário não-root”), todos os comandos do docker e do docker-compose devem ser executados pelo super usuário (root), ou invocando o sudo.

https://docs.docker.com/engine/installation/linux/linux-postinstall/

Docker-compose

Informações atualizadas sobre procedimentos de instalação para o docker-compose podem ser encontradas na documentação do projeto:

https://docs.docker.com/compose/install/

Instalação

Para construir o ambiente, simplesmente clone o repositório e execute os comandos abaixo.

O repositório com os scripts de instalação e configuração do docker-compose podem ser encontrados em:

https://github.com/dojot/docker-compose

ou com o comando git clone::

git clone https://github.com/dojot/docker-compose.git
# Let's move into the repo - all commands in this page should be executed
# inside it.
cd docker-compose

Uma vez que o repositório esteja propriamente clonado, selecione a versão a ser utilizada por meio da tag apropriada (note que o tagname deve ser substituído):

# Must be run from within the deployment repo

git checkout tag_name -b branch_name

Por exemplo:

git checkout v0.3.1 -b v0.3.1

Ou se você for muito ousado:

git checkout master

Depois que o repositório estiver clonado e uma versão (tag) ou branch tiver sido selecionado, haverá ainda alguns módulos que devem ser instalados antes de utilizar a plataforma. Esses módulos podem ser obtidos executando o seguinte comando:

git submodule update --init --recursive

Feito isso, o ambiente pode ser iniciado assim:

# Must be run from the root of the deployment repo.
# May need sudo to work: sudo docker-compose up -d
docker-compose up -d

Para verfificar o estado de um container individual, comandos do docker podem ser utilizados, como por exemplo:

# Shows the list of currently running containers, along with individual info
docker ps

# Shows the list of all configured containers, along with individual info
docker ps -a

Nota

Todos os comandos para docker e docker-compose podem requerer credenciais de super usuário (root) ou sudo.

Para permitir usuários “não-root” gerenciar o docker, confira a documentação do docker:

https://docs.docker.com/engine/installation/linux/linux-postinstall/

Utilização

A interface web está disponível em http://localhost:8000. O usuário é admin e a senha é admin. Você também pode interagir com a plataforma utilizando o Components and APIs.

Read the Utilizando a API da dojot and Usando a interface WEB for more information about how to interact with the platform.

Kubernetes

This section provides instructions on how to create a dojot deployment on a multi-node environment, using Kubernetes as the orchestration platform.

This deployment option when properly configured can be used for creating production environments.

The following sections describe all dependencies and steps required for this deployment.

Kubernetes Cluster

For this guide it is advised that you already have a working K8s cluster.

If you need to build a Kubernetes cluster from scratch, up to date information and installation procedures can be found at Kubernetes setup documentation.

Kubernetes Requirements

  • The minimum Kubernetes supported version is v1.11.
  • Access to Docker Hub repositories
  • (optional) a storage class that will be used for persistent storage

dojot Deployment

To deploy dojot to Kubernetes it is advised the use of ansible playbooks developed for dojot. The playbooks and all the related code can be found on the repository Ansible dojot.

The following steps will describe how to use this repository and its playbooks.

1. Cloning the repository

The first deployment step is cloning the repository. To do so, execute the command:

git clone https://github.com/dojot/ansible-dojot

2. Installing dependencies

The next step is installing the dependencies for running the ansible playbook, this dependencies include ansible itself with other modules that will be used to parse templates and communicate with kubernetes.

Enter the folder where the repository was downloaded and install the pip packages with the following commands:

cd ansible-dojot
pip install -r requirements.txt

3. Configuring the inventory

For deploying kubernetes with ansible, it is necessary to model your desired environment on an ansible inventory.

In the repository there is an ‘inventory’ folder containing an example inventory called ‘example_local’ that can be used as the starting point to creating the real environment inventory.

The first file that requires changes is the hosts.yaml. This file describes the nodes that will be accessed by ansible to perform the deployment. As the dojot deployment is done directly to K8s, only a node with access to the kubernetes cluster is actually required.

The node that will access the cluster might be a kubernetes cluster node that is accessible via SSH or event your local machine if it can reach the kubernetes cluster with a configuration file.

On the example file, the access is done via a local node, where the ansible script is executed. This node is described as localhost in the hosts item of the group all.

These same nodes must be added as children of the group dojot-k8s.

To configure a local access on the hosts file, follow the example below:

---
all:
  hosts:
    localhost:
      ansible_connection: local
      ansible_python.version.major: 3
  children:
    dojot-k8s:
      hosts:
        localhost:

To configure remote access via ssh to a node of the cluster, follow this other example:

---
all:
  hosts:
    NODE_NAME:
      ansible_host: NODE_IP
  children:
    dojot-k8s:
      hosts:
        NODE_NAME:

The next step is configuring the mandatory and optional variables required for deploying dojot.

There is a document describing each of the variables that can be configured at Ansible dojot variables.

This variables must be set for the group ‘dojot-k8s’, to do so set their values on the file dojot.yaml on the folder ‘group_vars/dojot-k8s/

4. Executing the deployment playbook

Now that the inventory is set, the next step is executing the deployment playbook.

To do so, run the following command:

ansible-playbook -K -k -i inventories/YOUR_INVENTORY deploy.yaml

Wait for the playbook execution to finish without errors.

5. Accessing the deployed dojot environment

Dojot access will be set using NodePorts, to view the proper ports to access the environment it is necessary to check service configuration.

kubectl get service -n dojot kong iotagent-mosca

This command will return the port used for external access to both the REST API and GUI via kong and the MQTT port via iotagent-mosca.