Instrucciones de instalación local

Este documento describe el proceso de instalación de axe DevTools en una ubicación local.

Requisitos

Antes de intentar instalar axe, asegúrese de que se cumplan los siguientes requisitos.

Sistema Operativo

Axe está diseñado para ejecutarse en RHEL7 o RHEL8. Actualmente no se admiten otros sistemas operativos.

Antes de instalar axe, se espera que su sistema haya sido actualizado mediante:

yum update -y

Requisitos de Hardware

Nuestras pruebas de carga han demostrado que un AWS t2.micro es capaz de soportar una pequeña base de usuarios (unos 25 usuarios) sin cargar significativamente la aplicación. No recomendamos desplegar axe en un servidor que no tenga especificaciones equivalentes a un t2.micro.

Si tiene una base de usuarios más grande, consulte la tabla a continuación para recomendaciones.

En cualquier tamaño de máquina, se requiere un mínimo de 15 GB de almacenamiento físico (espacio en disco). Recomendamos más de 30 GB, sin embargo.

Requisitos de Red

Actualmente axe no necesita acceso a la red saliente, aparte de responder a las solicitudes que se le hagan.

Axe abrirá los siguientes puertos en el sistema al que se despliegue:

Si planeas ejecutar PostgreSQL en la misma máquina que axe, se abrirá su puerto estándar (5432), pero no es accesible desde Internet exterior.

Requisitos de DNS

Se debe crear un DNS para axe. Este DNS puede estar detrás del firewall de tu empresa, en tu propia red privada, o ser accesible desde Internet pública. Para nuestro servidor axe privado, tenemos un registro A apuntando a una instancia EC2 en nuestra cuenta de AWS.

El DNS de ejemplo utilizado en este documento es axe.mycompany.com.

Configuración de SELinux

Axe requiere que se desactive un único indicador de SELinux:

setsebool -P httpd_can_network_connect 1

Esto permite que NGINX actúe como un proxy inverso y responda a solicitudes de red salientes.

Usuarios

Se espera que el instalador se ejecute como el usuario root. Si no puedes sudo su al usuario root, el instalador fallará.

El instalador creará los siguientes usuarios:

Ninguno de estos usuarios necesita permisos elevados.

Dependencias

El instalador de axe incluye todas sus dependencias. El servidor axe está instalado para no necesitar acceso a Internet exterior para que axe funcione.

Un despliegue de axe tiene dependencias cruciales en el siguiente software:

• NGINX - Expone los servidores axe a tu red
• PostgreSQL - Almacenamiento de datos

El servidor axe se ejecuta a través de Node.js, pero no es necesario que Node esté instalado en el sistema.

NGINX

NGINX debe ser instalado/configurado para reenviar tráfico al servidor axe. Se ha proporcionado un ejemplo de configuración para NGINX (ver axe-nginx-example.conf).

Los RPM necesarios para instalar NGINX están incluidos en el instalador de axe. Para instalar NGINX, haz lo siguiente:

# 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

El servidor axe utiliza PostgreSQL para el almacenamiento de datos. Debe proporcionarse una conexión válida a PostgreSQL al instalador.

Axe soporta tanto un PostgreSQL externo (por ejemplo, un RDS alojado por AWS), como un servidor PostgreSQL que se ejecute en la misma máquina.

Los RPM necesarios para instalar PostgreSQL están incluidos en el instalador de axe. Para instalar PostgreSQL, haz lo siguiente:

# 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

Ejecución del Instalador

El instalador debe ejecutarse como el usuario root. Verifica que eres el usuario root ejecutando:

whoami

Si has extraído previamente el instalador, asegúrate de limpiar el directorio migrations:

