Istruzioni per l'installazione in sede

Questo documento descrive il processo di installazione di axe DevTools in una sede locale.

Requisiti

Prima di tentare di installare axe, assicurarsi che i seguenti requisiti siano soddisfatti.

Sistema operativo

Axe è progettato per funzionare su RHEL7 o RHEL8. Nessun altro sistema operativo è attualmente supportato.

Prima di installare axe, si prevede che il sistema sia stato aggiornato tramite:

yum update -y

Requisiti hardware

I nostri test di carico hanno dimostrato che un AWS t2.micro è in grado di supportare una piccola base di utenti (circa 25 utenti) senza mettere un carico significativo sull'applicazione. Non raccomandiamo di distribuire axe su un server che non abbia specifiche equivalenti a un t2.micro.

Se hai una base di utenti più ampia, fai riferimento alla tabella qui sotto per le raccomandazioni.

Su qualsiasi dimensione di macchina, è richiesto un minimo di 15 GB di spazio di archiviazione fisico (spazio disco). Tuttavia, raccomandiamo 30+ GB.

Requisiti di rete

Attualmente axe non necessita di accesso di rete in uscita, a parte rispondere alle richieste fatte ad esso.

Axe aprirà le seguenti porte sul sistema dove è distribuito:

Se prevedi di eseguire PostgreSQL sulla stessa macchina di axe, la sua porta standard (5432) sarà aperta, ma non è accessibile da Internet esterno.

Requisiti DNS

Il DNS deve essere creato per axe. Questo DNS può essere dietro il firewall della tua azienda, nella tua rete privata, o accessibile a Internet pubblico. Per il nostro server axe privato, abbiamo un record A puntato a un'istanza EC2 nel nostro account AWS.

Il DNS di esempio utilizzato in questo documento è axe.mycompany.com.

Configurazione SELinux

Axe richiede che un singolo flag SELinux sia disabilitato:

setsebool -P httpd_can_network_connect 1

Questo permette a NGINX di agire come un reverse proxy e di rispondere alle richieste di rete in uscita.

Utenti

Si prevede che l'installatore venga eseguito come utente root. Se non puoi sudo su all'utente root, l'installazione fallirà.

L'installatore creerà i seguenti utenti:

Nessuno di questi utenti necessita di permessi elevati.

Dipendenze

L'installatore di axe include tutte le sue dipendenze. Il server axe è installato su non deve bisogno di accesso a Internet esterno per far funzionare axe.

Un'installazione di axe ha dipendenze forti dal seguente software:

• NGINX - Espone i server axe alla tua rete
• PostgreSQL - Archiviazione dati

Il server axe funziona tramite Node.js, ma Node non necessita di essere installato sul sistema.

NGINX

NGINX deve essere installato/configurato per inoltrare il traffico al server axe. È stata fornita una configurazione di esempio per NGINX (vedi axe-nginx-example.conf).

Gli RPM necessari per installare NGINX sono inclusi nell'installatore di axe. Per installare NGINX, esegui:

# 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

Il server axe utilizza PostgreSQL per l'archiviazione dei dati. Una connessione valida a PostgreSQL deve essere fornita all'installatore.

Axe supporta sia un PostgreSQL esterno (ad esempio un RDS ospitato da AWS) che un server PostgreSQL che gira sulla stessa macchina.

Gli RPM necessari per installare PostgreSQL sono inclusi nell'installatore di axe. Per installare PostgreSQL, esegui:

# 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

Esecuzione dell'installatore

L'installatore deve essere eseguito come utente root. Verifica di essere l'utente root eseguendo:

whoami

Se hai precedentemente estratto l'installatore, assicurati di svuotare la directory migrations:

