Merge pull request #105 from lappis-unb/gitbook

Reorganizes files in docs dir, and add git book configuration

.gitbook.yaml

@@ -0,0 +1,4 @@
+root: ./docs/
+
+structure:
+  readme: README.md

docs/README.md

@@ -0,0 +1,240 @@
+# Rasa Boilerplate
+<!-- badges -->
+<a href="https://www.gnu.org/licenses/gpl-3.0.pt-br.html"><img src="https://img.shields.io/badge/licence-GPL3-green.svg"/></a>
+<a href="https://codeclimate.com/github/lappis-unb/rasa-ptbr-boilerplate/maintainability"><img src="https://api.codeclimate.com/v1/badges/3fe22bf52000e147c6df/maintainability"/></a>
+
+## Tutorial para configurar todo o projeto
+
+Para ter seu chatbot Rasa no ar e funcionando rápidamente no `shell` execute os seguintes comandos:
+
+```sh
+sudo make build-bot
+sudo make train
+sudo make run-console
+```
+
+Estes comandos irão construir o seu chatbot e abrir a conversação no terminal. Tudo está dockerizado
+então você não terá problemas de instalação do ambiente.
+
+## Introdução
+
+### For English version, see [README-en](docs/README-en.md)
+
+Um projeto feito em Rasa com configurações necessárias para a construção de um projeto grande de chatbot.
+
+Este projeto teve como base o projeto [Tais](http://github.com/lappis-unb/tais).
+
+### Entenda a Arquitetura
+
+É utilizado no boilerplate diversas tecnologias que interagem entre si para obter um melhor resultado. Veja a arquitetura implementada:
+
+![](https://user-images.githubusercontent.com/8556291/57933140-d8d66b80-7892-11e9-8d58-a7eda60b099b.png)
+
+O usuário interage com a Boilerplate via RocketChat ou Telegram, que manda as mensagens para o Rasa NLU através de
+conectores, onde ele identifica a *intent*, e responde pelo Rasa Core, de acordo com as *stories* e *actions*.  
+As *models* utilizadas para a conversação foram geradas pelo módulo *trainer* e depois transferidas para o bot, estes
+modelos podem ser versionados e evoluídos entre bots.  
+Os notebooks avaliam o funcionamento de acordo com o formato das *intents* e *stories*.
+O elasticsearch coleta os dados da conversa e armazena para a análise feita pelo kibana, que gera gráficos para
+avaliação das conversas dos usuários e do boilerplate.
+
+### Bot
+
+Este script foi configurado para construir as imagens genéricas necessárias para execução deste ambiente.
+Caso seu projeto utilize este boilerplate e vá realizar uma integração contínua ou similar, é interessante
+criar um repositório para as imagens e substitua os nomes das imagens "lappis/bot", e "lappis/botrequirements" pelas suas respectivas novas imagens, por exemplo "<organização>/bot" em repositório público.
+
+
+### Treinamento
+
+**Atenção**: o comando de treinamento é usado para criar os modelos necessários na conversação do bot para treinar o seu chatbot execute o comando:
+```sh
+sudo make train
+```
+
+### Console
+
+```sh
+sudo make run-console
+```
+
+### Telegram
+
+Após realizar o [tutorial](/docs/setup_telegram.md) de exportação de todas variávies de ambiente necessárias, é possível realizar a execução do bot no telegram corretamente.
+
+**Antes de seguir adiante. Importante:** As variáveis de ambiente são necessárias para o correto funcionamento do bot, por isso não esqueça de exportá-las.
+
+Se ainda não tiver treinado seu bot execute antes:
+
+
+Depois execute o bot no telegram:
+
+```sh
+sudo docker-compose up bot_telegram
+```
+### Analytics
+
+Para a visualização dos dados da interação entre o usuário e o chatbot nós utilizamos uma parte da Stack do Elastic, composta pelo ElasticSearch e o Kibana. Com isso, utilizamos um broker para fazer a gerência de mensagens. Então conseguimos adicionar mensagens ao ElasticSearch independente do tipo de mensageiro que estamos utilizando.
+
+### Configuração do RabbitMQ
+
+Em primeiro lugar para fazer o setup do analytics é necessário subir o RabiitMQ e suas configurações.
+
+Inicie o serviço do servidor do RabbitMQ:
+
+```sh
+sudo docker-compose up -d rabbitmq
+```
+
+Inicie o serviço do consumidor do RabbitMQ, que ficará responsável por enviar as mensagens para o ElasticSearch:
+
+```sh
+sudo docker-compose up -d rabbitmq-consumer
+```
+
+Lembre-se de configurar as seguintes variáveis de ambiente do serviço `rabbitmq-consumer` no `docker-compose`.
+
+```sh
+ENVIRONMENT_NAME=localhost
+BOT_VERSION=last-commit-hash
+RABBITMQ_DEFAULT_USER=admin
+RABBITMQ_DEFAULT_PASS=admin
+```
+
+Sendo que as configurações de `RABBITMQ_DEFAULT_USER` e `RABBITMQ_DEFAULT_PASS` devem ser as mesmas definidas no serviço do `rabbitmq`.
+
+#### Integração com Rasa
+
+Existem duas formas para executar a Tais com o *broker*. A primeira delas é via linha de comando.
+Para utilizar esta forma é preciso definir Dentro do arquivo `endpoints.yml` as configurações do broker:
+
+```yml
+event_broker:
+  url: rabbitmq
+  username: admin
+  password: admin
+  queue: bot_messages
+```
+
+Depois basta executar o bot:
+
+```sh
+sudo docker-compose run --rm bot make run-console-broker
+```
+
+A segunda forma é utilizando o script `run-rocketchat` que é utilizado quando o bot é executado com o RocketChat como canal. Para isso, as mesmas variáveis devem ser configuradas no arquivo `docker/bot/bot.env`.
+Lembre-se também de configurar como `True` a seguinte variável do serviço `bot` no arquivo `docker/bot-rocketchat.env`.
+
+```
+# Broker config
+BROKER_URL=rabbitmq
+BROKER_USERNAME=admin
+BROKER_PASSWORD=admin
+QUEUE_NAME=bot_messages
+```
+
+Ao final é necessário buildar novamente o container do bot.
+
+```
+sudo docker-compose up --build -d bot
+```
+
+### Configuração ElasticSearch
+
+O ElasticSearch é o serviço responsável por armazenar os dados provenientes da interação entre o usuário e o chatbot.
+
+As mensagens são inseridas no índice do ElasticSearch utilizando o *broker* RabbitMQ.
+
+Para subir o ambiente do ElasticSearch rode os seguintes comandos:
+
+```
+sudo docker-compose up -d elasticsearch
+sudo docker-compose run --rm -v $PWD/analytics:/analytics bot python /analytics/setup_elastic.py
+```
+
+Lembre-se de setar as seguintes variaveis de ambiente no `docker-compose`.
+
+```
+ENVIRONMENT_NAME=localhost
+BOT_VERSION=last-commit-hash
+```
+
+#### Setup Kibana (Visualização)
+
+Para a análise dos dados das conversas com o usuário, utilize o kibana, e veja como os usuários estão interagindo com o bot, os principais assuntos, média de usuários e outras informações da análise de dados.
+
+O Kibana nos auxilia com uma interface para criação de visualização para os dados armazenados nos índices do ElasticSearch.
+
+```sh
+sudo docker-compose up -d kibana
+```
+
+**Atenção:** Caso queira configurar permissões diferentes de usuários (Login) no ElasticSearch/Kibana, siga esse tutorial ([link](https://github.com/lappis-unb/rasa-ptbr-boilerplate/tree/master/docs/setup_user_elasticsearch.md)).
+
+#### Importação de dashboards
+
+Caso queira subir com os dashboards que criamos para fazer o monitoramento de bots:
+
+```
+sudo docker-compose run --rm kibana python3.6 import_dashboards.py
+```
+
+Após rodar o comando anterior os dashboards importados estarão presentes no menu management/kibana/Saved Objects.
+
+Você pode acessar o kibana no `locahost:5601`
+
+
+
+## Testando Fluxos de Conversa
+
+É possível testar os fluxos de conversação utilizando o [Evaluation do Rasa Core](https://github.com/lappis-unb/tais/wiki/Testes-Automatizados). Para testá-los no seu bot basta adicionar um arquivo dentro do diretório `bot/e2e/` com as histórias a serem testadas. Essas histórias devem ser descritas normalmente, porém com exemplos de frases para cada uma das *Intents* sendo testadas, segundo o formato abaixo:
+
+```
+## História de teste 1
+* cumprimentar: oi
+   - utter_cumprimentar
+* action_test: test custom action
+   - action_test
+```
+
+Uma vez que os arquivos de teste foram adicionados ao diretório correto, basta rodar os testes com a *task* do bot:
+
+```sh
+sudo docker-compose run --rm bot make test-stories
+```
+
+Para gerar data-science referente aos testes automatizados de bor, execute o seguinte comando do *Makefile* na raíz do projeto:
+
+```sh
+sudo docker-compose run --rm bot make test-dialogue
+```
+
+## Notebooks - Análise de dados
+
+### Setup
+
+Levante o container `notebooks`
+
+```sh
+docker-compose up -d notebooks
+```
+
+Acesse o notebook em `localhost:8888`
+
+# Como conseguir ajuda
+
+Parte da documentação técnica do framework da Tais está disponível na
+[wiki do repositório](https://github.com/lappis-unb/tais/wiki). Caso não encontre sua resposta, abra uma issue
+com a tag `duvida` que tentaremos responder o mais rápido possível.
+
+Em caso de dúvidas em relação ao Rasa, veja o grupo [Telegram Rasa Stack Brasil](https://t.me/RasaBrasil),
+estamos lá também para ajudar.
+
+Veja mais informações de contato em nosso site: https://lappis.rocks
+
+# Licença
+
+Todo o framework do boilerplate é desenvolvido sob a licença
+[GPL3](https://github.com/lappis-unb/rasa-ptbr-boilerplate/blob/master/LICENSE)
+
+Veja a lista de dependências de licenças [aqui](https://libraries.io/github/lappis-unb/rasa-ptbr-boilerplate)

docs/Setup/setup_telegram.md

@@ -0,0 +1,54 @@
+## Setup do bot no Telegram
+
+##### Crie um bot no Telegram
+
+Converse com o [@BotFather do Telegram](https://t.me/BotFather) e crie um bot de teste unicamente seu seguindo as instruções dele.
+
+
+
+
+##### Exporte as variáveis do seu bot
+Após escolher um nome para seu bot, o @BotFather lhe dará um token para utilizar para acessar a API do Telegram. Adicione ambos no [arquivo de configurações do bot](../docker/bot-telegram.env), como a seguir. Substitua o TELEGRAM_TOKEN pelo token lhe enviado pelo @BotFather e TELEGRAM_BOT_USERNAME pelo nome do seu bot.
+
+```sh
+TELEGRAM_BOT_USERNAME=token_fornecido_pelo_BotFather
+TELEGRAM_TOKEN=username_do_bot
+```
+
+##### Execute o ngrok
+Após a etapa anterior, é necessário utilizar o [ngrok](https://ngrok.com/download) para expor determinada porta para ser utilizado
+pelo Telegram.
+
+Conforme a seguir, execute o ngrok na porta 5001.
+
+```sh
+./ngrok http 5001
+```
+
+**Atenção:** O conector do Telegram está utilizando a porta 5001 como padrão. Caso queira mudar, somente altere
+a porta utilizada pelo no Makefile.
+
+
+##### Exporte a URL do Webhook 
+
+Enquanto o ngrok estiver em execução, ele apresentará uma série de informações da sessão atual. Copie a url do campo Forwarding com o protocolo HTTPS e cole no [arquivo de configurações do bot](../docker/bot-telegram.env). ela será similar à seguinte.
+
+```sh
+TELEGRAM_WEBHOOK=link_do_ngrok/webhooks/telegram/webhook
+```
+
+::Lembre-se::: sempre que executar o ngrok essa url deve ser exportada.
+
+
+##### Execução do bot no telegram
+
+Ao final de realizar essas configurações, seu [arquivo de configurações do bot](../docker/bot-telegram.env) deve estar de acordo com o exibido logo abaixo:
+
+```sh
+TELEGRAM_BOT_USERNAME=lappisbot
+TELEGRAM_TOKEN=token
+TELEGRAM_WEBHOOK=your_webhook_server/webhooks/telegram/webhook
+```
+
+Com isso, é possível realizar a execução do bot seguindo os passos do [README](../README.md)
+

docs/Tutoriais/setup_user_elasticsearch.md

@@ -0,0 +1,74 @@
+# Configurando os usuários
+
+Caso seja desejada a função de se ter usuários com diferentes permissões dentro do kibana, deve-se seguir os seguintes passos (Caso não seja esse seu interesse, pode passar para a próxima sessão):   
+
+OBS: Os seguintes passos podem ser encontrados, com mais detalhes, na seguinte paǵina: https://www.elastic.co/guide/en/elastic-stack-overview/current/get-started-enable-security.html
+
+**1. Habilitar função de segurança do elastic search:**
+
+   Depois de se subir o container do elastic de acordo com a seção [Setup](https://github.com/lappis-unb/rasa-ptbr-boilerplate/tree/master#setup-elasticsearch),
+   adicione a seguinte linha ao arquivo 'rasa-ptbr-boilerplate/elasticsearch/elasticsearch.yml':
+
+```
+xpack.security.enabled: true
+```
+
+Após adicionar a linha, reinicie o container do Elastic Search
+
+```
+sudo docker-compose restart elasticsearch
+```
+
+
+**2. Definir senhas para usuários internos do elasticsearch:**
+
+ Entre no container com o comando:
+
+
+```
+sudo docker-compose exec elasticsearch bash
+```
+
+   Dentro do container execute o seguinte comando, preenchendo as senhas que deseja para cada um dos usuários.
+
+
+```
+./bin/elasticsearch-setup-passwords interactive
+```
+
+**3. Adicionar usuário kibana ao container do kibana**
+
+   Depois de subir o container do kibana de acordo com a seção [Visualização](https://github.com/lappis-unb/rasa-ptbr-boilerplate/tree/master#setup-kibana-visualização), entre no mesmo com o comando:
+
+```
+sudo docker-compose exec kibana bash
+```
+
+   Dentro do container, execute os seguintes comandos, digitando, quando necessário, o usuário kibana, e a senha criada no passo anterior.
+
+```
+../bin/kibana-keystore create
+../bin/kibana-keystore add elasticsearch.username
+../bin/kibana-keystore add elasticsearch.password
+```
+
+Após executar os comandos acima, reinicie o container do kibana.
+
+```
+sudo docker-compose restart kibana
+```
+
+
+**4. Crie usuários além do administrador**
+
+   Após os três passos anteriores, será possível entrar no kibana utilizando a conta com usuário 'elastic'.
+
+   Na interface, é possível criar outros usuários, com diversas outras permissões, entrando em ***Management / Security / Users***, e após isso clicando no botão Create New User.
+
+**5. Definir permissões para usuários.**
+
+   Na criação de usuários é possível se definir permissões para cada um deles, utilizando os ***roles*** definidos pelo elastic.
+
+   Por exemplo, um usuário que deva ter somente aceesso a leitura dos dashboards criados, deverá ter o role ***kibana_dashboard_only_user*** e ***apm_user***
+
+   É possível criar novos ***roles*** em ***Management / Security / Roles***