Anweisungen zur lokalen Installation

Dieses Dokument beschreibt den Prozess der Installation von axe DevTools an einem lokalen Standort.

Anforderungen

Stellen Sie vor der Installation von axe DevTools sicher, dass die folgenden Anforderungen erfüllt sind.

Betriebssystem

Axe ist für die Ausführung unter RHEL7 oder RHEL8 konzipiert. Andere Betriebssysteme werden derzeit nicht unterstützt.

Vor der Installation von axe wird erwartet, dass Ihr System wie folgt aktualisiert wurde:

yum update -y

Hardwareanforderungen

Unsere Belastungstests haben bewiesen, dass eine AWS-Instanz t2.micro in der Lage ist, eine kleine Benutzerbasis (ca. 25 Benutzer) zu unterstützen, ohne die Anwendung erheblich zu belasten. Wir empfehlen nicht, Axe auf einem Server bereitzustellen, der nicht über die gleichen Spezifikationen verfügt wie ein [fehlendes Nomen]. t2.micro

Wenn Sie über eine größere Benutzerbasis verfügen, finden Sie Empfehlungen in der folgenden Tabelle.

Auf jeder Maschinengröße werden mindestens 15 GB physischer Speicher (Laufwerksspeicher) benötigt. Wir empfehlen jedoch 30+ GB.

Netzwerkanforderungen

Axe benötigt derzeit keinen ausgehenden Netzwerkzugriff, außer um auf an ihn gerichtete Anfragen zu antworten.

Axe öffnet die folgenden Ports auf dem System, auf dem es bereitgestellt wird:

Wenn Sie PostgreSQL auf derselben Maschine wie axe ausführen möchten, wird dessen Standardport (5432) geöffnet, ist aber vom externen Internet nicht zugänglich.

DNS-Anforderungen

Für axe muss DNS erstellt werden. Dieser DNS kann sich hinter der Firewall Ihres Unternehmens, in Ihrem eigenen privaten Netzwerk oder zugänglich über das öffentliche Internet befinden. Für unseren privaten Axe-Server haben wir einen A Eintrag, der auf eine EC2-Instanz in unserem AWS-Konto verweist.

Das in diesem Dokument verwendete Beispiel-DNS ist: axe.mycompany.com

SELinux-Konfiguration

Für Axe muss ein einzelnes SELinux-Flag deaktiviert werden:

setsebool -P httpd_can_network_connect 1

Dadurch kann NGINX als reverse proxy fungieren und auf ausgehende Netzwerkanforderungen antworten.

Benutzer

Es wird erwartet, dass das Installationsprogramm als root Benutzer ausgeführt wird. Wenn Sie keinen Zugriff sudo su auf den root Benutzer haben, schlägt das Installationsprogramm fehl.

Das Installationsprogramm erstellt die folgenden Benutzer:

Keiner dieser Benutzer benötigt erweiterte Berechtigungen.

Abhängigkeiten

Das Axe-Installationsprogramm bündelt alle seine Abhängigkeiten. Der Server, auf dem Axe installiert ist, braucht keinen Zugriff auf das externe Internet, um Axe zum Laufen zu bringen.

Eine Axe-Bereitstellung weist feste Abhängigkeiten von der folgenden Software auf:

• NGINX - Stellt die Axe-Server Ihrem Netzwerk zur Verfügung
• PostgreSQL - Datenspeicherung

Der Axe-Server läuft mit Node.js, Node muss jedoch nicht auf dem System installiert sein.

NGINX

NGINX muss installiert/konfiguriert werden, um den Datenverkehr an den Axe-Server weiterzuleiten. Es wurde eine Beispielkonfiguration für NGINX bereitgestellt (siehe axe-nginx-example.conf).

Die erforderlichen RPMs zur Installation von NGINX sind im Axe-Installationsprogramm enthalten. So installieren Sie NGINX:

# 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

Der Axe-Server verwendet PostgreSQL zur Datenspeicherung. Dem Installationsprogramm muss eine gültige Verbindung zu PostgreSQL bereitgestellt werden.

Axe unterstützt sowohl ein externes PostgreSQL (z. B. ein von AWS gehostetes RDS) als auch einen PostgreSQL-Server, der auf derselben Maschine ausgeführt wird.

Die erforderlichen RPMs zur Installation von PostgreSQL sind im Axe-Installationsprogramm enthalten. So installieren Sie PostgreSQL:

# 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

Ausführen des Installationsprogramms

Das Installationsprogramm muss als root Benutzer root ausgeführt werden. Bestätigen Sie, dass Sie der root Benutzer sind, indem Sie Folgendes ausführen:

whoami

Wenn Sie das Installationsprogramm zuvor extrahiert haben, löschen Sie unbedingt das migrations Verzeichnis:

