Configuração do Engine

Este documento detalha as configurações do servidor Engine. Para uma explicação mais geral de como instalar o sistema consulte o manual Instalação do sistema. Para instalar um servidor Engine adicional em uma base de dados já configurada, siga as instruções da página https://endereco-do-servidor/install.

A configuração do Engine pode ser realizada na interface de configuração web Manage, via parâmetros de linha de comando ou por meio de variáveis de ambiente definidas no sistema operacional. As configurações realizadas na interface Manage ou via parâmetros de linha de comando se aplicam a uma instalação específica do Engine. Já as realizadas via variáveis de ambiente se aplicam a todos os Engines executados no contexto dessa configuração.

A interface Manage pode ser acessada remotamente utilizando o endereço do Engine utilizando a URL “http://endereco:porta/manage”. Alterações nos parâmetros de linha de comando ou variáveis de ambiente requerem acesso direto ao sistema operacional onde o Engine está sendo executado.

Modos de execução

O Engine pode ser configurado como servidor de aplicação, onde ele se conecta diretamente ao SGBD, ou como servidor de borda, onde ele se conecta a um outro Engine servidor de aplicação para ter acesso ao SGBD.

Engines instalados na mesma rede do SGBD ou que tenham uma conexão de alta performance e baixa latência com o SGBD devem ser preferencialmente configurados como servidores de aplicação. O acesso direto ao SGBD diminui a quantidade de pontos de falha e eliminam o custo de rede e serialização de dados do acesso intermediado.

O Engine deve ser configurado como servidor de borda quando não for viável o acesso direto ao SGBD ou quando o Engine for instalado em filiais ou unidades de negócio com o objetivo de diminuir a latência de conexão de rede dos navegadores ao servidor ou como estratégia de distribuição da carga de processamento.

Configurando o Engine como servidor de aplicação

Para conectar o Engine ao SGBD, é necessário instalar a biblioteca cliente de conexão com o banco, disponível no site do fornecedor do SGBD, exceto para o PostgreSQL, para o qual o Engine já inclui a biblioteca como uma das suas dependências. No manual Bancos de dados são descritas as configurações específicas para cada banco de dados.

É recomendado que os Engines usados como servidor de aplicação sejam instalados como serviços do sistema operacional, garantindo que eles sejam inicializados de forma automática, sem a necessidade de intervenção humana após o reinício do servidor.

Configurando o Engine como servidor de borda

Para configurar o Engine como servidor de borda devem ser informados como parâmetros de linha de comando o endereço do servidor de aplicação ao qual ele deve ser conectar e o nome da base de dados, conforme exemplo abaixo:

engine64.exe https://endereco_do_servidor NOME_BASE

No Windows, essa configuração deve ser informada ao registrar o sistema como serviço ou no atalho criado para iniciar a aplicação, caso o Engine seja utilizado como aplicação desktop. A instalação e configuração do Engine como aplicativo cliente também pode ser realizada pelo instalador do sistema, iniciado automaticamente quando o Engine é executado no Windows sem informar os parâmetros de configuração. Mais detalhes da configuração do Engine como aplicativo cliente podem ser obtidas na página de instalação do sistema /install.

Parâmetros de comando de linha

Os parâmetros de linha de comando em geral são informados por meio de flags descritivas prefixadas com dois hifens. Os mais utilizados também possuem uma versão curta com apenas um hífen.

Os parâmetros do endereço do servidor e o nome da base de dados, requeridos para a configuração do Engine cliente ou como servidor de borda, têm um tratamento diferenciado e não são prefixados por flags ou hifens. Eles preferencialmente devem ser informados antes dos demais parâmetros, conforme exemplo abaixo:

engine64.exe https://example.com DATABASE_NAME -nu --NoProxy

Abaixo são relacionadas os parâmetros de linha de comando do Engine:

• -nu, --DisableAutomaticUpgrade: desabilita a atualização automática de versão do executável.
• -s, --Server: O Engine será executado em modo servidor. O acesso a IDE não é disponibilizado, e o navegador não é aberto automaticamente.
• -lavfsc, --LoadiVfsLobTable: a Tabela iVfsLob é descarregada para o Cache Local. Por padrão os registros da tabela iVfsLob são carregados sob demanda. Quando esta opção está ativa, o Engine passa a carregar integralmente essa tabela na inicialização do cache local e desativa o modo de leitura sob demanda. Ativar essa opção pode penalizar significativamente a inicialização do Engine, devendo ser usada em casos onde é necessário ter acesso a todos os arquivos da VFS, como as imagens de produtos, mesmo que o Engine esteja off-line.
• -aac, --AllowAnonymousConnections: o Engine permitirá conexões remotas sem autenticação.
• -safemode, --SafeMode: o Engine carregará apenas algumas tabelas essenciais,
  possibilitando ao administrador do sistema reparar erros de configuração que impeçam a inicialização do sistema.
