Instructions d'installation sur site

Link to Instructions d'installation sur site copied to clipboard
Not for use with personal data

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.

Spéc Prérequis
Cœurs de processeur 1
Vitesse du processeur 3,3 GHz
RAM 1 Go
Stockage 15 Go

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

Utilisateurs Processeurs RAM (Go) Taille AWS T2
100 1 2 petit
300 2 4 moyen
500 4 8 grand
700 8 16 Très grand
1000 8 32 2 fois grand

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é :

Numéro de port Accessible depuis Internet Objectif
80 oui Trafic HTTP entrant
443 oui Trafic HTTPS entrant (uniquement lorsqu'il est exécuté en mode SSL)
3000 Non Serveur Axe

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 :

Utilisateur Objectif
nginx Exécute le service nginx
axe Exécute le service Axe
postgres Exécute le service postgres

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.

Option Description
axe-database-name Nom de la base de données pour Axe
mot-de-passe-base-de-données-axe Mot de passe pour la base de données Axe
nom-base-de-données-maître Nom de la base de données maître
utilisateur-base-de-données-maître Utilisateur pour la base de données principale
Mot de passe de la base de données principale Mot de passe pour l'utilisateur de la base de données principale
hôte-de-base-de-données-principale Hôte pour la base de données principale
Port de base de données principale Port pour la base de données principale (par défaut 5432)
Clé de chiffrement de base de données Clé de 32 caractères pour le chiffrement de la base de données
iv-de-chiffrement-de-base-de-donnees IV de 16 caractères pour le cryptage de la base de données
répertoire-migration Répertoire contenant les migrations de bases de données Axe
axe-user Nom de l'utilisateur système qui exécutera le service axe
ID d'extension ID de l'extension Google Chrome pour l'extension Axe
adresse Adresse (URL) que le service Axe utilisera
Secrets des cookies Secrets pour signer les cookies Axe (liste séparée par des virgules)
domaines-email-autorisés Liste blanche des domaines de messagerie (liste séparée par des virgules)
url-service-auth Définir l'adresse sur un déploiement de service d'authentification existant
auth-service-realm Le nom du realm qu'Axe utilisera
auth-service-admin-nom-utilisateur Nom d'utilisateur pour un administrateur de royaume « maître » existant
auth-service-admin-password Mot de passe pour un administrateur de royaume « maître » existant
auth-service-axe-admin-nom-utilisateur Nom d'utilisateur pour l'administrateur Axe
auth-service-axe-admin-mot-de-passe Mot de passe pour l'utilisateur administrateur Axe
auth-service-public-client-id ID du client public pour ce déploiement Axe
auth-service-confidentiel-client-id ID du client confidentiel pour ce déploiement Axe
auth-service-admin-client-id ID client pour un client administrateur existant (généralement « admin-cli »)
ml-service-api-key Clé API pour le service Machine Learning Deque
ml-service-url URL du service Machine Learning Deque
Délai d'expiration du service ml Délai d'expiration de la demande (en ms) pour le service Deque Machine Learning
Partagé avec Remplace les tests et le partage des problèmes. Soit « utilisateurs » soit « n’importe qui ».
URL du service de facturation URL du service de facturation (facultatif)
migrer-vers-la-facturation Migrer les utilisateurs existants vers le service de facturation
administrateurs-service-facturation Assurez-vous que certains utilisateurs sont administrateurs lors de la migration vers le service-de-facturation (facultatif ; nécessite --billing-service-url et --migrate-to-billing)
accepter-ssl-auto-signe Accepter les certificats TLS/SSL auto-signés (facultatif)
max-concurrence-migration Nombre maximal de demandes effectuées lors de la migration des utilisateurs vers le service de facturation (facultatif ; la valeur par défaut est 20)
activer-log-audit Activer ou désactiver la fonction de journal d'audit
smtp-host Hôte SMTP pour l'envoi d'e-mails
smtp-port Port SMTP pour l'envoi d'e-mails
Nom d'utilisateur SMTP Nom d'utilisateur SMTP pour l'envoi d'e-mails
Mot de passe SMTP Mot de passe SMTP pour l'envoi d'e-mails

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}

{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.