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.

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.

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.5-p1 or later (due to the dependency of Service Connector)

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

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.

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

2. Enable the extension.

   bin/magento module:enable Magento_ServicesId
   

3. Update the database schema.

   bin/magento setup:upgrade
   

4. Clear the cache.

   bin/magento cache:clean
   

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

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:

   • Service (preferred if you have root access)

   • Cron

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.supportinsights.adobe.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.supportinsights.adobe.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:

   • Service (preferred if you have root access)

   • Cron

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

Troubleshooting

Access keys not parsed properly

You may see the following error if your access keys are not parsed properly:

ERRO[2022-10-10 00:01:41] Error while refreshing token: error while getting jwt from magento: invalid character 'M' looking for beginning of value
FATA[2022-12-10 20:38:44] bad http status from https://updater.supportinsights.adobe.com/linux-amd64.json: 403 Forbidden

To resolve this error, try the following steps:

1. Do a scripted install, save the output, and review the output for errors.
2. Review the generated config.yaml file and verify that the path to your Commerce instance and PHP is correct.
3. Make sure that the user that is running the scheduler is in the file system owner Unix group or is the same user as the file system owner.
4. Make sure that the Commerce Services Connector keys are installed correctly and try updating them to connect the extension to your system.
5. Uninstall the agent after updating the keys and reinstall using the install script.
6. Run the scheduler and see if you still receive the same error.
7. If you still receive the same error, increase the log level in the config.yaml to debug and open a Support ticket.

SIGFAULT Error

If you see a SIGFAULT error when running binary, you probably do not run this as the file owner of Adobe Commerce and Agent files.
To resolve, please check if all the files inside the agent directory that have the same user as the fileowner that Adobe Commerce files have, and binary should be run under that user as well.
You can use the chown command to change the files owner and switch to the appropriate user.
Make sure that your daemonization mechanism (Cron or System.d) runs the process under the appropriate user.