• -kiosk, --KioskMode: o navegador é aberto em modo kiosk.
• -ncc, --NoCheckCertificate: não serão validados os certificados SSL dos servidores. É recomendado o seu uso apenas em ambiente de desenvolvimento.
• -dar, --DisableAutoRestart: o processo do Engine não poderá ser reiniciado automaticamente. Essa opção é útil no cenário onde o Engine está sendo executado e controlado a partir de um outro processo. Caso o Engine seja iniciado com essa opção e ele detecte que há uma nova versão no servidor, ele finalizará o processo com o código de erro 4, cabendo ao processo controlador invocar novamente o Engine para que ele possa concluir a atualização. Chamadas a API server.restart() não reiniciarão o Engine.
• --DisableGui: desabilita a interface gráfica do Engine, inibindo a exibição da tela de progresso da inicialização do cache local, o ícone da área de notificações e a abertura do navegador web. Essa opção é útil em cenários onde outros processos controlam a inicialização e finalização do Engine.
• --DisableIdoSyncToDisk: desativa a operação de flush dos buffers de escrita dos arquivos dos bancos de dados locais do Engine a cada transação, tornando as operações em disco mais rápidas em detrimento de um maior risco de perda de dados nos desligamentos forçados do Engine. Ela também pode ser desativada informando a variável de ambiente NGIN_SYNC_TO_DISK com os valores “0” ou “OFF”, ou por meio da configuração SyncToDisk na página “Configuration > Others” do Manage.
• --CloseAfterDBCacheSync: após a sincronização inicial do Cache Local, o processo do Engine é automaticamente encerrado. Caso falhe a sincronização, o processo retornará o código de erro 6 ou 7.
• --HttpPort=<port>: configura a porta HTTP que deve ser aberta pelo Engine. Caso não seja possível abrir a porta indicada, o Engine será encerrado com o código de erro 5.
• --jazArchive=<path>: configura o caminho de um arquivo JAZ no sistema de arquivos da máquina que deve ser carregado na UFS. Essa opção somente será considerada se a base de dados permitir configurações externas da UFS. Esse parâmetro pode ser usado repetidas vezes ao se configurar múltiplos arquivos.
• --ufsDirectory=<path>: configura o caminho de um diretório do sistema de arquivos da máquina que deve ser montado na UFS. Essa opção somente será considerada se a base de dados permitir configurações externas da UFS. Esse parâmetro pode ser usado repetidas vezes ao se configurar múltiplas pastas.
• --JavaHome=<path>: configura o caminho da instalação do Java. É obrigatório o seu uso, caso seja usado o OpenJDK.
• --v8-flags="<args>": informa flags avançadas de configuração do runtime JavaScript v8. A relação de todas as flags pode ser obtida em flag-definitions.h ou pelo comando node --v8-options em um node que utilize um versão do v8 equivalente a da utilizada pelo Engine.
• --AdditionalLoggerConfig=<path>: informa um arquivo com configurações complementares para o gerador de logs do Engine.
• --EnableStandardManageAuthentication: ativa o suporte aos esquemas de autenticação Basic e Digest no login do Manage.
• --EnableHttpServerTLSV11: ativa o protocolo TLS 1.1 no servidor HTTP.
• --NoProxy: desativa o uso da configuração de proxy do sistema operacional. Essa mesma configuração pode ser alternativamente realizada através da variável de ambiente ENGINE_PROXY definida com o valor “NONE”.
• --EnableProfiler: ativa a coleta de estatísticas de desempenho das operações instrumentadas por meio da API Profiler. Essa opção também pode ser ativada informando a variável de ambiente NGIN_PROFILER com o valor DEFAULT ou 1, ou por meio da configuração “Profiler Enabled” na página “Configuration > General” do Manage.
• --EnableAutoProfiler: ativa a coleta de estatísticas de desempenho com a instrumentação automática de todos os métodos JavaScript, além das operações instrumentadas manualmente por meio da API Profiler. Essa opção também pode ser ativada informando a variável de ambiente NGIN_PROFILER com o valor AUTO ou por meio da configuração “Automatic Profiler Active” na página “Configuration > General” do Manage. Importante: o profiler automático registra a execução de todas as funções JavaScript, requerendo uma quantidade significativa de memória para controlar esses registros. Essa configuração não deve estar ativa em servidores de produção ou em servidores de testes que possuem uma quantidade de usuários simultâneos expressiva.
• --EnableCertbot: ativa a integração do Engine com o Certbot ou solução equivalente de geração automática de certificados digitais. Essa opção também pode ser ativada informando a variável de ambiente NGIN_CERTBOT_ENABLED com o valor 1. Mais detalhes da integração no manual Configuração do HTTPS no Engine.
• --appdatadir=<path>: configura o diretório onde são armazenados os arquivos de dados permanentes do Engine necessários para a execução do sistema, como o cache local, configuração do Manage, agendamento de scripts e demais arquivos de controle do sistema.
• --apptempdir=<path>: configura o diretório onde são armazenados os arquivos temporários do Engine. Importante: o conteúdo desse diretório é removido a cada inicialização Engine e não deve conter arquivos que precisam ser persistidos após o reinício do Engine.
• --applogdir=<path>: configura o diretório onde são armazenados os arquivos de logs do Engine.

