Instructions d'installation sur site

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

Exigences

Avant de tenter d'installer axe, assurez-vous que les exigences suivantes sont remplies.

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, il est attendu que votre système ait été mis à jour via :

yum update -y

Exigences matérielles

Nos tests de charge ont prouvé qu'une AWS t2.micro est capable de prendre en charge un petit nombre d'utilisateurs (environ 25 utilisateurs) sans surcharger l'application. Nous ne recommandons pas de déployer axe sur un serveur qui n'a pas des caractéristiques équivalentes à une t2.micro.

Si vous avez un nombre plus élevé d'utilisateurs, référez-vous au tableau ci-dessous pour les recommandations.

Pour toutes les tailles de machine, un minimum de 15 Go de stockage physique (espace disque) est requis. Cependant, nous recommandons plus de 30 Go.

Exigences réseau

Axe n'a actuellement pas besoin d'accès réseau sortant, sauf pour répondre aux requêtes 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.

Exigences DNS

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

Le DNS d’exemple utilisé dans ce document est axe.mycompany.com.

Configuration SELinux

Axe nécessite la désactivation d’un seul indicateur SELinux :

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

L'installateur est censé être exécuté en tant qu'utilisateur root. Si vous ne pouvez pas sudo su à l'utilisateur root, l'installateur échouera.

L'installateur créera les utilisateurs suivants :

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

Dépendances

L’installateur axe regroupe toutes ses dépendances. Le serveur axe installé sur ne pas besoin d’un accès à Internet pour faire fonctionner axe.

Un déploiement de axe a des dépendances strictes 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 diriger le trafic vers le serveur axe. Une configuration NGINX d’exemple a été fournie (voir axe-nginx-example.conf).

Les RPM nécessaires à l’installation de NGINX sont inclus dans l’installateur axe. Pour installer NGINX, exécutez :

# 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 à l’installateur.

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 l’installateur axe. Pour installer PostgreSQL, exécutez :

# 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

Exécution de l'installateur

L'installateur doit être exécuté en tant qu'utilisateur root. Vérifiez que vous êtes l'utilisateur root en exécutant :

whoami

Si vous avez précédemment extrait l’installateur, assurez-vous de vider le répertoire migrations :

rm -f installer/migrations/*.sql

L’installateur sera livré sous forme de fichier unique (archive) : installer.tar.gz. Pour extraire l’archive, exécutez ce qui suit :

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

Cela aboutira à 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 est d'exécuter le programme installer/installer.

Configuration de l'installateur

De nombreux drapeaux de configuration sont nécessaires pour configurer l'installateur. Le tableau suivant explique chaque drapeau CLI à passer au programme installer.

Notes sur les indicateurs de configuration

• --migration-directory doit pointer vers le répertoire où l'archive d'installation a été extraite plus /migrations. Cela peut probablement être $PWD/migrations.
• --address est le DNS préconfiguré pour l'installation d'Axe.
• --allowed-email-domains peut être défini si votre installation d'Axe doit permettre l'utilisation uniquement à partir de domaines de messagerie spécifiques (par exemple *@mycompany.com).
• --extension-id par défaut pour tous les connu IDs d'extension Axe (y compris Chrome et Edge).
• --database-encryption-key doit être de 32 caractères de long.
• --database-encryption-iv doit être de 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 suivant :

AXE_DEVTOOLS_INSTALLER_{flag name}

Où {flag name} est la variante en majuscules et avec des traits de soulignement du drapeau 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 fichier .env dans le même répertoire de travail où l'installateur est exécuté sera chargé, permettant ce qui suit :

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

Configuration Exemple

Exemples de configurations pour installer axe DevTools.

Drapeaux 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" \
  --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 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_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"

Remarques

Journalisation

Les journaux sont actuellement envoyés à stdio. Les journaux sont tournés en fonction de la configuration de votre système (non dictée 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, faites :

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.

Apprentissage automatique (ML)

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

Pour effectuer les fonctionnalités ML, le serveur axe DevTools (portail de compte axe) communique avec le ML service qui à son tour communique avec le Sagemaker instance. Sagemaker réalise l'inférence de vision par ordinateur qui est utilisée pour réduire le travail manuel dans les IGT. Le service ML gère toutes les données d'image utilisées pour l'inférence et pour d'autres objectifs - comme les captures d'écran de problèmes - et stocke les données pour une utilisation à long terme.

SageMaker ne stocke aucune donnée, et il est donc recommandé que tous les clients permettent à leurs instances de communiquer avec le modèle hébergé centralement. Un client peut demander la désactivation de cette fonctionnalité. Dans ce cas, ils perdront l'accès aux améliorations du modèle ML dans le produit qui peuvent aider à optimiser leurs tests et à automatiser des tâches qui étaient auparavant manuelles. Les captures d'écran des problèmes partagés et l'analyse de contraste des couleurs continueraient à fonctionner sans SageMaker.

Les instances privées et sur site peuvent prendre en charge les fonctionnalités ML en pointant l'instance vers une instance de service ML (cela peut être partagé ou non partagé) 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 d'apprentissage automatique

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

Authentification

Le SSO de Deque est requis pour que les utilisateurs se connectent à l’application. Ce service de SSO peut être partagé entre plusieurs produits Deque et peut être déployé de plusieurs façons. 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.