On-premises Installation Instructions

This document describes the process of installing axe DevTools in an on-premises location.

Requirements

Before attempting to install axe, be sure the following requirements are met.

Operating System

Axe is designed to run on RHEL7. No other operating systems are currently supported.

Before installing axe, it is expected that your system has been updated via:

yum update -y

Hardware Requirements

Our load testing has proven that a AWS t2.micro is capable of supporting a small user base (about 25 users) without putting significant load on the application. We do not recommend deploying axe to a server that does not have equivalent specs as a t2.micro.

If you have a larger user base, refer to the below table for recommendations.

On any machine size, a minimum of 15 GB of physical storage (drive space) is required. We recommend 30+ GB however.

Network Requirements

Axe currently does not need outgoing network access, other than to respond to requests made to it.

Axe will open the following ports on the system it is deployed to:

If you plan on running PostgreSQL on the same machine as axe, its standard port (5432) will be opened, but is not accessible from the outside Internet.

DNS Requirements

DNS must be created for axe. This DNS may be behind your company's firewall, in your own private network, or accessible to the public Internet. For our private axe server, we have an A record pointed at an EC2 instance in our AWS account.

The example DNS used in this document is axe.mycompany.com.

SELinux Configuration

Axe requires a single SELinux flag to be disabled:

setsebool -P httpd_can_network_connect 1

This enables NGINX to act as a reverse proxy and to respond to outgoing network requests.

Users

The installer is expected to be run as the root user. If you cannot sudo su to the root user, the installer will fail.

The installer will create the following users:

None of these users need elevated permissions.

Dependencies

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

An axe deployment has hard dependencies on the following software:

• NGINX - Exposes the axe servers to your network
• PostgreSQL - Data storage

The axe server runs via Node.js, but Node does not need to be installed on the system.

NGINX

NGINX needs to be installed/configured to forward traffic to the axe server. An example NGINX configuration has been provided (see axe-nginx-example.conf).

The necessary RPMs for installing NGINX are included in the axe installer. To install NGINX, do:

# 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

The axe server uses PostgreSQL for data storage. A valid connection to PostgreSQL must be provided to the installer.

Axe supports both an external PostgreSQL (eg an RDS hosted by AWS), or a PostgreSQL server running on the same machine.

The necessary RPMs for installing PostgreSQL are included in the axe installer. To install PostgreSQL, do:

# 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

Running the Installer

The installer must be run as the root user. Verify you are the root user by running:

whoami

The installer will be delivered as a single (archive) file: installer.tar.gz. To extract the archive, run the following:

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

This will result in structure similar to:

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

Once extracted, the next step is to run the installer/installer program.

Installer Configuration

Many configuration flags are needed in order to configure the installer. The following table explains each CLI flag to passed to the installer program.

Configuration Flag Notes

• --migration-directory should point to the directory the installer tarball was extracted to plus /migrations. This can likely be $PWD/migrations.
• --address is the pre-configured DNS for the axe installation.
• --allowed-email-domains may be set if your axe installation should only allow usage from specific email domains (eg *@mycompany.com).
• --extension-id defaults to all known axe extension IDs (including Chrome and Edge).
• --database-encryption-key must be 32 characters long.
• --database-encryption-iv must be 16 characters long.

Environment Variables

Each of these configuration flags may be set by environment variables with the format of:

AXE_DEVTOOLS_INSTALLER_{flag name}

Where {flag name} is the upper snake case variant of the configuration flag. For example, --auth-service-admin-client-id may be provided by using the AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_ADMIN_CLIENT_ID environment variable.

Additionally, a .env file in the same working directory the installer is run from will be loaded, enabling the following:

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

Example Configuration

Sample configurations for installing axe DevTools.

Command Line 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" \
  --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"

Environment Variables (.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"
ML_SERVICE_API_KEY="your-api-key"
ML_SERVICE_URL="https://axe-ml.deque.com"
ML_SERVICE_TIMEOUT="30000"

Notes

Logging

Logs are currently sent to stdio. Logs are rotated based on your system configuration (not dictated by axe itself).

They can be retrieved with journalctl. For example:

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

System Status

To see the entire system status, use systemctl:

systemctl status

To see the status of the axe service, do:

systemctl status axe

Starting / Stopping Axe Services

In order to start/stop a service, use systemctl:

systemctl stop axe
systemctl start axe

Machine Learning (ML)

By default, the axe DevTools Extensions's ML enhancements are enabled.

In order to perform the ML functionality, the axe DevTools Server (axe Account Portal) communicates with the ML service which in turn communicates with the Sagemaker instance. Sagemaker performs the machine vision inference that is used to reduce the amount of manual work in IGTs. The ML service handles all the image data that is used for inference and for other purposes - like issue screenshots - and stores the data for long term use.

SageMaker doesn’t store any data, and it is therefore recommended that all customers allow their instances to communicate with the centrally hosted model. A customer can request this feature to be disabled. If this is done, they will lose access to the ML model enhancements in the product that can help optimize their testing and automate otherwise manual tasks. The shared issue screenshots and color contrast analysis would continue to function without SageMaker.

Private and on-prem instances can support ML features by pointing the instance at a ML service instance (this could be shared or not shared) via the ML_SERVICE environment variable (the URL of the ML service) and setting the ML_SERVICE_API_KEY env var with a valid API key.

Machine Learning Features

• Issue screenshots (can be viewed on share issue page)
• Automatic Color Contrast Review tool
• Automatic element Role detection
• Automatic input label detection

Authentication

Deque SSO is required in order for users to log in to the application. This SSO service can be shared between multiple Deque products and can be stood up in a number of ways. As documented above, there are a number of AXE_DEVTOOLS_INSTALLER_AUTH_SERVICE_* environment variables that enable the axe DevTools Extension to allow users to log in to the application.