Variáveis de ambiente

O Engine também pode ser configurado por meio de variáveis de ambiente definidas no sistema operacional. Elas têm a vantagem de serem aplicadas a todos os Engines executados no mesmo servidor caso tenham sido definidas de forma global para todo o sistema. Configurações realizadas por meio de variáveis de ambiente tem menor precedência que aquelas realizadas por meio de parâmetros de linha de comando ou configurações equivalentes realizadas na interface do Manage.

Abaixo são relacionadas as variáveis de ambiente que são utilizadas na configuração do Engine:

• NGIN_SYNC_TO_DISK: quando informada com os valores “0” ou “OFF”, desativa a operação de flush dos buffers de escrita dos arquivos dos bancos de dados locais do Engine a cada transação, tornando as operações em disco mais rápidas em detrimento de um maior risco de perda de dados nos desligamentos forçados do Engine.
• NGIN_PROFILER: configura a coleta de desempenho das operações instrumentadas por meio da API Profiler. Valores possíveis:
  • “0”: desativa a coleta de estatísticas.
  • “1” ou “DEFAULT”: ativa a coleta de estatísticas instrumentadas manualmente por meio da classe Profiler.
  • “AUTO”: ativa a coleta de estatísticas de desempenho com a instrumentação automática de todos os métodos JavaScript. Importante: o profiler automático registra a execução de todas as funções JavaScript, requerendo uma quantidade significativa de memória para controlar esses registros. Essa configuração não deve estar ativa em servidores de produção ou em servidores de testes que possuem uma quantidade de usuários simultâneos expressiva.
• NGIN_CERTBOT_ENABLED: quando informada com o valor “1”, ativa a integração do Engine com o Certbot ou solução equivalente de geração automática de certificados digitais. Mais detalhes da integração no manual Configuração do HTTPS no Engine.
• NGIN_V8_DEFAULT: quando informado com o valor “1”, determina que o Engine deve utilizar o runtime JavaScript V8 em vez do Ije como padrão.
• NGIN_APP_DATA_DIR: configura o diretório onde são armazenados os arquivos de dados permanentes do Engine necessários para a execução do sistema, como o cache local, configuração do Manage, agendamento de scripts e demais arquivos de controle do sistema.
• NGIN_APP_TEMP_DIR: configura o diretório onde são armazenados os arquivos temporários do Engine. Importante: o conteúdo desse diretório é removido a cada inicialização Engine e não deve conter arquivos que precisam ser persistidos após o reinício do Engine.
• NGIN_APP_LOG_DIR: configura o diretório onde são armazenados os arquivos de logs do Engine.
• NGIN_JAVA_HOME e JAVA_HOME: diretório de instalação do Java que deve ser utilizado pelo Engine. Mais detalhes em Integração com o Java.

Modificação de bibliotecas Open Source

O Engine utiliza a versão LGPL do Framework Qt, sendo assim permitido aos seus usuários o acesso ao seu código fonte, assim como a possibilidade de o modificar, se assim desejarem, e usar a versão alterada no Engine desde que sua Application Binary Interface não tenha sido alterada. Para que o Engine não substitua a versão modificada das bibliotecas pela versão distribuída na instalação, é necessário acrescentar nos parâmetros do seu atalho o argumento -nu. É importante ressaltar que o suporte padrão não dá cobertura para o uso do Engine com versões não homologadas de suas bibliotecas.