Install Guide

The Site-Wide Analysis Tool provides 24/7 real-time performance monitoring, reports, and recommendations to ensure the security and operability of Adobe Commerce on cloud infrastructure installations. It also provides detailed information about available and installed patches, third-party extensions, and your Adobe Commerce installation.

INFO

Learn how to enable the Site-Wide Analysis Tool and generate reports.

If you have an on-premises installation of Adobe Commerce, install an agent on your infrastructure to use the tool. You do not need to install the agent on Adobe Commerce on cloud infrastructure projects.

Agent

The Site-Wide Analysis Tool Agent allows you to use the Site-Wide Analysis Tool for on-premises installations of Adobe Commerce.

The Site-Wide Analysis Tool Agent collects application and business data, analyzes it, and provides additional insights about the health of your installation so that you can improve customer experience. It monitors your application and helps you identify performance, security, availability, and application issues.

Installing the agent requires the following steps:

  1. Verify system requirements.

  2. Configure API keys in the Commerce Services Connector extension.

  3. Install the agent.

  4. Run the agent.

INFO

The agent supports multi-node Adobe Commerce installations. Install and configure the agent on each node.

System requirements

Your on-premises infrastructure must meet the following requirements before installing the agent:

  • Operating systems

    • Linux x86-64 distributions, such as Red Hat® Enterprise Linux (RHEL), CentOS, Ubuntu, Debian, and similar
    IMPORTANT

    Adobe Commerce is not supported on Microsoft Windows or macOS.

  • Adobe Commerce 2.4.1 or later

  • Commerce Services Connector extension

  • PHP CLI

  • Bash/shell utilities

    • php

    • wget

    • awk

    • nice

    • grep

    • openssl

Commerce Services Connector

The agent requires the Commerce Services Connector extension to be installed on your system and configured with API keys. To verify that the extension is installed, run the following command:

bin/magento module:status Magento_ServicesConnector

If you have installed the extension and configured it using an existing API key for a different service, you MUST regenerate the API key and update it in the Adobe Commerce Admin for the agent.

  1. Put your website into maintenance mode.

  2. Log into account.magento.com.

    NOTE

    If you have trouble accessing your account, see Unable to log in to Adobe Commerce support or cloud account for troubleshooting help.

  3. Click API Portal.

  4. Click Delete next to the existing API Key.

  5. Configure a new API key.

IMPORTANT

If you generate new keys in the API Portal, immediately update the API keys in the Admin configuration. If you generate new keys and do not update the keys in the Admin, your SaaS extensions will no longer work and you will lose valuable data.

If the extension is not installed, use the following instructions to install it:

  1. Add the extension to your composer.json file and install it.

    composer require magento/services-connector:1.*
    
  2. Enable the extension.

    bin/magento module:enable Magento_ServicesConnector
    
  3. Update the database schema.

    bin/magento setup:upgrade
    
  4. Configure API Keys to connect the extension to your system.

Install the agent

We have created a shell script to simplify installation. We recommend using the shell script, but you can follow the manual installation method if necessary.

INFO

After the agent is installed, it will self-update when a new release is available.

Scripted

  1. Download and execute the shell script.

    bash -c "$(wget -qO - https://raw.githubusercontent.com/magento-swat/install-agent-helpers/main/install.sh)"
    
    TIP

    We recommend installing the agent outside of your root Adobe Commerce project directory.

  2. Verify installation.

    ./scheduler -v
    
    Version: 1.0.1
    Success exit.
    
  3. After downloading and installing the agent, configure it to run using one of the following methods:

Manual

