On-premises Installation Instructions

Link to On-premises Installation Instructions copied to clipboard

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


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.

Spec Requirement
CPU Cores 1
CPU Speed 3.3 GHz
Storage 15 GB

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

Users CPUs RAM (GB) AWS T2 Size
100 1 2 small
300 2 4 medium
500 4 8 large
700 8 16 xlarge
1000 8 32 2xlarge

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:

Port Number Accessible from Internet Purpose
80 yes Incoming HTTP traffic
443 yes Incoming HTTPS traffic (only when run in SSL mode)
3000 no Axe server

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.


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:

User Purpose
nginx runs the nginx-service
axe runs the axe-service
postgres runs the postgres-service

None of these users need elevated permissions.


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


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:


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.

Option Description
axe-database-name Database name for Axe
axe-database-password Password for the Axe database
master-database-name Master database name
master-database-user User for the master database
master-database-password Password for the master database user
master-database-host Host for the master database
master-database-port Port for the master database (defaults to 5432)
database-encryption-key 32 character key for database encryption
database-encryption-iv 16 character IV for database encryption
migration-directory Directory containing Axe database migrations
axe-user Name for the system user which will run the axe-service
extension-id Google Chrome Extension ID for the Axe Extension
address Address (URL) the Axe service will assume
cookie-secrets Secrets for signing Axe cookies (comma separated list)
allowed-email-domains Email domain whitelist (comma separated list)
auth-service-url Set the address to an existing auth-service deployment
auth-service-realm Realm name Axe will use
auth-service-admin-username Username for an existing "master" realm admin
auth-service-admin-password Password for an existing "master" realm admin
auth-service-axe-admin-username Username for the Axe admin user
auth-service-axe-admin-password Password for the Axe admin user
auth-service-public-client-id Public client ID for this Axe deployment
auth-service-confidential-client-id Confidential client ID for this Axe deployment
auth-service-admin-client-id Client ID for an existing admin client (usually "admin-cli")
ml-service-api-key API key for the Deque Machine Learning Service
ml-service-url URL for the Deque Machine Learning Service
ml-service-timeout Request timeout (in ms) for the Deque Machine Learning Service

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:


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:


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

Environment Variables (.env)




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


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.