Installatie-instructies voor On-premises

Dit document beschrijft het proces van het installeren van axe DevTools op een on-premises locatie.

Vereisten

Voordat u probeert axe te installeren, zorg ervoor dat aan de volgende vereisten is voldaan.

Besturingssysteem

Axe is ontworpen om te draaien op RHEL7 of RHEL8. Andere besturingssystemen worden momenteel niet ondersteund.

Voordat u axe installeert, wordt verwacht dat uw systeem is bijgewerkt via:

yum update -y

Hardwarevereisten

Onze belastingtests hebben aangetoond dat een AWS t2.micro in staat is om een kleine gebruikersgroep (ongeveer 25 gebruikers) te ondersteunen zonder aanzienlijke belasting op de applicatie te leggen. We raden af om axe te implementeren op een server die niet over vergelijkbare specificaties als een t2.micro beschikt.

Als u een grotere gebruikersbasis heeft, raadpleeg dan de onderstaande tabel voor aanbevelingen.

Bij elke machinespecifikatie is minimaal 15 GB aan fysieke opslag (schijfruimte) vereist. We raden echter 30+ GB aan.

Netwerkvereisten

Axe heeft momenteel geen uitgaand netwerktoegang nodig, behalve om te reageren op verzoeken die eraan worden gedaan.

Axe zal de volgende poorten openen op het systeem waarop het wordt geïmplementeerd:

Als u van plan bent om PostgreSQL op dezelfde machine als axe te draaien, zal de standaardpoort (5432) worden geopend, maar niet toegankelijk zijn vanaf het externe internet.

DNS-vereisten

DNS moet worden aangemaakt voor axe. Deze DNS kan zich achter de firewall van uw bedrijf bevinden, in uw eigen privénetwerk, of toegankelijk zijn voor het openbare internet. Voor onze privé axe-server hebben we een A-record gericht op een EC2-instance in ons AWS-account.

Het voorbeeld-DNS dat in dit document wordt gebruikt is axe.mycompany.com.

SELinux-configuratie

Axe vereist dat een enkele SELinux-flag wordt uitgeschakeld:

setsebool -P httpd_can_network_connect 1

Dit stelt NGINX in staat om als een reverse proxy te fungeren en te reageren op uitgaande netwerkverzoeken.

Gebruikers

Het is de bedoeling dat de installer wordt uitgevoerd als de root gebruiker. Als u niet kunt sudo su naar de root gebruiker, zal de installatie mislukken.

De installatie zal de volgende gebruikers aanmaken:

Geen van deze gebruikers heeft verhoogde rechten nodig.

Afhankelijkheden

The axe installer bundles all of its dependencies. The server axe is installed to **heeft** niet need access to the outside Internet in order to get axe running.

Een axe-implementatie heeft harde afhankelijkheden van de volgende software:

• NGINX - Stelt de axe-servers bloot aan uw netwerk
• PostgreSQL - Gegevensopslag

De axe-server draait via Node.js, maar Node hoeft niet op het systeem te zijn geïnstalleerd.

NGINX

NGINX moet worden geïnstalleerd/geconfigureerd om verkeer door te sturen naar de axe-server. Er is een voorbeeldconfiguratie voor NGINX verstrekt (zie axe-nginx-example.conf).

De benodigde RPM's voor het installeren van NGINX zijn opgenomen in de axe-installer. Om NGINX te installeren, doe:

# 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

De axe-server gebruikt PostgreSQL voor gegevensopslag. Een geldige verbinding met PostgreSQL moet aan de installer worden verstrekt.

Axe ondersteunt zowel een externe PostgreSQL (bijv. een RDS gehost door AWS) als een PostgreSQL-server die op dezelfde machine draait.

De benodigde RPM's voor het installeren van PostgreSQL zijn opgenomen in de axe-installer. Om PostgreSQL te installeren, doe:

# 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

De Installer Uitvoeren

De installer moet worden uitgevoerd als de root gebruiker. Verifieer dat u de root gebruiker bent door het volgende uit te voeren:

whoami

Als u de installer eerder hebt uitgepakt, zorg er dan voor dat u de migrations-directory leegmaakt:

