Instructions d'installation sur site

Ce document décrit le processus d'installation d'axe DevTools dans un emplacement sur site.

Prérequis

Avant de tenter d’installer axe, assurez-vous que les exigences suivantes sont respectées.

Système d'exploitation

Axe est conçu pour fonctionner sur RHEL7 ou RHEL8. Aucun autre système d'exploitation n'est actuellement pris en charge.

Avant d'installer axe, on s'attend à ce que votre système ait été mis à jour via :

yum update -y

Configuration matérielle requise

Nos tests de charge ont prouvé qu'un AWS t2.micro est capable de prendre en charge une petite base d'utilisateurs (environ 25 utilisateurs) sans exercer de charge significative sur l'application. Nous ne recommandons pas de déployer axe sur un serveur dont les spécifications ne sont pas équivalentes à celles d'un t2.micro.

Si vous disposez d'une base d'utilisateurs plus large, reportez-vous au tableau ci-dessous pour obtenir des recommandations.

Quelle que soit la taille de la machine, un minimum de 15 Go de stockage physique (espace disque) est requis. Nous recommandons cependant 30 Go ou plus.

Exigences du réseau

Axe n'a actuellement pas besoin d'accès au réseau sortant, sauf pour répondre aux demandes qui lui sont adressées.

Axe ouvrira les ports suivants sur le système sur lequel il est déployé :

Si vous prévoyez d'exécuter PostgreSQL sur la même machine qu'axe, son port standard (5432) sera ouvert, mais ne sera pas accessible depuis Internet extérieur.

Exigences DNS

Un enregistrement DNS doit être créé pour axe. Ce DNS peut se trouver derrière le pare-feu de votre entreprise, dans votre propre réseau privé ou accessible à l'Internet public. Pour notre serveur axe privé, nous avons un A enregistrement pointé vers une instance EC2 dans notre compte AWS.

L'exemple de DNS utilisé dans ce document est axe.mycompany.com.

Configuration de SELinux

Axe nécessite qu'un seul indicateur SELinux soit désactivé :

setsebool -P httpd_can_network_connect 1

Cela permet à NGINX d'agir comme un proxy inverse et de répondre aux requêtes réseau sortantes.

Utilisateurs

Le programme d'installation doit être exécuté en tant qu' root utilisateur. Si vous ne pouvez pas sudo su accéder à l' root utilisateur, le programme d'installation échouera.

Le programme d’installation créera les utilisateurs suivants :

Aucun de ces utilisateurs n’a besoin d’autorisations élevées.

Dépendances

L'installateur axe regroupe toutes ses dépendances. Le serveur axe est installé ** n'a pas besoin** d'accéder à Internet extérieur pour faire fonctionner axe.

Un déploiement d'axe a des dépendances fortes sur les logiciels suivants :

• NGINX - Expose les serveurs axe à votre réseau
• PostgreSQL - Stockage des données

Le serveur axe fonctionne via Node.js, mais Node n'a pas besoin d'être installé sur le système.

NGINX

NGINX doit être installé/configuré pour transférer le trafic vers le serveur axe. Un exemple de configuration NGINX a été fourni ( voir axe-nginx-example.conf).

Les RPM nécessaires à l'installation de NGINX sont inclus dans le programme d'installation d'axe. Pour installer NGINX, procédez comme suit :

# 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

Le serveur axe utilise PostgreSQL pour le stockage des données. Une connexion valide à PostgreSQL doit être fournie au programme d'installation.

Axe prend en charge à la fois un PostgreSQL externe (par exemple un RDS hébergé par AWS) ou un serveur PostgreSQL fonctionnant sur la même machine.

Les RPM nécessaires à l'installation de PostgreSQL sont inclus dans le programme d'installation axe DevTools. Pour installer PostgreSQL, procédez comme suit :

# 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

Lancement du programme d'installation

Le programme d'installation doit être exécuté en tant que root utilisateur. Vérifiez que vous êtes bien l' root utilisateur en exécutant :

whoami

Si vous avez déjà extrait le programme d'installation, assurez-vous d'effacer le migrations répertoire :