rm -f installer/migrations/*.sql

El instalador se entregará como un único archivo (archivo comprimido): installer.tar.gz. Para extraer el archivo, ejecuta lo siguiente:

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

Esto resultará en una estructura similar a:

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

Una vez extraído, el siguiente paso es ejecutar el programa installer/installer.

Configuración del Instalador

Se necesitan muchas opciones de configuración para configurar el instalador. La siguiente tabla explica cada opción de la CLI que se debe pasar al programa installer.

Notas sobre las banderas de configuración

• --migration-directory debería apuntar al directorio al que se extrajo el paquete instalador más /migrations. Esto probablemente puede ser $PWD/migrations.
• --address es el DNS preconfigurado para la instalación de axe.
• --allowed-email-domains puede configurarse si su instalación de axe solo debe permitir el uso desde dominios de correo específicos (por ejemplo, *@mycompany.com).
• Por defecto, --extension-id para todos los IDs de extensión de axe conocido (incluidos Chrome y Edge).
• --database-encryption-key debe tener 32 caracteres de longitud.
• --database-encryption-iv debe tener 16 caracteres de longitud.

Variables de Entorno

Cada una de estas banderas de configuración puede establecerse mediante variables de entorno con el formato de:

AXE_DEVTOOLS_INSTALLER_{flag name}

Donde {flag name} es la variante en mayúsculas con guiones bajos del indicador de configuración. Por ejemplo, --auth-service-admin-client-id puede proporcionarse utilizando la variable de entorno AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_ADMIN_CLIENT_ID.

Además, un archivo .env en el mismo directorio de trabajo desde el cual se ejecuta el instalador será cargado, permitiendo lo siguiente:

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

Configuración de Ejemplo

Configuraciones de ejemplo para instalar axe DevTools.

Banderas de Línea 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"

Variables de Entorno (.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

Los registros se envían actualmente a stdio. Los registros se rotan según la configuración de su sistema (no determinada por axe).

Pueden recuperarse con journalctl. Por ejemplo:

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"}

Estado del Sistema

Para ver el estado completo del sistema, use systemctl:

systemctl status

Para ver el estado del servicio axe, haga lo siguiente:

systemctl status axe

Iniciar / Detener Servicios de Axe

Para iniciar/detener un servicio, use systemctl:

systemctl stop axe
systemctl start axe

Certificados TLS/SSL Autogenerados

Si se utilizan certificados TLS/SSL autogenerados, AXE_DEVTOOLS_INSTALLER_ACCEPT_SELF_SIGNED_TLS=true o el --accept-self-signed-tls=true debe estar configurado.

Aprendizaje Automático (ML)

Por defecto, las mejoras de ML de las extensiones de axe DevTools están habilitadas.

Para realizar la funcionalidad de ML, el Servidor de axe DevTools (Portal de Cuentas de axe) se comunica con el ML service que a su vez se comunica con el Sagemaker instance. Sagemaker realiza la inferencia de visión artificial que se utiliza para reducir el trabajo manual en los IGTs. El servicio de ML maneja todos los datos de imágenes que se utilizan para la inferencia y para otros propósitos - como capturas de pantalla de problemas - y almacena los datos para uso a largo plazo.

SageMaker no almacena ningún dato, por lo que se recomienda a todos los clientes que permitan que sus instancias se comuniquen con el modelo alojado centralmente. Un cliente puede solicitar que esta función se desactive. Si se hace esto, perderán acceso a las mejoras del modelo de ML en el producto que pueden ayudar a optimizar sus pruebas y automatizar tareas que de otro modo serían manuales. Las capturas de pantalla compartidas de problemas y el análisis automático de contraste de color seguirían funcionando sin SageMaker.

Las instancias privadas y locales pueden admitir funciones de ML apuntando la instancia a una instancia del servicio ML (esto podría ser compartido o no compartido) a través de la variable de entorno ML_SERVICE (la URL del servicio ML) y configurando la variable de entorno ML_SERVICE_API_KEY con una clave de API válida.

Características del Aprendizaje Automático

• Capturas de pantalla de problemas (se pueden ver en la página de compartir problemas)
• Herramienta de Revisar Contraste de Color Automáticamente
• Detección automática de rol de elemento
• Detección automática de etiqueta de entrada

Autenticación

Se requiere SSO de Deque para que los usuarios inicien sesión en la aplicación. Este servicio SSO puede compartirse entre varios productos de Deque y puede configurarse de varias maneras. Como se documentó anteriormente, hay una serie de variables de entorno AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_* que permiten que la Extensión de axe DevTools permita a los usuarios iniciar sesión en la aplicación.