If you do not want to use our shell script to install the agent, then you must manually install it by following these steps:

  1. Create a directory where you want to download the agent.

    TIP

    We recommend installing the agent outside of your root Adobe Commerce project directory.

  2. Download the binary file and unpack it.

    INFO

    To use the Site-Wide Analysis Tool, you must first read and accept the Terms of Use that are presented when you access the dashboard from the Adobe Commerce Admin.

    For the AMD64 architecture:

    1. Download the launcher archive.

      curl -O https://updater.swat.magento.com/launcher/launcher.linux-amd64.tar.gz
      
    2. Unpack the launcher archive.

      tar -xf launcher.linux-amd64.tar.gz
      

    For the ARM64 architecture:

    1. Download the launcher archive.

      curl -O https://updater.swat.magento.com/launcher/launcher.linux-arm64.tar.gz
      
    2. Unpack the launcher archive.

      tar -xf launcher.linux-arm64.tar.gz
      
  3. (Optional) Verify the signature for the checksum file.

    echo -n "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQ0lqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FnOEFNSUlDQ2dLQ0FnRUE0M2FBTk1WRXR3eEZBdTd4TE91dQpacG5FTk9pV3Y2aXpLS29HendGRitMTzZXNEpOR3lRS1Jha0MxTXRsU283VnFPWnhUbHZSSFhQZWt6TG5vSHVHCmdmNEZKa3RPUEE2S3d6cjF4WFZ3RVg4MEFYU1JNYTFadzdyOThhenh0ZHdURVh3bU9GUXdDcjYramFOM3ErbUoKbkRlUWYzMThsclk0NVJxWHV1R294QzBhbWVoakRnTGxJUSs1d1kxR1NtRGRiaDFJOWZqMENVNkNzaFpsOXFtdgorelhjWGh4dlhmTUU4MUZsVUN1elRydHJFb1Bsc3dtVHN3ODNVY1lGNTFUak8zWWVlRno3RFRhRUhMUVVhUlBKClJtVzdxWE9kTGdRdGxIV0t3V2ppMFlrM0d0Ylc3NVBMQ2pGdEQzNytkVDFpTEtzYjFyR0VUYm42V3I0Nno4Z24KY1Q4cVFhS3pYRThoWjJPSDhSWjN1aFVpRHhZQUszdmdsYXJSdUFacmVYMVE2ZHdwYW9ZcERKa29XOXNjNXlkWApBTkJsYnBjVXhiYkpaWThLS0lRSURnTFdOckw3SVNxK2FnYlRXektFZEl0Ni9EZm1YUnJlUmlMbDlQMldvOFRyCnFxaHNHRlZoRHZlMFN6MjYyOU55amgwelloSmRUWXRpdldxbGl6VTdWbXBob1NrVnNqTGtwQXBiUUNtVm9vNkgKakJmdU1sY1JPeWI4TXJCMXZTNDJRU1MrNktkMytwR3JyVnh0akNWaWwyekhSSTRMRGwrVzUwR1B6LzFkeEw2TgprZktZWjVhNUdCZm00aUNlaWVNa3lBT2lKTkxNa1cvcTdwM200ejdUQjJnbWtldm1aU3Z5MnVMNGJLYlRoYXRlCm9sdlpFd253WWRxaktkcVkrOVM1UlNVQ0F3RUFBUT09Ci0tLS0tRU5EIFBVQkxJQyBLRVktLS0tLQ==" | base64 -d > release.pub
    
    openssl dgst -sha256 -verify release.pub -signature launcher.sha256 launcher.checksum
    
  4. (Optional) Verify the checksum.

    shasum -a 512 -c launcher.checksum
    
  5. Create the config.yaml file with the following contents.

    project:
      appname: "Acme Inc" # Company or site name that you provided when installing the agent
    application:
      phppath: php # Path to your PHP CLI interpreter (usually /usr/bin/php)
      magentopath: /var/www/html/example.com # Root directory where your Adobe Commerce application is installed (usually /var/www/html)
      checkregistrypath: /path/to/swat-agent/tmp # Temporary directory for the agent (usually /usr/local/swat-agent/tmp)
      issandbox: false # Enabling sandbox mode to use the agent on staging environment (true or false)
      database:
        user: your-adobe-commerce-db-username # Database user for your Adobe Commerce installation
        password: your-password # Database password for the specified user for your Adobe Commerce installation
        host: 127.0.0.1 # Database host for your Adobe Commerce installation
        dbname: your-adobe-commerce-db-name # Database name for your Adobe Commerce installation
        port: 3306 # Database port for your Adobe Commerce installation (usually 3306)
        tableprefix: # Table Prefix for your Adobe Commerce installation (default value: empty)
     enableautoupgrade: true # Enables automatic upgrade (restart required after an upgrade; agent does not check for upgrades if the option is disabled; true or false)
     runchecksonstart: true # Collect data on the first run (Usually 1)
     loglevel: error # Determines what events are logged based on severity (usually error)
    
  6. Verify the installation.

    scheduler -v
    
    Version: 1.0.1
    Success exit.
    
  7. After downloading and installing the agent, you must configure it to run using one of the following methods:

Run the agent