rm -f installer/migrations/*.sql

Das Installationsprogramm wird als einzelne (Archiv-)Datei geliefert: installer.tar.gz. Um das Archiv zu extrahieren, führen Sie Folgendes aus:

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

Das Ergebnis ist eine Struktur ähnlich der folgenden:

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

Nach dem Extrahieren besteht der nächste Schritt darin, das installer/installer Programm auszuführen.

Installer-Konfiguration

Zum Konfigurieren des Installationsprogramms werden viele Konfigurationsflags benötigt. In der folgenden Tabelle werden die einzelnen CLI-Flags erläutert, die an das installer Programm übergeben werden.

Hinweise zu Konfigurationsflags

• --migration-directory sollte auf das Verzeichnis verweisen, in das das Installations-Tarball extrahiert wurde plus /migrations. Das kann durchaus sein $PWD/migrations.
• --address ist der vorkonfigurierte DNS für die Axe-Installation.
• --allowed-email-domains kann festgelegt werden, wenn Ihre axe-Installation nur die Nutzung von bestimmten E-Mail-Domänen zulassen soll (z. B. „*@mycompany.com“).
• --extension-id Standardmäßig werden alle bekannten axe-Erweiterungs-IDs verwendet (einschließlich Chrome und Edge).
• --database-encryption-key **muss ** 32 Zeichen lang sein.
• --database-encryption-iv **muss ** 16 Zeichen lang sein.

Umgebungsvariablen

Jedes dieser Konfigurationsflags kann durch Umgebungsvariablen im folgenden Format gesetzt werden:

AXE_DEVTOOLS_INSTALLER_{flag name}

Wobei {flag name} die Variante in Großbuchstaben und Unterstrichen des Konfigurationsflags ist. Beispielsweise kann --auth-service-admin-client-id durch die Verwendung der Umgebungsvariable AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_ADMIN_CLIENT_ID bereitgestellt werden.

Zusätzlich wird eine .env Datei im selben Arbeitsverzeichnis geladen, aus dem das Installationsprogramm ausgeführt wird. Dadurch wird Folgendes ermöglicht:

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

Beispielkonfiguration

Beispielkonfigurationen für die Installation von axe DevTools.

Befehlszeilenflags

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

Umgebungsvariablen (.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"

Notizen

Protokollierung

Protokolle werden derzeit gesendet an stdio Die Protokolle werden basierend auf Ihrer Systemkonfiguration rotiert (nicht von Axe selbst vorgegeben).

Diese können mit journalctl abgerufen werden. Zum Beispiel:

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

Systemstatus

Um den gesamten Systemstatus anzuzeigen, verwenden Sie systemctl:

systemctl status

Um den Status des Axe-Dienstes anzuzeigen, gehen Sie wie folgt vor:

systemctl status axe

Starten/Stoppen von Axe-Diensten

Um einen Dienst zu starten/stoppen, verwenden Sie systemctl:

systemctl stop axe
systemctl start axe

Selbstsignierte TLS/SSL-Zertifikate

Wenn selbstsignierte TLS/SSL-Zertifikate verwendet werden, muss AXE_DEVTOOLS_INSTALLER_ACCEPT_SELF_SIGNED_TLS=true oder --accept-self-signed-tls=true festgelegt werden.

Machine Learning (ML)

Standardmäßig sind die ML-Erweiterungen der Axe DevTools Extensions aktiviert.

Um die ML-Funktionalität auszuführen, kommuniziert der axe DevTools Server (axe Account Portal) mit dem ML service , das wiederum mit dem Sagemaker instance kommuniziert. Sagemaker führt die maschinelle Bildverarbeitungsinferenz durch, mit der der manuelle Arbeitsaufwand in IGTs reduziert wird. Der ML-Dienst verarbeitet alle Bilddaten, die für Inferenzen und andere Zwecke verwendet werden – wie etwa Screenshots von Problemen – und speichert die Daten für die langfristige Verwendung.

SageMaker speichert keine Daten und es wird daher allen Kunden empfohlen, ihren Instanzen die Kommunikation mit dem zentral gehosteten Modell zu erlauben. Ein Kunde kann die Deaktivierung dieser Funktion beantragen. In diesem Fall verlieren sie den Zugriff auf die ML-Modellerweiterungen im Produkt, die ihnen bei der Optimierung ihrer Tests und der Automatisierung ansonsten manueller Aufgaben helfen können. Die freigegebenen Problem-Screenshots und die Farbkontrastanalyse würden auch ohne SageMaker weiterhin funktionieren.

Private und lokale Instanz können ML-Funktionen unterstützen, indem die Instanz über die Umgebungsvariable ML_SERVICE (die URL des ML-Dienstes) auf eine ML-Dienstinstanz verweist (diese kann geteilt oder nicht geteilt werden) und die Umgebungsvariable ML_SERVICE_API_KEY mit einem gültigen API-Schlüssel festgelegt wird.

Funktionen für maschinelles Lernen

• Screenshots des Problems (können auf der Seite „Problem teilen“ angezeigt werden)
• Automatisches Tool zur Überprüfung des Farbkontrasts
• Automatische Elementrollenerkennung
• Automatische Erkennung der Eingabebezeichnung

Authentifizierung

Deque SSO ist erforderlich, damit sich Benutzer bei der Anwendung anmelden können. Dieser SSO-Dienst kann zwischen mehreren Deque-Produkten gemeinsam genutzt und auf verschiedene Arten eingerichtet werden. Wie oben dokumentiert, gibt es eine Reihe von Umgebungsvariablen AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_*, die es der axe DevTools-Erweiterung ermöglichen, Benutzern die Anmeldung bei der Anwendung zu ermöglichen.