rm -f installer/migrations/*.sql

De installer wordt geleverd als een enkel (archief)bestand: installer.tar.gz. Om het archief uit te pakken, voert u het volgende uit:

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

Dit resulteert in een structuur die lijkt op:

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

Na het uitpakken is de volgende stap het uitvoeren van het installer/installer programma.

Installerconfiguratie

Er zijn veel configuratievlaggen nodig om de installer te configureren. De volgende tabel legt elke CLI-vlag uit die moet worden doorgegeven aan het installer programma.

Configuratievlagnotities

• --migration-directory moet wijzen naar de directory waar het installer-tarball naartoe is uitgepakt plus /migrations. Dit kan waarschijnlijk $PWD/migrations zijn.
• --address is de vooraf geconfigureerde DNS voor de axe-installatie.
• --allowed-email-domains *kan* worden ingesteld als uw axe-installatie alleen gebruik van specifieke e-maildomeinen moet toestaan (bijv. *@mycompany.com).
• --extension-id standaard naar alle *bekende* axe-extensie-ID's (inclusief Chrome en Edge).
• --database-encryption-key **moet** 32 karakters lang zijn.
• --database-encryption-iv **moet** 16 karakters lang zijn.

Omgevingsvariabelen

Elk van deze configuratievlaggen kan worden ingesteld door omgevingsvariabelen in het volgende formaat:

AXE_DEVTOOLS_INSTALLER_{flag name}

Waar {flag name} de snake_case-variant in hoofdletters van de configuratievlag is. Bijvoorbeeld, --auth-service-admin-client-id kan worden verstrekt door gebruik te maken van de AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_ADMIN_CLIENT_ID omgevingsvariabele.

Bovendien wordt er een .env-bestand in dezelfde werkdirectory waarvan de installer wordt uitgevoerd geladen, waardoor het volgende mogelijk wordt:

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

Voorbeeldconfiguratie

Voorbeeldconfiguraties voor het installeren van axe DevTools.

Commandoregelvlaggen

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

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

Notities

Logboekregistratie

Logboeken worden momenteel verzonden naar stdio. Logboeken worden geroteerd op basis van uw systeemconfiguratie (niet voorgeschreven door axe zelf).

Ze kunnen worden opgehaald met journalctl. Bijvoorbeeld:

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

Systeemstatus

Om de volledige systeemstatus te zien, gebruik systemctl:

systemctl status

Om de status van de axe-dienst te zien, doe:

systemctl status axe

Starten / Stoppen van Axe-diensten

Om een service te starten/stoppen, gebruik systemctl:

systemctl stop axe
systemctl start axe

Zelfondertekende TLS/SSL-certificaten

Als zelfondertekende TLS/SSL-certificaten worden gebruikt, moeten AXE_DEVTOOLS_INSTALLER_ACCEPT_SELF_SIGNED_TLS=true of de --accept-self-signed-tls=true worden ingesteld.

Machine Learning (ML)

Standaard zijn de ML-verbeteringen van axe DevTools Extensions ingeschakeld.

Om de ML-functionaliteit uit te voeren, communiceert de axe DevTools Server (axe Account Portal) met de ML service die op zijn beurt communiceert met de Sagemaker instance. Sagemaker voert de machine vision-inferentie uit die wordt gebruikt om de hoeveelheid handmatig werk in IGT's te verminderen. De ML-service verwerkt alle beeldgegevens die voor inferentie en andere doeleinden worden gebruikt - zoals issueschermopnamen - en slaat de gegevens op voor langdurig gebruik.

SageMaker slaat geen gegevens op, en het wordt daarom aanbevolen dat alle klanten hun instanties toestaan te communiceren met het centraal gehoste model. Een klant kan verzoeken om deze functie uit te schakelen. Als dit wordt gedaan, verliezen ze de toegang tot de ML-modelverbeteringen in het product die kunnen helpen bij het optimaliseren van hun tests en bij het automatiseren van anders handmatige taken. Het delen van problemen en de kleuranalysator zouden blijven functioneren zonder SageMaker.

Private en on-premise instanties kunnen ML-functies ondersteunen door de instantie te verbinden met een ML-service-instantie (deze kan gedeeld of niet gedeeld zijn) via de ML_SERVICE-omgevingsvariabele (de URL van de ML-service) en de ML_SERVICE_API_KEY-omgeving var in te stellen met een geldige API-sleutel.

Machine Learning-functies

• Probleemschermafbeeldingen (kunnen bekeken worden op de probleemdeelpagina)
• Automatisch hulpmiddel voor beoordeling van kleurcontrast
• Automatische detectie van elementrol
• Automatische detectie van invoerveldlabels

Authenticatie

Deque SSO is vereist opdat gebruikers kunnen inloggen op de applicatie. Deze SSO-service kan worden gedeeld tussen meerdere Deque-producten en kan op verschillende manieren worden opgezet. Zoals hierboven gedocumenteerd, zijn er verschillende AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_* omgevingsvariabelen die de axe DevTools-uitbreiding in staat stellen gebruikers in te laten loggen op de applicatie.