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.
Table of Contents
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:
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.
Leia o tutorials/using-api-interface e tutorials/using-web-interface para maiores informações sobre como interagir com a plataforma dojot.
Kubernetes¶
This section provides instructions on how to create a simple dojot deployment environment on a multi-node environment, using Kubernetes as the orchestration platform.
This deployment option as presented in this document is best suited for testing and platform assessment. With appropriate changes, this option can be also be used in production environments.
This guide has been checked on a Kubernetes cluster with Ceph as the underlying storage infrastructure and it has also been tested on a Kubernetes cluster over the Google Cloud Platform
The following sections describe all Kubernetes dependencies.
Kubernetes Cluster¶
For this guide it is advised that you already have a working cluster.
If you desire to prepare a Kubernetes cluster from scratch, up to date information and installation procedures can be found at Kubernetes setup documentation.
Persistent Storage¶
To make sure that all the data from the containers running databases is persisted when containers fail or are moved to different nodes of the Kubernetes environment it is necessary to attach persistent storage to the database pods.
Kubernetes requires that an infrastructure for persistent storage already exists on the cluster. As an example for how to configure your persistent storage we provide files for two different kind of deployments, the first is for a local deployment where a Ceph Cluster is used as storage backend, more information on Ceph may be found at: http://ceph.com/. The second example is based on a Google Cloud deployment and use the existing persistent storage services that are provided by Google Cloud. If you’re deploying dojot using Kubernetes to a different cloud provider, some adjustments to fit the different deployments might be necessary.
Information about the currently supported persistent storage for Kubernetes can be found at persistent-volumes page.
Kubernetes Client¶
To install the Kubernetes client on your machine before proceeding with this guide, follow the proper instructions as presented on the Kubernetes documentation.
Also, verify that your client is capable of connecting to the cluster.
For providing access for a local cluster, follow the documentation below:
https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/
If the Kubernetes cluster is running on a specific cloud platform like Google Cloud, follow the steps as presented by your cloud provider.
Deployment¶
To deploy dojot to a Kubernetes environment, we provide a script for clusters with Ceph as storage solution.
To download the required files using git, run the following command:
git clone https://github.com/dojot/kubernetes.git
or, to download a compressed zip file containing the data, use the following link: https://github.com/dojot/kubernetes/archive/master.zip
This repository contains all the scripts and deployment files necessary to
properly setup dojot’s containers. There is one file that must be changed:
config.yaml
, which contains all the parameters used by these scripts. An
example of such file is this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | ---
version: 0.2.0-nightly20180319
namespace: dojot
storage:
type: ceph
cephMonitors:
- '10.0.0.1:6789'
- '10.0.0.2:6789'
- '10.0.0.3:6789'
cephAdminId: admin
cephAdminKey: AQD85Z5a/wnlJBAARNISUDpC6RHc8g/UkUcDLA==
cephUserId: admin
cephUserKey: AQD85Z5a/wnlJBAARNISUDpC6RHc8g/UkUcDLA==
cephPoolName: kube
externalAccess:
type: publicIP
ips:
- '10.0.0.1'
- '10.0.0.2'
- '10.0.0.3'
ports:
httpPort: 80
httpsPort: 443
mqttPort: 1883
mqttSecurePort: 8883
services:
zookeeper:
clusterSize: 3
postgres:
clusterSize: 3
mongodb:
replicas: 2
kafka:
clusterSize: 3
auth:
emailHost: 'smtp.gmail.com'
emailUser: 'test@test.com'
emailPassword: 'password'
|
From line 5 to 14, we have Ceph configuration parameters. The cephMonitors
attribute specifies how many monitors are going to be used and by which address
they can be accessed. For more information about this element, check ceph
monitors documentation.
cephAdminId
, cephAdminKey
, cephUserId
and cephUserKey
attributes refers to user information. These values are set/generated in user
creation.
In externalAccess
section we have what addresses and ports should be
exposed for external access. In services
section, we can configure how many
replicas we want to each service and a few other parameters to configure that
service (for instance, auth taks an emailHost
and emailUser
parameters).
To configure and start the kubernetes cluster, just install all python requirements and start the deploy.py script:
pip install -r ./requirements.txt
python ./deploy.py