DocumentationCommerceTools

Install Guide

Last update: Thu Apr 04 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Experienced
  • Admin
  • Developer
IMPORTANT
Effective April 23, 2024, the Site-Wide Analysis Tool will be decommissioned for all Adobe Commerce on-premises customers.

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
    note important
    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 note
    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.

    code language-bash 
    composer require magento/services-id

  2. Enable the extension.

    code language-bash 
    bin/magento module:enable Magento_ServicesId

  3. Update the database schema.

    code language-bash 
    bin/magento setup:upgrade

  4. Clear the cache.

    code language-bash 
    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.

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

Scripted

  1. Download and execute the shell script.

    code language-bash 
    bash -c "$(wget -qO - https://raw.githubusercontent.com/magento-swat/install-agent-helpers/main/install.sh)"
    note tip
    TIP
    We recommend installing the agent outside of your root Adobe Commerce project directory.

  2. Verify installation.

    code language-bash 
    ./scheduler -v
    code language-bash 
    Version: 1.0.1
Success exit.

  3. After downloading and installing the agent, configure it to run using one of the following methods:

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

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

  2. Download the binary file and unpack it.

    note info
    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.

      code language-bash 
      curl -O https://updater.supportinsights.adobe.com/launcher/launcher.linux-amd64.tar.gz

    2. Unpack the launcher archive.

      code language-bash 
      tar -xf launcher.linux-amd64.tar.gz

    For the ARM64 architecture:

    1. Download the launcher archive.

      code language-bash 
      curl -O https://updater.supportinsights.adobe.com/launcher/launcher.linux-arm64.tar.gz

    2. Unpack the launcher archive.

      code language-bash 
      tar -xf launcher.linux-arm64.tar.gz

  3. (Optional) Verify the signature for the checksum file.

    code language-bash 
    echo -n "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQ0lqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FnOEFNSUlDQ2dLQ0FnRUE0M2FBTk1WRXR3eEZBdTd4TE91dQpacG5FTk9pV3Y2aXpLS29HendGRitMTzZXNEpOR3lRS1Jha0MxTXRsU283VnFPWnhUbHZSSFhQZWt6TG5vSHVHCmdmNEZKa3RPUEE2S3d6cjF4WFZ3RVg4MEFYU1JNYTFadzdyOThhenh0ZHdURVh3bU9GUXdDcjYramFOM3ErbUoKbkRlUWYzMThsclk0NVJxWHV1R294QzBhbWVoakRnTGxJUSs1d1kxR1NtRGRiaDFJOWZqMENVNkNzaFpsOXFtdgorelhjWGh4dlhmTUU4MUZsVUN1elRydHJFb1Bsc3dtVHN3ODNVY1lGNTFUak8zWWVlRno3RFRhRUhMUVVhUlBKClJtVzdxWE9kTGdRdGxIV0t3V2ppMFlrM0d0Ylc3NVBMQ2pGdEQzNytkVDFpTEtzYjFyR0VUYm42V3I0Nno4Z24KY1Q4cVFhS3pYRThoWjJPSDhSWjN1aFVpRHhZQUszdmdsYXJSdUFacmVYMVE2ZHdwYW9ZcERKa29XOXNjNXlkWApBTkJsYnBjVXhiYkpaWThLS0lRSURnTFdOckw3SVNxK2FnYlRXektFZEl0Ni9EZm1YUnJlUmlMbDlQMldvOFRyCnFxaHNHRlZoRHZlMFN6MjYyOU55amgwelloSmRUWXRpdldxbGl6VTdWbXBob1NrVnNqTGtwQXBiUUNtVm9vNkgKakJmdU1sY1JPeWI4TXJCMXZTNDJRU1MrNktkMytwR3JyVnh0akNWaWwyekhSSTRMRGwrVzUwR1B6LzFkeEw2TgprZktZWjVhNUdCZm00aUNlaWVNa3lBT2lKTkxNa1cvcTdwM200ejdUQjJnbWtldm1aU3Z5MnVMNGJLYlRoYXRlCm9sdlpFd253WWRxaktkcVkrOVM1UlNVQ0F3RUFBUT09Ci0tLS0tRU5EIFBVQkxJQyBLRVktLS0tLQ==" | base64 -d > release.pub
    code language-bash 
    openssl dgst -sha256 -verify release.pub -signature launcher.sha256 launcher.checksum

  4. (Optional) Verify the checksum.

    code language-bash 
    shasum -a 512 -c launcher.checksum

  5. Create the config.yaml file with the following contents.

    code language-yaml 
    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.

    code language-bash 
    scheduler -v
    code language-bash 
    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 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 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.

    code language-config 
    [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.

    code language-bash 
    systemctl daemon-reload
    code language-bash 
    systemctl start scheduler
    code language-bash 
    systemctl enable scheduler

  3. Validate that the service is up and running.

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

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

    code language-bash 
    systemctl stop scheduler

  2. Disable the scheduler.

    code language-bash 
    systemctl disable scheduler

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

    code language-bash 
    rm /etc/systemd/system/scheduler.service

  4. Reload the systemd manager configuration.

    code language-bash 
    systemctl daemon-reload

  5. Reset any systemd units from a failed state.

    code language-bash 
    systemctl reset-failed

  6. Remove the scheduler service directory.

    code language-bash 
    rm -rf <CHECK_REGISTRY_PATH> #see SWAT_AGENT_APPLICATION_CHECK_REGISTRY_PATH in /etc/systemd/system/scheduler.service

  7. Remove the scheduler binary file.

    code language-bash 
    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.

    code language-bash 
    crontab -e

  2. Stop the running job.

    code language-bash 
    ps aux | grep scheduler

  3. Remove the directory where you installed the agent.

    code language-bash 
    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.

INFO
See How to Access Site-Wide Analysis Tool and generate reports.
recommendation-more-help
c2d96e17-5179-455c-ad3a-e1697bb4e8c3