rm -f installer/migrations/*.sql

Le programme d'installation sera livré sous la forme d'un fichier unique (archive) : installer.tar.gz. Pour extraire l’archive, exécutez la commande suivante :

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

Cela donnera une structure similaire à :

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

Une fois extrait, l'étape suivante consiste à exécuter le installer/installer programme.

Configuration du programme d'installation

De nombreux drapeaux de configuration sont nécessaires pour configurer le programme d'installation. Le tableau suivant explique chaque indicateur CLI à transmettre au installer programme.

Notes sur le Drapeau de configuration

• --migration-directory doit pointer vers le répertoire dans lequel l'archive tar du programme d'installation a été extraite plus /migrations. Cela peut probablemente être $PWD/migrations.
• --address est le DNS préconfiguré pour l'installation d'axe.
• --allowed-email-domains peut être défini si votre installation axe doit uniquement autoriser l'utilisation à partir de domaines de messagerie spécifiques (par exemple *@mycompany.com).
• --extension-id par défaut, il inclut tous les ID d'extension axe connus (y compris Chrome et Edge).
• --database-encryption-key doit avoir 32 caractères de long.
• --database-encryption-iv doit avoir 16 caractères de long.

Variables d’environnement

Chacun de ces indicateurs de configuration peut être défini par des variables d'environnement au format :

AXE_DEVTOOLS_INSTALLER_{flag name}

Où {flag name} est la variante en majuscules avec des underscores de l'indicateur de configuration. Par exemple, --auth-service-admin-client-id peut être fourni en utilisant la variable d'environnement AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_ADMIN_CLIENT_ID .

De plus, un .env fichier dans le même répertoire de travail à partir duquel le programme d'installation est exécuté sera chargé, ce qui permet les opérations suivantes :

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

Exemple de configuration

Exemples de configurations pour l'installation d'axe DevTools.

Options de ligne de commande

./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" \
  --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" \
  --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"

Variables d'environnement (.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_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_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_ENABLE_AUDIT_LOG="false"

Notes

Journalisation

Les journaux sont actuellement envoyés à stdio. Les journaux sont rotatifs en fonction de la configuration de votre système (et non dictés par Axe lui-même).

Ils peuvent être récupérés avec journalctl. Par exemple :

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

État du système

Pour voir l'état complet du système, utilisez systemctl :

systemctl status

Pour voir l'état du service Axe, procédez comme suit :

systemctl status axe

Démarrage/arrêt des services Axe

Pour démarrer/arrêter un service, utilisez systemctl :

systemctl stop axe
systemctl start axe

Certificats TLS/SSL auto-signés

Si des certificats TLS/SSL auto-signés sont utilisés, AXE_DEVTOOLS_INSTALLER_ACCEPT_SELF_SIGNED_TLS=true ou le --accept-self-signed-tls=true doit être défini.

Machine Learning (ML)

Par défaut, les améliorations ML des extensions axe DevTools sont activées.

Afin d'exécuter la fonctionnalité ML, le serveur axe DevTools (portail de compte axe) communique avec le ML service qui à son tour communique avec le Sagemaker instance. Sagemaker effectue l'inférence de vision artificielle qui est utilisée pour réduire la quantité de travail manuel dans les IGT. Le service ML gère toutes les données d'image utilisées pour l'inférence et à d'autres fins (comme les captures d'écran des problèmes) et stocke les données pour une utilisation à long terme.

SageMaker ne stocke aucune donnée et il est donc recommandé à tous les clients d'autoriser leurs instances à communiquer avec le modèle hébergé de manière centralisée. Un client peut demander que cette fonctionnalité soit désactivée. Si cela est fait, ils perdront l’accès aux améliorations du modèle d'apprentissage automatique dans le produit qui peuvent aider à optimiser leurs tests et à automatiser des tâches autrement manuelles. Les captures d'écran des problèmes partagés et l'analyse du contraste des couleurs continueraient de fonctionner sans SageMaker.

Les instances privées et sur site peuvent prendre en charge les fonctionnalités d'apprentissage automatique en pointant l'instance vers une instance de service ML (celle-ci peut être partagée ou non) via la variable d'environnement ML_SERVICE (l'URL du service ML) et en définissant la variable d'environnement ML_SERVICE_API_KEY avec une clé API valide.

Fonctionnalités de Machine Learning

• Captures d'écran du problème (peuvent être consultées sur la page de partage de problème)
• Outil de vérification automatique du contraste des couleurs
• Détection automatique du rôle des éléments
• Détection automatique des étiquettes d'entrée

Authentification

Deque SSO est requis pour que les utilisateurs puissent se connecter à l'application. Ce service SSO peut être partagé entre plusieurs produits Deque et peut être établi de plusieurs manières. Comme documenté ci-dessus, il existe un certain nombre de variables d'environnement AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_* qui permettent à l'extension axe DevTools de permettre aux utilisateurs de se connecter à l'application.