Installationsanweisungen für On-Premises

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

Anforderungen

Bevor Sie versuchen, axe zu installieren, stellen Sie sicher, dass die folgenden Anforderungen erfüllt sind.

Betriebssystem

Axe ist für den Einsatz auf 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 gezeigt, dass ein AWS t2.micro in der Lage ist, eine kleine Benutzergruppe (etwa 25 Benutzer) zu unterstützen, ohne die Anwendung erheblich zu belasten. Wir empfehlen nicht, axe auf einem Server zu betreiben, der nicht die gleichen Spezifikationen wie ein t2.micro hat.

Wenn Sie eine größere Benutzergruppe haben, konsultieren Sie die folgende Tabelle für Empfehlungen.

Unabhängig von der Maschinengröße sind mindestens 15 GB physischer Speicher (Platz auf der Festplatte) erforderlich. Wir empfehlen jedoch 30+ GB.

Netzwerkanforderungen

Axe benötigt derzeit keinen ausgehenden Netzwerkzugriff, außer um auf Anfragen zu reagieren, die an ihn gestellt werden.

Axe wird die folgenden Ports auf dem System öffnen, auf dem es eingesetzt wird:

Wenn Sie planen, PostgreSQL auf demselben Rechner wie Axe auszuführen, wird dessen Standardport (5432) geöffnet, ist jedoch nicht vom Internet aus erreichbar.

DNS-Anforderungen

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

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

SELinux-Konfiguration

Axe erfordert, dass ein einzelnes SELinux-Flag deaktiviert wird:

setsebool -P httpd_can_network_connect 1

Dies ermöglicht es NGINX, als Reverse Proxy zu fungieren und auf ausgehende Netzwerk-Anfragen zu reagieren.

Benutzer

Es wird erwartet, dass das Installationsprogramm als root -Benutzer ausgeführt wird. Wenn Sie sich nicht als root-Benutzer sudo su können, wird die Installation fehlschlagen.

Das Installationsprogramm erstellt die folgenden Benutzer:

Keiner dieser Benutzer benötigt erhöhte Berechtigungen.

Abhängigkeiten

Der Axe-Installer bündelt alle seine Abhängigkeiten. Der Server, auf dem Axe installiert wird, muss nicht auf das Internet zugreifen, um Axe auszuführen.

Eine Axe-Bereitstellung hat harte Abhängigkeiten von der folgenden Software:

• NGINX - Macht die Axe-Server in Ihrem Netzwerk verfügbar
• PostgreSQL - Datenspeicherung

Der Axe-Server läuft über Node.js, aber Node muss nicht auf dem System installiert sein.

NGINX

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

Die notwendigen RPMs zur Installation von NGINX sind im Axe-Installer enthalten. Um NGINX zu installieren, tun Sie Folgendes:

# 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. Eine gültige Verbindung zu PostgreSQL muss dem Installer 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 läuft.

Die notwendigen RPMs zur Installation von PostgreSQL sind im Axe-Installer enthalten. Um PostgreSQL zu installieren, tun Sie Folgendes:

# 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

Die Installation ausführen

Der Installer muss als der Benutzer root ausgeführt werden. Überprüfen Sie, ob Sie der Benutzer root sind, indem Sie Folgendes ausführen:

whoami

Wenn Sie den Installer bereits extrahiert haben, seien Sie sicher, das Verzeichnis migrations zu leeren:

rm -f installer/migrations/*.sql

Der Installer 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

Dies führt zu einer Struktur ähnlich wie:

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

Einmal extrahiert, besteht der nächste Schritt darin, das installer/installer Programm auszuführen.

Installer-Konfiguration

Viele Konfigurationsflags sind erforderlich, um den Installer zu konfigurieren. Die folgende Tabelle erklärt jedes CLI-Flag, das dem installer Programm übergeben werden muss.

Anmerkungen zu den Konfigurationsflags

• --migration-directory sollte auf das Verzeichnis zeigen, in das das Installations-Tarball extrahiert wurde, plus /migrations. Dies kann wahrscheinlich $PWD/migrations sein.
• --address ist der vorkonfigurierte DNS für die Axe-Installation.
• --allowed-email-domains kann gesetzt werden, wenn Ihre Axe-Installation nur die Nutzung von bestimmten E-Mail-Domains zulassen soll (z. B. *@mycompany.com).
• --extension-id ist standardmäßig auf alle bekannt Axe-Erweiterungs-IDs (einschließlich Chrome und Edge) eingestellt.
• --database-encryption-key muss 32 Zeichen lang sein.
• --database-encryption-iv müssen 16 Zeichen lang sein.

Umgebungsvariablen

Jede dieser Konfigurationsflags kann durch Umgebungsvariablen mit folgendem Format gesetzt werden:

AXE_DEVTOOLS_INSTALLER_{flag name}

Dabei ist {flag name} die Variante des Konfigurationsflags im Großschreibweise-Schlangenmuster. Zum Beispiel 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 gleichen Arbeitsverzeichnis, von dem aus der Installer ausgeführt wird, geladen und ermöglicht Folgendes:

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

Beispielkonfiguration

Beispielkonfigurationen für die Installation von axe DevTools.

Kommandozeilen-Flags

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

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

Anmerkungen

Protokollierung

Protokolle werden derzeit an stdio gesendet. Protokolle werden basierend auf Ihrer Systemkonfiguration rotiert (nicht von axe selbst bestimmt).

Sie 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, tun Sie Folgendes:

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, AXE_DEVTOOLS_INSTALLER_ACCEPT_SELF_SIGNED_TLS=true oder das --accept-self-signed-tls=true muss gesetzt sein.

Maschinelles Lernen (ML)

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

Um die ML-Funktionalität auszuführen, kommuniziert der axe DevTools Server (axe Account Portal) mit dem ML service, der wiederum mit dem Sagemaker instance kommuniziert. Sagemaker führt die maschinelle Seh-Inferenz durch, die verwendet wird, um die Menge an manueller Arbeit in IGTs zu reduzieren. Der ML-Dienst verarbeitet alle Bilddaten, die für Inferenz und andere Zwecke wie Problem-Screenshots verwendet werden, und speichert die Daten zur langfristigen Nutzung.

SageMaker speichert keine Daten, und es wird daher empfohlen, dass alle Kunden ihren Instanzen erlauben, mit dem zentral gehosteten Modell zu kommunizieren. Ein Kunde kann diese Funktion deaktivieren lassen. Wenn dies geschieht, verlieren sie den Zugang zu den ML-Modelverbesserungen im Produkt, die dazu beitragen können, ihr Testen zu optimieren und sonst manuelle Aufgaben zu automatisieren. Die geteilten Problemscreenshots und die Farbkontrasteanalyse würden ohne SageMaker weiter funktionieren.

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

Funktionen des Maschinellen Lernens

• Problembildschirmfotos (können auf der Seite zum Teilen von Problemen angesehen werden)
• Automatisches Werkzeug zur Prüfung des Farbkontrasts
• Automatische Erkennung von Elementrollen
• Automatische Erkennung von Eingabelabels

Authentifizierung

Deque SSO ist erforderlich, damit Benutzer sich in die Anwendung einloggen können. Dieser SSO-Dienst kann zwischen mehreren Deque-Produkten geteilt werden und auf unterschiedliche Weise bereitgestellt werden. Wie oben dokumentiert, gibt es eine Anzahl von AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_* Umgebungsvariablen, die es der axe DevTools-Erweiterung ermöglichen, Benutzern das Einloggen in die Anwendung zu erlauben.