Istruzioni per l'installazione on-premise

Questo documento descrive il processo di installazione di axe DevTools in una posizione on-premise.

Requisiti

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

Sistema operativo

Axe è progettato per funzionare su RHEL7 o RHEL8. Al momento non sono supportati altri sistemi operativi.

Prima di installare axe, è previsto che il sistema sia stato aggiornato tramite:

yum update -y

Requisiti hardware

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

Se la base utenti è più ampia, fare riferimento alla tabella sottostante per le raccomandazioni.

Indipendentemente dalle dimensioni della macchina, è richiesto un minimo di 15 GB di spazio di archiviazione fisica (spazio su disco). Tuttavia, consigliamo 30+ GB.

Requisiti di rete

Attualmente Axe non necessita di accesso alla rete in uscita, se non per rispondere alle richieste che gli vengono inoltrate.

Axe aprirà le seguenti porte sul sistema su cui viene distribuito:

Se si prevede di eseguire PostgreSQL sulla stessa macchina di axe, la sua porta standard (5432) verrà aperta, ma non sarà accessibile dall'esterno tramite Internet.

Requisiti DNS

Deve essere impostato un DNS per axe. Questo DNS potrebbe trovarsi dietro il firewall della tua azienda, nella tua rete privata o accessibile alla rete Internet pubblica. Per il nostro server axe privato, abbiamo un A record puntato a un'istanza EC2 nel nostro account AWS.

L'esempio DNS 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

Ciò consente a NGINX di agire come proxy inverso e di rispondere alle richieste di rete in uscita.

Gli utenti

Si prevede che il programma di installazione venga eseguito come root l'utente. Se non è possibile sudo su accedere root all'utente, l'installazione non riuscirà.

Il programma di installazione creerà i seguenti utenti:

Nessuno di questi utenti necessita di autorizzazioni elevate.

Dipendenze

Il programma di installazione di axe raggruppa tutte le sue dipendenze. Il server Axe è installato ** e non necessita** di accesso a Internet esterno per funzionare.

L'implementazione di axe ha forti dipendenze dal seguente software:

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

Il server axe funziona tramite Node.js, ma non è necessario che Node sia installato sul sistema.

NGINX

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

Gli RPM necessari per l'installazione di NGINX sono inclusi nel programma di installazione axe. Per installare NGINX, procedere come segue:

# 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. È necessario fornire al programma di installazione una connessione valida a PostgreSQL.

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

Gli RPM necessari per l'installazione di PostgreSQL sono inclusi nel programma di installazione axe. Per installare PostgreSQL, eseguire i seguenti passaggi:

# 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

Il programma di installazione deve essere eseguito come root utente. Verifica di essere root l'utente eseguendo:

whoami

Se hai già estratto il programma di installazione, assicurati di cancellare migrations la directory:

rm -f installer/migrations/*.sql

Il programma di installazione verrà consegnato come un singolo file (archivio): installer.tar.gz. Per estrarre l'archivio, esegui il seguente comando:

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

Ciò darà luogo a 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 installer/installer il programma.

Configurazione dell'installatore

Per configurare il programma di installazione sono necessari molti parametri di configurazione. La tabella seguente spiega ogni flag CLI da passare al installer programma.

Note sul flag di configurazione

• --migration-directory dovrebbe puntare alla directory in cui è stato estratto il tarball del programma di installazione /migrations. Probabilmente è così $PWD/migrations.
• --address è il DNS preconfigurato per l'installazione di axe.
• --allowed-email-domains può essere impostato se l'installazione di axe deve consentire l'utilizzo solo da domini di posta elettronica specifici (ad esempio *@mycompany.com).
• --extension-id per impostazione predefinita vengono utilizzati tutti gli ID delle estensioni axe conosciuti (inclusi Chrome ed Edge).
• --database-encryption-key **deve ** essere lungo 32 caratteri.
• --database-encryption-iv deve essere lungo 16 caratteri.

Variabili d'ambiente

Ciascuno di questi flag di configurazione può essere impostato da variabili di ambiente con il formato:

AXE_DEVTOOLS_INSTALLER_{flag name}

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

Inoltre, verrà caricato un .env file nella stessa directory di lavoro da cui viene eseguito il programma di installazione, abilitando quanto segue:

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

Esempio di configurazione

Configurazioni di esempio per l'installazione di axe DevTools.

Flag della 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" \
  --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"

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

Note

Registrazione

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

Possono essere recuperati con journalctl. Per 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 vedere lo stato completo del sistema, utilizzare systemctl:

systemctl status

Per vedere lo stato del servizio Axe, fare:

systemctl status axe

Avvio/Arresto Servizi di Axe

Per avviare/arrestare un servizio, utilizzare systemctl:

systemctl stop axe
systemctl start axe

Certificati TLS/SSL autofirmati

Se vengono utilizzati certificati TLS/SSL autofirmati, è necessario impostare AXE_DEVTOOLS_INSTALLER_ACCEPT_SELF_SIGNED_TLS=true o --accept-self-signed-tls=true.

Machine Learning (ML)

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

Per eseguire la funzionalità ML, axe DevTools Server (axe Account Portal) comunica con ML service che a sua volta comunica con Sagemaker instance. Sagemaker esegue l'inferenza della visione artificiale utilizzata per ridurre la quantità di lavoro manuale negli IGT. Il servizio ML gestisce tutti i dati delle immagini utilizzati per l'inferenza e per altri scopi, come gli screenshot dei problemi, e li archivia per un utilizzo a lungo termine.

SageMaker non memorizza alcun dato, pertanto si consiglia a tutti i clienti di consentire alle proprie istanze di comunicare con il modello ospitato centralmente. Il cliente può richiedere che questa funzione venga disattivata. In tal caso, perderanno l'accesso ai miglioramenti del modello ML nel prodotto che possono aiutarli a ottimizzare i test e ad automatizzare attività altrimenti manuali. Gli screenshot dei problemi condivisi e l'analisi del contrasto dei colori continuerebbero a funzionare anche senza SageMaker.

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

Funzionalità di apprendimento automatico

• Screenshot del problema (possono essere visualizzati nella pagina di condivisione del problema)
• Strumento di revisione automatica del contrasto dei colori
• Rilevamento automatico del ruolo dell'elemento
• Rilevamento automatico dell'etichetta di input

Autenticazione

Per consentire agli utenti di accedere all'applicazione è necessario Deque SSO. Questo servizio SSO può essere condiviso tra più prodotti Deque e può essere attivato in vari modi. Come documentato sopra, sono presenti numerose variabili di ambiente AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_* che consentono all'estensione axe DevTools di consentire agli utenti di accedere all'applicazione.