Conector Local - Instalação e Atualização
Passo a passo dos Procedimentos para Instalação do Conector
1. Pré-Instalação
1.1. Solicite as credenciais para uso do serviço
a. Credenciais para uso do RAP: i. Login; ii. Senha; iii. Client ID - ID que identifica unicamente cada instituição; iv. URL do ambiente de homologação. b. Credenciais para acesso ao registro de imagens privados do Serviço: i. Login; ii. Senha;
1.2. Cadastro e Configuração de Certificados Digitais
a. Envie os certificados com chave pública que serão utilizados no teste para RNP: i. Podem ser exportados a partir dos containers A1 (arquivo.pfx) ou A3 (token criptográfico) para o formato .cer via ferramenta RAPSign; ii. Caso ainda não tenha certificado, solicite à RNP certificados exemplares. Nesse caso, eles já serão cadastrados no sistema antes do envio; iii. Recomendamos o uso de pelo menos dois certificados para simular o processo. Um para simular a pessoa jurídica da instituição e outro para simular uma pessoa física;
1.3. Requisitos para Infraestrutura recomendada para instalação do Conector
Serão executados, nesse ambiente, um par de imagens Docker (uma com o conector e outra com o banco de dados) além de um volume para armazenar o banco. A configuração mínima é uma Máquina virtual básica com uma CPU e 2Gb de RAM. É recomendado 2 vCPU e 4 Gb de RAM para um processamento mais fluido.
Apesar do Docker virtualizar também para outros sistemas operacionais é fortemente recomendado que a imagem seja utilizada no Sistema Operacional Linux, mais especificamente nas distribuições Ubuntu ou Debian. Isso é necessário para evitar problemas de configurações que diferem de um sistema para outro, principalmente, configurações de rede.
1.4. Requisitos para instalação do Container
a. Para o deploy deste projeto, é necessário ter instalado algumas ferramentas de conteinerização: i. Para instalação do Docker Engine execute os seguintes comandos:
ii. Para instalação do Docker Compose execute os seguintes comandos:
2. Instalação
2.1 Edite o arquivo docker-compose.api.yml**
a. Adicione as credenciais para acesso ao Serviço de Diplomas: i. Login (RAP_API_USER_EMAIL); ii. Senha (RAP_API_USER_PASS); iii. Client ID (INSTITUTION_ID). iv. *As variáveis de configuração do RAP Sign WEB também serão configuradas no mesmo arquivo docker-compose. Verifique manual próprio da aplicação
b. Realize login no registro privado de imagens do ambiente de homologação:
c. Execute o script do docker-compose para: i. Download da imagem atualizada do Conector; ii. Configuração automática do banco (criação e execução dos scripts para migração de tabelas); iii. Inicialização dos daemons de processamento de documentos e APIs de Comunicação;
iv. Opcionalmente efetue logoff do serviço de registro de imagens;
Obs.: Caso o conector na primeira execução apresentar problema de conexão com o banco, reinicie o mesmo.
Vídeo demonstrativo da Instalação e Configuração dos Componentes Locais:
3. Procedimentos de Instalação
Procedimentos para instalação e integração via API de Comunicação
Acessar o serviço de registro de imagens (URL temporária do ambiente de homologação. A URL para configuração do ambiente de produção é enviada para instituição junto com as credenciais do ambiente de produção no início da operação do serviço).
2. Inserir credenciais para acesso ao serviço registro privado de imagens docker do Conector local;
3. Instalar o docker-compose4;
4. Configurar as variáveis de ambiente no arquivo docker-compose.api.yml para acesso ao banco de dados, serviço RAP, bem como variáveis adicionais (ver Seção 5);
5. Iniciar o Conector local. É possível indicar a opção -d para que o serviço rode em background;
6. (Opcional) Após a configuração e execução do docker-compose é possível remover as informações de login ao repositório privado de imagens com o comando. Caso seja necessário no futuro atualizar a imagem do Conector, o processo de login deverá ser feito novamente.
3 https://www.iti.gov.br/legislacao/documentos-principais
4 https://docs.docker.com/compose/install/
OBSERVAÇÃO: Na primeira execução, as ações de configuração do banco de dados serão executadas pelo próprio Conector, sendo necessário apenas configurar as informações referentes ao nome do banco e credenciais que serão usados. O banco de dados utilizado é o PostgresSQL.
4. Atualização do Conector
Para verificar a existência de atualizações no Conector deve-se executar o seguinte comando utilizando o docker-compose*:
Caso exista a versão mais recente do Conector, esta será baixada automaticamente. Após isso, basta reiniciar os containers.
Vide Release Note do Conector Local.
4.1 Como localizar o log completo do conector.
Para localizar o log completo do conector deve-se executar o seguinte comando:
sudo docker cp <container_id>:/var/log
5. Procedimentos de Configuração
O Conector Local possui algumas variáveis configuráveis.
Essas variáveis são passadas para container do Conector Local por meio de arquivo de configuração docker-compose.api.yml.
A descrição de cada variável de ambiente é dada no próprio arquivo.
6. Documentação da API
Toda a comunicação entre o Sistema da Instituição e o Conector Local é feito via API de Comunicação.
A documentação da API de Comunicação pode ser acessada e testada em tempo real via swagger no próprio Conector Local na URL: http://<IP-DO-CONECTOR>:<PORTAS>/docs. A porta padrão para a API de comunicação e para acesso a documentação é a 80. Ela pode ser alterada no arquivo de configuração do docker-compose. Outra forma de acessar a documentação da API de Comunicação é a partir do arquivo openapi.json**
Esse arquivo pode ser renderizado em qualquer visualizador de documentação swagger, a exemplo do Swagger Editor. Além da documentação do Swagger, também é disponibilizada às instituições documentação para uso com o Postman:
Vide arquivo Conector API Environment.postman_environment.json**
Vide arquivo RAP Conector.postman_collection.json**
**Os arquivos referenciados são disponibilizados para as Instituições que aderiram ao Serviço e que estão em processo de implantação.
7. Procedimentos para Operação
Inicialização do Processo de Gestão do Diploma
Para o início do processo de geração as seguintes ações devem ser realizadas:
● XML da Documentação Acadêmica:
Montagem dos metadados a partir do preenchimento do JSON específico;
Inserção do JSON no Conector via API;
Indicação do código 4 para tratamento de Documentação Acadêmica;
● XML do Histórico Escolar Final:
Montagem dos metadados a partir do preenchimento do JSON específico;
Inserção do JSON no Conector via API;
Indicação do código 3 para tratamento do Histórico Escolar Final;
● XML do Diploma Digital:
Montagem dos metadados a partir do preenchimento do JSON específico;
Inserção do JSON no Conector via API;
Indicação do código 2 para tratamento do Diploma Digital;
● Tratamento da versão PDF/A da Representação Visual:
Montagem dos metadados a partir do preenchimento do JSON específico;
Inserção do JSON no Conector via API;
Indicação do código 5 para tratamento da Representação Visual;
Envio do arquivo no formato PDF/A que será processado;
O processo de tratamento da Representação Visual converte verifica se a representação visual está no formato de preservação PDF/A. Caso não esteja, o Conector tentará convertê-lo. Caso a conversão seja bem sucedida, o processo de registro do referido documento no Serviço RAP será realizado.
No presente momento todas as demais ações necessárias para geração da representação visual do diploma (layout e aposição de estruturas visuais) são de responsabilidade da instituição;
7.1 Ordem de Processamento
Para o caso dos documentos associados ao Diploma Digital, uma vez que esses dados possuem interdependência, os documentos devem ser processados na seguinte ordem:
XML da Documentação Acadêmica;
a. Geração, Assinatura
XML do Histórico Escolar Final;
a. Geração, Assinatura
XML do Diploma Digital;
a. Geração, Assinatura
PDF da Representação Visual (assinatura digital é dispensada);
a. Geração
Vale reforçar, que um documento subsequente, só deve ser enviado para processamento após a finalização completa do anterior, ou seja, após concluída a fase de registro.
8. Segurança e Estratégias de Backup
8.1 Autenticação na API do Conector com token JWT
No arquivo docker-compose existe uma flag RAP_USE_JWT_AUTHORIZATION que permite ativar a obrigatoriedade de autenticação com tokens JWT para uso das rotas do Conector.
O token pode ser obtido através da rota POST /users/auth e as credenciais são as mesmas que a instituição usa para configurar o Conector. O token tem duração de 15 minutos, mas é recomendado fazer o gerenciamento da expiração através da variável "exp" do token JWT decodificado (https://jwt.io/). Para atualização do token existe uma rota denominada POST /users/auth/refresh que permite a aquisição de um novo token JWT a partir do envio do refresh token.
8.2 Arquitetura e Estratégias de Firewall
A partir da versão 0.3.7 do RAP Sign WEB houve uma alteração da arquitetura dos componentes locais do serviço. O RAP Sign WEB possui agora um componente de front-end e um componente de back-end. O componente de back-end é o que de fato se comunica com a API do conector. Com essa arquitetura é possível isolar o conector na infraestrutura da instituição, sem a necessidade de expor suas rotas para acesso público.
A única aplicação que precisa ficar pública é o RAP Sign Web. Desta forma, recomenda-se limitar o acesso da API conector apenas para a aplicação RAP Sign Web e para as aplicações internas da instituição como forma de aumentar a segurança sobre a solução.
8.3 Estratégias de Backup
Para garantir a consistência, histórico dos documentos e funcionamento correto do serviço é necessário manter o banco de dados de integração do Conector íntegro. Sendo assim, é recomendado que as instituições utilizem estratégias de backup regulares para esse banco de integração.
Abaixo um exemplo de comando que pode ser utilizado para realizar o backup do banco de dados.
Recomenda-se também trabalhar com uma estratégia de backup do volume onde os arquivos do relacionados aos arquivos da documentação acadêmica, diplomas e representação visual se encontram. Para tanto recomenda-se o uso de redundância e sincronização periódica dos arquivos. É preciso observar a manutenção da coerência dos paths dos arquivos a partir do diretório base para que o Conector consiga acessar de forma correta todos os arquivos em caso de uma restauração de arquivos seja necessária.
Com relação às políticas e frequências de backup de banco e volume de arquivos, as instituições devem observar as melhores práticas para esse tipo de ação e aplicar/desenvolver estratégias nesse sentido que se encaixe aos requisitos de segurança trabalhados na instituição.
8.4 Execução dos serviços Docker
Recomenda-se apenas a execução de uma cópia do serviço Conector, dada a forma como os daemons internos trabalham. A execução de múltiplas cópias da aplicação pode gerar problemas de inconsistência dos dados.
Os serviços descritos no docker-compose não possuem mecanismo de reinicialização automática. Caso a máquina host seja reiniciada, estes devem ser manualmente reiniciados também. É possível, contudo, que a instituição configure via docker-compose políticas de reinicialização.
Last updated
