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