rm -f installer/migrations/*.sql

L'installatore sarà fornito come un unico file (archivio): installer.tar.gz. Per estrarre l'archivio, esegui il seguente comando:

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

Ciò risulterà in una struttura simile a:

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

Una volta estratto, il passo successivo è eseguire il programma installer/installer.

Configurazione dell'installatore

Molte opzioni di configurazione sono necessarie per configurare l'installatore. La seguente tabella spiega ogni flag CLI da passare al programma installer.

Note sui flag di configurazione

• --migration-directory dovrebbe puntare alla directory in cui l'archivio tar dell'installer è stato estratto più /migrations. Questo può probabilmente essere $PWD/migrations.
• --address è il DNS preconfigurato per l'installazione di axe.
• --allowed-email-domains può essere impostato se l'installazione di axe dovrebbe consentire l'uso solo da domini email specifici (es. *@mycompany.com).
• --extension-id predefinisce tutti i conosciuto ID di estensione axe (inclusi Chrome ed Edge).
• --database-encryption-key deve essere lungo 32 caratteri.
• --database-encryption-iv deve essere lungo 16 caratteri.

Variabili d'ambiente

Ognuno di questi flag di configurazione può essere impostato da variabili d'ambiente con il formato:

AXE_DEVTOOLS_INSTALLER_{flag name}

Dove {flag name} è la variante in maiuscolo snake case del flag di configurazione. Ad esempio, --auth-service-admin-client-id può essere fornito utilizzando la variabile d'ambiente AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_ADMIN_CLIENT_ID.

Inoltre, un file .env nella stessa directory di lavoro da cui viene eseguito l'installatore verrà caricato, abilitando quanto segue:

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

Configurazione di esempio

Configurazioni di esempio per l'installazione di axe DevTools.

Flag da riga di comando

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

Variabili d'ambiente (.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"

Note

Registrazione

I registri sono attualmente inviati a stdio. I registri vengono ruotati in base alla configurazione del sistema (non decisa da axe stessa).

Possono essere recuperati con journalctl. Ad esempio:

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

Stato del sistema

Per visualizzare lo stato completo del sistema, utilizzare systemctl:

systemctl status

Per vedere lo stato del servizio axe, eseguire:

systemctl status axe

Avvio / Arresto dei servizi Axe

Per avviare/fermare un servizio, utilizzare systemctl:

systemctl stop axe
systemctl start axe

Certificati TLS/SSL Autofirmati

Se vengono utilizzati certificati TLS/SSL autofirmati, AXE_DEVTOOLS_INSTALLER_ACCEPT_SELF_SIGNED_TLS=true o il --accept-self-signed-tls=true devono essere impostati.

Apprendimento automatico (ML)

Per impostazione predefinita, i miglioramenti ML delle estensioni di axe DevTools sono abilitati.

Per eseguire la funzionalità ML, il Server DevTools di axe (Portale Account di axe) comunica con il ML service che a sua volta comunica con il Sagemaker instance. Sagemaker esegue l'inferenza di visione artificiale utilizzata per ridurre il lavoro manuale negli IGT. Il servizio ML gestisce tutti i dati immagine usati per l'inferenza e per altri scopi - come le schermate dei problemi - e conserva i dati per un uso a lungo termine.

SageMaker non memorizza alcun dato, ed è pertanto consigliato che tutti i clienti consentano alle loro istanze di comunicare con il modello ospitato centralmente. Un cliente può richiedere che questa funzionalità sia disabilitata. Se ciò avviene, perderanno l'accesso ai miglioramenti del modello ML nel prodotto che possono aiutare a ottimizzare i loro test e a automatizzare compiti che altrimenti sarebbero manuali. Le schermate dei problemi condivise e l'analisi automatica del contrasto dei colori continueranno a funzionare senza SageMaker.

Le istanze private e on-prem possono supportare le funzionalità ML puntando l'istanza a un'istanza di servizio ML (che potrebbe essere condivisa o non condivisa) tramite la variabile d'ambiente ML_SERVICE (l'URL del servizio di ML) e impostando la variabile d'ambiente ML_SERVICE_API_KEY con una chiave API valida.

Funzionalità di apprendimento automatico

• Schermate dei problemi (possono essere visualizzate sulla pagina di condivisione dei problemi)
• Strumento di revisione automatica del contrasto dei colori
• Rilevazione automatica del ruolo degli elementi
• Rilevamento automatico dell'etichetta di input

Autenticazione

È richiesto il SSO di Deque affinché gli utenti possano accedere all'applicazione. Questo servizio SSO può essere condiviso tra più prodotti Deque e può essere impostato in diversi modi. Come documentato sopra, ci sono una serie di variabili d'ambiente AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_* che abilitano l'estensione di axe DevTools a consentire agli utenti di accedere all'applicazione.