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 load testing heeft aangetoond dat een AWS t2.micro in staat is om een kleine gebruikersbasis (ongeveer 25 gebruikers) te ondersteunen zonder een significante belasting op de applicatie te leggen. We raden af om axe te implementeren op een server die niet dezelfde specificaties heeft als een t2.micro.

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 dat wijst naar een EC2-instantie 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 te functioneren als een reverse proxy en om te reageren op uitgaande netwerkverzoeken.

Gebruikers

De installatie wordt verwacht te draaien 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

De axe-installateur bundelt al zijn afhankelijkheden. De server waarop axe wordt geïnstalleerd **heeft** niet noodzakelijk toegang tot het externe internet nodig om axe aan de praat te krijgen.

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 naar de axe-server door te sturen. Een voorbeeld van een NGINX-configuratie is 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. Controleer of u de root gebruiker bent door het volgende uit te voeren:

whoami

Als u de installer eerder heeft uitgepakt, zorg dan dat u de migrations map leegt:

rm -f installer/migrations/*.sql

De installer wordt geleverd als één (archief)bestand: installer.tar.gz. Om het archief uit te pakken, voer 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

Eenmaal uitgepakt, is de volgende stap het uitvoeren van het installer/installer programma.

Installerconfiguratie

Veel configuratievlaggen zijn 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 map waarin het installatietarbal is uitgepakt plus /migrations. Dit kan waarschijnlijk $PWD/migrations.
• --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 (bijv. *@mycompany.com).
• --extension-id standaard naar alle *bekende* axe-extensie-ID's (inclusief Chrome en Edge).
• --database-encryption-key **moet** 32 tekens lang zijn.
• --database-encryption-iv **moet** 16 tekens 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 variant in hoofdletters met underscores van de configuratievlag is. Bijvoorbeeld, --auth-service-admin-client-id kan worden verstrekt door het gebruik van de AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_ADMIN_CLIENT_ID omgevingsvariabele.

Daarnaast zal een .env bestand in dezelfde werkmap waarin de installer wordt uitgevoerd worden geladen, waardoor het volgende mogelijk is:

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 bepaald 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 dienst te starten/stoppen, gebruik systemctl:

systemctl stop axe
systemctl start axe

Zelfondertekende TLS/SSL-certificaten

Als er zelfondertekende TLS/SSL-certificaten worden gebruikt, AXE_DEVTOOLS_INSTALLER_ACCEPT_SELF_SIGNED_TLS=true of de --accept-self-signed-tls=true moet 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 vervolgens 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 worden gebruikt voor inferentie en andere doeleinden - zoals schermafbeeldingen van problemen - 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 zodat gebruikers kunnen inloggen op de applicatie. Deze SSO-dienst kan worden gedeeld tussen meerdere Deque-producten en kan op verschillende manieren worden opgezet. Zoals hierboven gedocumenteerd, zijn er een aantal AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_* omgevingsvariabelen die de axe DevTools-extensie in staat stellen gebruikers in te laten loggen op de applicatie.