Instruções de Instalação Local

Este documento descreve o processo de instalação do axe DevTools em um local no servidor local.

Requisitos

Antes de tentar instalar o axe, certifique-se de que os seguintes requisitos sejam atendidos.

Sistema Operacional

O Axe foi projetado para rodar em RHEL7 ou RHEL8. Nenhum outro sistema operacional é atualmente suportado.

Antes de instalar o axe, espera-se que seu sistema tenha sido atualizado via:

yum update -y

Requisitos de Hardware

Nossos testes de carga comprovaram que um AWS t2.micro é capaz de suportar uma base de usuários pequena (cerca de 25 usuários) sem colocar carga significativa na aplicação. Não recomendamos implantar o axe em um servidor que não possua especificações equivalentes a um t2.micro.

Se você tiver uma base de usuários maior, consulte a tabela abaixo para obter recomendações.

Em qualquer tamanho de máquina, é necessário no mínimo 15 GB de armazenamento físico (espaço em disco). No entanto, recomendamos 30+ GB.

Requisitos de Rede

Atualmente, o Axe não precisa de acesso à rede de saída, além de responder às solicitações feitas a ele.

O Axe abrirá as seguintes portas no sistema em que está implantado:

Se você planeja executar o PostgreSQL na mesma máquina que axe, sua porta padrão (5432) será aberta, mas não é acessível da Internet externa.

Requisitos de DNS

O DNS deve ser criado para axe. Este DNS pode estar atrás do firewall da sua empresa, na sua própria rede privada, ou acessível à Internet pública. Para nosso servidor axe privado, temos um A registro apontado para uma instância EC2 em nossa conta AWS.

O DNS de exemplo usado neste documento é axe.mycompany.com.

Configuração do SELinux

Axe requer que uma única flag do SELinux seja desativada:

setsebool -P httpd_can_network_connect 1

Isso permite que o NGINX atue como um proxy reverso e responda a solicitações de rede de saída.

Usuários

Espera-se que o instalador seja executado como o usuário root . Se você não puder sudo su para o usuário root , o instalador falhará.

O instalador criará os seguintes usuários:

Nenhum desses usuários precisa de permissões elevadas.

Dependências

O instalador do axe inclui todas as suas dependências. O servidor onde o axe é instalado não precisa de acesso à Internet externa para executar o axe.

Uma implantação de axe tem dependências rígidas no seguinte software:

• NGINX - Exponha os servidores axe à sua rede
• PostgreSQL - Armazenamento de dados

O servidor axe é executado via Node.js, mas o Node não precisa ser instalado no sistema.

NGINX

O NGINX precisa ser instalado/configurado para encaminhar tráfego para o servidor axe. Uma configuração de exemplo do NGINX foi fornecida (veja axe-nginx-example.conf).

Os RPMs necessários para instalar o NGINX estão incluídos no instalador axe. Para instalar o NGINX, faça:

# Install the RPM.
yum install -y ./rpms/nginx/*.rpm
# Overwrite default configuration.
cp axe-nginx-example.conf /etc/nginx/nginx.conf
# Start NGINX and ensure it runs at system startup.
systemctl start nginx
systemctl enable nginx

PostgreSQL

O servidor axe utiliza o PostgreSQL para armazenamento de dados. É necessário fornecer uma conexão válida com o PostgreSQL para o instalador.

O Axe suporta tanto um PostgreSQL externo (por exemplo, um RDS hospedado pela AWS), quanto um servidor PostgreSQL rodando na mesma máquina.

Os RPMs necessários para instalar o PostgreSQL estão incluídos no instalador axe. Para instalar o PostgreSQL, faça:

# Install the RPM.
yum install -y ./rpms/postgres/*.rpm
# Initialize PostgreSQL DB.
postgresql-14-setup initdb

# https://www.cyberciti.biz/faq/psql-fatal-ident-authentication-failed-for-user/
sed -i 's/ident/trust/g' /var/lib/pgsql/14/data/pg_hba.conf
sed -i 's/peer/trust/g' /var/lib/pgsql/14/data/pg_hba.conf

# Start PostgreSQL and ensure it runs at system startup.
systemctl start postgresql-14
systemctl enable postgresql-14

Executando o Instalador

O instalador deve ser executado como o root usuário. Verifique se você é o root usuário executando:

whoami

Se você extraiu previamente o instalador, certifique-se de limpar o diretório migrations :

rm -f installer/migrations/*.sql

O instalador será fornecido como um único arquivo (arquivo compactado): installer.tar.gz. Para extrair o arquivo compactado, execute o seguinte:

mkdir installer
tar -xvzf ./installer.tar.gz -C ./installer

Isso resultará em uma estrutura semelhante a:

.
└── installer
    ├── axe-nginx-example.conf
    ├── axe-service
    ├── installer
    ├── migrations
    │   ├── 0000-00-00-baseline.sql
    │   └── [...]
    └── rpms
        ├── nginx
        └── postgres

Uma vez extraído, o próximo passo é executar o programa installer/installer .

Configuração do Instalador

Muitas bandeiras de configuração são necessárias para configurar o instalador. A tabela a seguir explica cada bandeira CLI a ser passada para o programa installer .

Notas sobre as Flags de Configuração

• --migration-directory deve apontar para o diretório em que o arquivo tarball de instalação foi extraído, mais /migrations. Isso provavelmente pode ser $PWD/migrations.
• --address é o DNS pré-configurado para a instalação do axe.
• --allowed-email-domains _pode_ ser configurado se sua instalação do axe deve permitir o uso apenas de domínios de e-mail específicos (ex. *@mycompany.com).
• --extension-id tem como padrão todos os _conhecidos_ IDs de extensão do axe (incluindo Chrome e Edge).
• --database-encryption-key **deve** ter 32 caracteres de comprimento.
• --database-encryption-iv **deve** ter 16 caracteres de comprimento.

Variáveis de Ambiente

Cada uma dessas flags de configuração pode ser definida por variáveis de ambiente com o formato de:

AXE_DEVTOOLS_INSTALLER_{flag name}

Onde {flag name} é a variante em snake case maiúscula da flag de configuração. Por exemplo, --auth-service-admin-client-id pode ser fornecido usando a variável de ambiente AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_ADMIN_CLIENT_ID .

Além disso, um arquivo .env no mesmo diretório de trabalho de onde o instalador é executado será carregado, habilitando o seguinte:

echo 'AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_ADMIN_CLIENT_ID=my-admin-client' > .env
./installer

Exemplo de Configuração

Configurações de exemplo para instalar o axe DevTools.

Flags de Linha de Comando

./installer \
  --axe-database-name="axe" \
  --axe-database-password="secret" \
  --master-database-name="postgres" \
  --master-database-user="postgres" \
  --master-database-password="postgres" \
  --master-database-host="localhost" \
  --master-database-port="5432" \
  --database-encryption-key="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  --database-encryption-iv="bbbbbbbbbbbbbbbb" \
  --extension-id="lhdoppojpmngadmnindnejefpokejbdd" \
  --address="https://axe.mycompany.com" \
  --port="3000" \
  --cookie-secrets="foo,bar" \
  --auth-service-url="https://auth.mycompany.com" \
  --auth-service-admin-username="admin" \
  --auth-service-admin-password="SECRET" \
  --auth-service-admin-client-id="admin-cli" \
  --auth-service-axe-admin-password="SECRET" \
  --auth-service-axe-admin-username="axe-admin" \
  --auth-service-realm="axe" \
  --auth-service-public-client-id="onprem_public" \
  --auth-service-confidential-client-id="onprem_confidential" \
  --migration-directory="./migrations" \
  --ml-service-api-key="AAAAAAAAAAAAAA" \
  --ml-service-url="http://axe.mlservice.com" \
  --ml-service-timeout=50000 \
  --shared-with="users" \
  --mobile-app-url="https://some-mobile-dashboard.com" \
  --api-keys="comma,separated,list,of,service-to-service,keys" \
  --cors-domains="comma,separated,list,of,domains" \
  --billing-service-url="http://axe.billing.service.url" \
  --migrate-to-billing="true" \
  --billing-service-admins="admin1@deque.com" \
  --accept-self-signed-ssl="true" \
  --max-migration-concurrency=20 \
  --enable-audit-log="false" \
  --smtp-host="http://smtp.host" \
  --smtp-port="8125" \
  --smtp-username="user" \
  --smtp-password="password" \
  --from-email-address="noreply@mycompany.com"

Variáveis de Ambiente (.env)

AXE_DEVTOOLS_INSTALLER_AXE_DATABASE_NAME="axe"
AXE_DEVTOOLS_INSTALLER_AXE_DATABASE_PASSWORD="secret"
AXE_DEVTOOLS_INSTALLER_MASTER_DATABASE_NAME="postgres"
AXE_DEVTOOLS_INSTALLER_MASTER_DATABASE_USER="postgres"
AXE_DEVTOOLS_INSTALLER_MASTER_DATABASE_PASSWORD="postgres"
AXE_DEVTOOLS_INSTALLER_MASTER_DATABASE_HOST="localhost"
AXE_DEVTOOLS_INSTALLER_MASTER_DATABASE_PORT="5432"
AXE_DEVTOOLS_INSTALLER_DATABASE_ENCRYPTION_KEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
AXE_DEVTOOLS_INSTALLER_DATABASE_ENCRYPTION_IV="bbbbbbbbbbbbbbbb"
AXE_DEVTOOLS_INSTALLER_MIGRATION_DIRECTORY="./migrations"
AXE_DEVTOOLS_INSTALLER_AXE_USER="axe"
AXE_DEVTOOLS_INSTALLER_EXTENSION_ID="lhdoppojpmngadmnindnejefpokejbdd"
AXE_DEVTOOLS_INSTALLER_ADDRESS="https://axe.mycompany.com"
AXE_DEVTOOLS_INSTALLER_PORT="3000"
AXE_DEVTOOLS_INSTALLER_COOKIE_SECRETS="foo,bar"
AXE_DEVTOOLS_INSTALLER_ALLOWED_EMAIL_DOMAINS=""
AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_URL="https://auth.mycompany.com"
AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_REALM="axe"
AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_ADMIN_PASSWORD="secret"
AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_ADMIN_USERNAME="admin"
AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_AXE_ADMIN_USERNAME="axe-admin"
AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_AXE_ADMIN_PASSWORD="secret"
AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_PUBLIC_CLIENT_ID="onprem_public"
AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_CONFIDENTIAL_CLIENT_ID="onprem_confidential"
AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_ADMIN_CLIENT_ID="admin-cli"
AXE_DEVTOOLS_INSTALLER_ML_SERVICE_API_KEY="your-api-key"
AXE_DEVTOOLS_INSTALLER_ML_SERVICE_URL="https://axe-ml.deque.com"
AXE_DEVTOOLS_INSTALLER_ML_SERVICE_TIMEOUT="30000"
AXE_DEVTOOLS_INSTALLER_SHARED_WITH="users"
AXE_DEVTOOLS_INSTALLER_MOBILE_APP_URL="https://some-mobile-dashboard.com"
AXE_DEVTOOLS_INSTALLER_API_KEYS="comma,separated,list,of,service-to-service,keys"
AXE_DEVTOOLS_INSTALLER_CORS_DOMAINS="comma,separated,list,of,domains"
AXE_DEVTOOLS_INSTALLER_BILLING_SERVICE_URL="http://axe-billing.service.com"
AXE_DEVTOOLS_INSTALLER_MIGRATE_TO_BILLING="true"
AXE_DEVTOOLS_INSTALLER_BILLING_SERVICE_ADMINS="admin1@deque.com"
AXE_DEVTOOLS_INSTALLER_ACCEPT_SELF_SIGNED_TLS="false"
AXE_DEVTOOLS_INSTALLER_SMTP_HOST="http://smtp.host"
AXE_DEVTOOLS_INSTALLER_SMTP_PORT="8125"
AXE_DEVTOOLS_INSTALLER_SMTP_USERNAME="user"
AXE_DEVTOOLS_INSTALLER_SMTP_PASSWORD="password"
AXE_DEVTOOLS_INSTALLER_FROM_EMAIL_ADDRESS="noreply@mycompany.com"
AXE_DEVTOOLS_INSTALLER_ENABLE_AUDIT_LOG="false"

Notas

Registro de Logs

Os logs atualmente são enviados para stdio. Os logs são rotacionados com base na configuração do seu sistema (não determinado pelo axe).

Eles podem ser recuperados com journalctl. Por exemplo:

journalctl -u axe
-- Logs begin at Tue 2020-05-05 13:51:35 UTC, end at Tue 2020-05-05 14:14:34 UTC. --
May 05 13:54:45 c8df7dc28ee3 systemd[1]: Started Axe Enterprise Service.
May 05 13:54:45 c8df7dc28ee3 axe-service[766]: {"config":{"extensionURL":"https://chrome.google.com/webstore/detail/axe/lhdoppojpmngadmnindnejefpokejbdd","port":"3000","assetC
DN":"","connection":{"host":"localhost","database":"walnut","user":"walnut","password":"<redacted>"},"defaultOrganization":{"name":"Axe Organization","realm":"axe"},"keycloak"
:{"url":"https://localhost","publicClientId":"axe-public","realm":{"username":"admin","password":"<redacted>","client_id":"axe-confidential","client_secret":"<redacted>"}},"ro
leLockPrefix":"team-","trackingID":"UA-132342340-1","datadog":{"host":"localhost","port":8125,"prefix":"axepro.server."}},"level":"info","message":"Starting application"}
May 05 13:54:45 c8df7dc28ee3 axe-service[766]: {"connection":{"host":"localhost","database":"walnut","user":"walnut","password":"<redacted>"},"level":"info","message":"Connect
ing to database"}
May 05 13:54:46 c8df7dc28ee3 axe-service[766]: {"message":"Connected to database","level":"info"}
May 05 13:54:46 c8df7dc28ee3 axe-service[766]: {"port":"3000","level":"info","message":"listening"}

Status do Sistema

Para ver o status completo do sistema, use systemctl:

systemctl status

Para ver o status do serviço axe, faça:

systemctl status axe

Iniciando / Parando Serviços do Axe

Para iniciar/parar um serviço, use systemctl:

systemctl stop axe
systemctl start axe

Certificados TLS/SSL Autoassinados

Se certificados TLS/SSL autoassinados estão sendo usados, AXE_DEVTOOLS_INSTALLER_ACCEPT_SELF_SIGNED_TLS=true ou o --accept-self-signed-tls=true deve ser configurado.

Aprendizado de Máquina (AM)

Por padrão, os aprimoramentos de AM das extensões do axe DevTools estão habilitados.

Para executar a funcionalidade de AM, o Servidor do axe DevTools (Portal de Contas axe) se comunica com o ML service que por sua vez se comunica com o Sagemaker instance. O Sagemaker realiza a inferência de visão computacional que é utilizada para reduzir a quantidade de trabalho manual em IGTs. O serviço de AM lida com todos os dados de imagem usados para inferência e para outros fins - como capturas de tela de problemas - e armazena os dados para uso a longo prazo.

O SageMaker não armazena nenhum dado, e por isso é recomendado que todos os clientes permitam que suas instâncias se comuniquem com o modelo hospedado centralmente. Um cliente pode solicitar que esse recurso seja desativado. Se isso for feito, eles perderão o acesso aos aprimoramentos do modelo de AM no produto que podem ajudar a otimizar seus testes e automatizar tarefas manualmente. As capturas de tela dos problemas compartilhados e a análise de contraste de cor continuariam a funcionar sem o SageMaker.

Instâncias privadas e locais podem suportar recursos de AM apontando a instância para uma instância de serviço de AM (esta pode ser compartilhada ou não) via a variável de ambiente ML_SERVICE (a URL do serviço de AM) e configurando a variável de ambiente ML_SERVICE_API_KEY com uma chave de API válida.

Recursos de Aprendizado de Máquina

• Capturas de tela de problemas (podem ser visualizadas na página de compartilhamento de problemas)
• Ferramenta Automática de Revisão de Contraste de Cor
• Detecção automática de função de elemento
• Detecção automática de rótulo de entrada

Autenticação

O SSO Deque é necessário para que os usuários façam login na aplicação. Este serviço de SSO pode ser compartilhado entre vários produtos Deque e pode ser configurado de várias maneiras. Conforme documentado acima, existem várias AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_* variáveis de ambiente que permitem que a extensão axe DevTools permita que os usuários façam login na aplicação.