We recommend configuring the agent to run as a service. If you have limited access to your infrastructure and do not have root permissions, then you must use cron instead.

Service

  1. Create a systemd unit file (/etc/systemd/system/scheduler.service) with the following configuration (replace <filesystemowner> with the UNIX® user that owns the directory where the agent and the Adobe Commerce software are installed). If you downloaded the agent as the root user, change the directory and nested files owner.

    [Unit]
    Wants=network.target
    After=network.target
    
    [Service]
    Type=simple
    User=<filesystemowner>
    ExecStart=/path/to/agent/scheduler
    Restart=always
    RestartSec=3
    
    [Install]
    WantedBy=multi-user.target
    
  2. Launch the service.

    systemctl daemon-reload
    
    systemctl start scheduler
    
    systemctl enable scheduler
    
  3. Validate that the service is up and running.

    journalctl -u scheduler | grep "Application is going to update" | tail -1 && echo "Agent is successfully installed"
    

Cron

If you do not have root permissions or do not have permissions to configure a service as root, you can use cron instead.

Update your cron schedule:

( crontab -l ; echo "* * * * * flock -n /tmp/swat-agent.lockfile -c '/path/to/agent/scheduler' >> /path/to/agent/errors.log 2>&1" ) | sort - | uniq - | crontab -

Uninstall

Run the following commands to uninstall the service from your system and remove all generated files:

  1. Stop the scheduler.

    systemctl stop scheduler
    
  2. Disable the scheduler.

    systemctl disable scheduler
    
  3. Remove the scheduler service’s systemd unit file.

    rm /etc/systemd/system/scheduler.service
    
  4. Reload the systemd manager configuration.

    systemctl daemon-reload
    
  5. Reset any systemd units from a failed state.

    systemctl reset-failed
    
  6. Remove the scheduler service directory.

    rm -rf <CHECK_REGISTRY_PATH> #see SWAT_AGENT_APPLICATION_CHECK_REGISTRY_PATH in /etc/systemd/system/scheduler.service
    
  7. Remove the scheduler binary file.

    rm /usr/local/bin/scheduler
    

If you configured the agent to run with cron instead, use the following instructions:

  1. Remove the agent from the crontab list.

    crontab -e
    
  2. Stop the running job.

    ps aux | grep scheduler
    
  3. Remove the directory where you installed the agent.

    rm -rf swat-agent
    

Override the configuration file

You can override the values that you specified in the configuration file during installation by using environment variables. This preserves backward compatibility with earlier versions of the agent. See the following table for recommended values:

PROPERTY DESCRIPTION
SWAT_AGENT_APP_NAME Company or site name that you provided when installing the agent
SWAT_AGENT_APPLICATION_PHP_PATH Path to your PHP CLI interpreter (usually /usr/bin/php)
SWAT_AGENT_APPLICATION_MAGENTO_PATH Root directory where your Adobe Commerce application is installed (usually /var/www/html)
SWAT_AGENT_APPLICATION_DB_USER Database user for your Adobe Commerce installation
SWAT_AGENT_APPLICATION_DB_PASSWORD Database password for the specified user for your Adobe Commerce installation
SWAT_AGENT_APPLICATION_DB_HOST Database host for your Adobe Commerce installation
SWAT_AGENT_APPLICATION_DB_NAME Database name for your Adobe Commerce installation
SWAT_AGENT_APPLICATION_DB_PORT Database port for your Adobe Commerce installation (usually 3306)
SWAT_AGENT_APPLICATION_DB_TABLE_PREFIX Table Prefix for your Adobe Commerce installation (default value: empty)
SWAT_AGENT_APPLICATION_DB_REPLICATED Whether your Adobe Commerce installation has a secondary database instance (usually false)
SWAT_AGENT_APPLICATION_CHECK_REGISTRY_PATH Temporary directory for the agent (usually /usr/local/swat-agent/tmp)
SWAT_AGENT_RUN_CHECKS_ON_START Collect data on the first run (usually 1)
SWAT_AGENT_LOG_LEVEL Determines what events are logged based on severity (usually error)
SWAT_AGENT_ENABLE_AUTO_UPGRADE Enables automatic upgrade (restart required after an upgrade; agent does not check for upgrades if the option is disabled; true or false)
SWAT_AGENT_IS_SANDBOX=false Enabling sandbox mode to use the agent on staging environment

On this page