{"type":"doc","content":[{"type":"extension","attrs":{"layout":"full-width","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"markdown","parameters":{"macroParams":{"__bodyContent":{"value":"- [Introduction](#introduction)\n - [Target Audience](#target-audience)\n - [End User License Agreement](#end-user-license-agreement)\n- [Prerequisites](#prerequisites)\n - [Gateway Hostname](#gateway-hostname)\n - [Hardware Requirements](#hardware-requirements)\n - [Operating System](#operating-system)\n - [Root User](#root-user)\n - [Docker](#docker)\n - [PowerShell](#powershell)\n - [HTTPS](#https)\n - [Gateway Basic Auth Password](#gateway-basic-auth-password)\n - [Service User](#service-user)\n - [Installation Directory](#installation-directory)\n- [Installing](#installing)\n - [Running the Install Script](#running-the-install-script)\n - [Smart Classifier ML](#smart-classifier-ml)\n - [Gateway](#gateway)\n - [Enable Smart Classifier Feature](#enable-smart-classifier-feature)\n - [Major Version Upgrades](#major-version-upgrades)\n - [Upgrading from major version 5 to 6](#upgrading-from-major-version-5-to-6)\n- [Starting and Stopping](#starting-and-stopping)\n - [Stopping](#stopping)\n - [Starting](#starting)\n\n# Introduction\nThe Smart Classifier ML is a set of APIs for training machine learning (ML) models and making predictions based on these models. The Smart Classifier ML APIs are required by the Smart Classifier feature in the Saga platform.\n\n## Target Audience\nThis guide is directed towards system administrators that are to install the Smart Classifier ML.\n\n## End User License Agreement\nBy installing the software one is accepting the [End User License Agreement](https://www.ayfie.com/hubfs/terms/eula.pdf).\n\n# Prerequisites\n\n## Gateway Hostname\nThe first prerequisite to fulfill is to decide the Smart Classifier ML API's Gateway Hostname. Other prerequisites as well as the Saga install script depend on knowing it. Using the FQDN of the Smart Classifier ML host is the easiest alternative as setting it to anything else will require a DNS entry.\n\n## Hardware Requirements\nThe more CPU cores, the faster ML model training.\n|CPU Speed|CPU Cores |RAM | Drive Size|\n|:-------:|:----------:|:------:|:---------:|\n| ~2 GHz| 4| 8 GB| 50 GB|\n\n## Operating System\nTested on Ubuntu 22.04.\n\n## Root User\nA root user is required to install the prerequisites for Smart Classifier ML. All *sudo* commands in the sections below needs to be run as the root user.\n\n## Docker\nInstall Docker:\n```\nsudo apt-get update\n\nsudo apt-get install ca-certificates curl gnupg lsb-release\n\nsudo mkdir -p /etc/apt/keyrings\n\ncurl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg\n\necho \\\n \"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \\\n $(lsb_release -cs) stable\" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null\n\nsudo apt-get update\n\nsudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin\n```\n\n## PowerShell\nThe Smart Classifier ML install script requires that PowerShell is installed. Consult [Install PowerShell on Ubuntu](https://learn.microsoft.com/en-us/powershell/scripting/install/install-ubuntu?view=powershell-7.2) on this.\n\n## HTTPS\nThe Smart Classifier ML APIs require the use of the HTTPS protocol. To facilitate that, the Smart Classifier ML APIs need to be set up with an SSL certificate. The prerequisite for this depends on how the certificate is to be provided:\n\n- Received from a commercial Certificate Authority (CA) such as for instance IdenTrust, DigiCert, Sectigo, GoDaddy, etc.\n- Automatically generated by Let’s Encrypt during the Smart Classifier ML installation\n\nThe prerequisites in regard to the first option are:\n- two PEM formatted files, \\.crt and \\.key.\n- the \\.crt has [Gateway Hostname](#gateway-hostname) set in the Subject Alternative Name attribute. This applies even if there technically are no alternative names.\n- the \\.key has an unencrypted private key.\n\nSee [Obtaining Correctly Formatted SSL Certificate Files](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2987327489/Obtaining+Correctly+Formatted+SSL+Certificate+Files) for details.\n\nThe two files are to be placed into directory _/var/ayfie/smart-classifier-ml/volumes/traefik/certs_ during installation.\n\nThe prerequisites in regard to the second option of using Let’s Encrypt's are network related:\n\n- One is using an approved public Top Level Domain (TLD)\n- The Smart Classifier ML server is exposed to the public Internet\n- The firewall is open for port 80 on the Smart Classifier ML host\n- There is a DNS A record entry for the Smart Classifier ML host FQDN and its public IP\n\n## Gateway Basic Auth Password\nThe Smart Classifier APIs are secured with Basic Auth in the Gateway. The Basic Auth user is set to *smart-classifier-ml*. The Basic Auth password needs to be generated and hashed using MD5, SHA1, or BCrypt. That can on Ubuntu be done this way:\n```\nsudo apt-get install apache2-utils\n```\n\nReplace *\\* and run the command:\n```\nhtpasswd -nb smart-classifier-ml \\\n```\n\nThe command output will be something like this:\n```\nsmart-classifier-ml:$apr1$fhrtmbJR$og2srnFdPPFpDiTaFUOxZ0\n```\n\nCopy the *\\* and the encrypted password (*$apr1$fhrtmbJR$og2srnFdPPFpDiTaFUOxZ0* One should run the Smart Classifiin our example above) as both will be required later, the *\\* when enabling the Smart Classifier feature in the Saga install script and the encrypted password when running the Smart Classifier ML install script.\n\n## Service User\nOne should run the Smart Classifier ML installer as a non-root service user. Create the non-root service user with these commands after having replaced *\\*:\n```\nsudo useradd \nsudo passwd \n```\n\nThis service user needs to be member of the *docker* group to run the installer without *sudo*. Add the service user to the *docker* group:\n ```\n sudo usermod -a -G docker \n ```\n\nThe *uid* of the service user and the *gid* of the *docker* group will be required later when [installing](#installing).\n\nThen log in as the service user:\n ```\n su \n ```\n\nTake note of the *uid* of the service user and the *gid* of the docker group from the output of the command below, they will be required later:\n ```\n id\n ```\n\nThen log back out to the root user:\n ```\n exit\n ```\n\n## Installation Directory\n\nRun the command below to create the install directory for Smart Classifier ML:\n ```\n sudo mkdir -p /var/ayfie/smart-classifier-ml\n ```\nGrant permissions with these commands after having replaced *\\* with the service user:\n ```\n sudo chown :docker /var/ayfie/smart-classifier-ml\n sudo chmod g+s /var/ayfie/smart-classifier-ml\n ```\n\n# Installing\nNew versions of the Smart Classifier ML is released using the continuous delivery approach. The Smart Classifier ML is versioned using semantic versioning. When new versions within the same major version are released, *the smart-classifier-ml.ps1* script will discover that a new version is available and automatically upgrade to that new minor version.\n\n## Running the Install Script\n\nLog in as the service user with this command:\n ```\n su \n ```\n\nDownload the Smart Classifier ML installs script:\n ```\n cd /var/ayfie/smart-classifier-ml\n wget https://nexus.ayfie.dev/repository/Raw-Hosted/smart-classifier-ml-releases/6/smart-classifier-ml.ps1\n ```\nRun the install script:\n ```\n pwsh smart-classifier-ml.ps1\n ```\n\nIn the install script menu, fill in the information obtained in the prerequisites sections.\n\nThe full menu looks like this:\n```\nYour customized configuration values. Please choose from the list below to change.\n Smart Classifier ML UID:\n Smart Classifier ML GID:\n Smart Classifier ML Worker Count: 5\n Gateway Host Name:\n Gateway Basic Auth Password:\n Gateway Certificate Name:\n Gateway Certificates Resolver:\n Gateway Acme Email:\n```\n\nValues at the end of each line are default values except for some of the blank cases that have to be set (see below). The script will keep returning to the menu upon exiting it until all required fields are set.\n\nNavigate the fields using the up and down arrow keys and press enter to edit, or as in some cases, to toggle the field value.\n\n### Smart Classifier ML\n\n- **Smart Classifier ML UID:** The *uid* of the service user, see the [Service User](#service-user) section.\n- **Smart Classifier ML GID:** The *gid* of the *docker* group, see the [Service User](#service-user) section.\n- **Smart Classifier ML Worker Count:** The number of *uvicorn* workers. *uvicorn* is the web server hosting the Smart Classifier ML APIs.\n\n\n### Gateway\nThe table below shows the field values to be set based on the type of certificate one is using (see section [HTTPS](#https) for further details):\n\n| | Certificate Authority provided | Let's Encrypt generated |\n|:-----------------------------------|:--------------------------------------|:---------------------------------------|\n| **Gateway Host Name:** | [Gateway Hostname](#gateway-hostname) | [Gateway Hostname](#gateway-hostname) |\n| **Gateway Certificate Name:** | the \\ of \\.crt | |\n| **Gateway Certificates Resolver:** | | \"letsencrypt\" |\n| **Gateway Acme Email:** | | contact email |\n\nA quoted value means that it is to be used as-is (but without the quotes). Empty fields means to leave the menu field empty.\n\n## Enable Smart Classifier Feature\nConsult the *Smart Classifier* section of the [Installation Guide](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2400714758/Ayfie+Locator+Installation+Guide) for how to enable the Smart Classifier feature. See also the *Managing Users and Roles* section for how to grant the *search.smart-classifier* permission to users that are to manage the Smart Classifiers.\n\n## Major Version Upgrades\n\nTo upgrade to a new major version, a *smart-classifier-ml.ps1* install script for that new major version is required. Section [Running the Install Script](#running-the-install-script) describes how to obtain the installer for any given major version.\n\n### Upgrading from major version 5 to 6\n\n1. Stop Smart Classifier ML, see [Stopping](#stopping).\n2. Run the following commands to delete the current version of the install script (the path assumes recommended install directory):\n ```\n > cd /var/ayfie/smart-classifier-ml\n > rm smart-classifier-ml.ps1\n ```\n3. Download and run the 6.x version of the *smart-classifier-ml.ps1* install script, see [Running the Install Script](#running-the-install-script).\n\n# Starting and Stopping\n\nA start or restart of the Smart Classifier ML requires a subsequent restart of Saga. That Saga restart should not be performed before the Smart Classifier ML services are up and running.\n\n## Stopping\n\nUse this command to start Smart Classifier ML:\n\n```\n> pwsh stop-smart-classifier-ml.ps1\n```\n\n\n## Starting\n\n```\n> pwsh smart-classifier-ml.ps1\n```\n\nThe *smart-classifier-ml.ps1* script checks for updates, and if any compatible newer version is detected, the script will perform the upgrade before starting Smart Classifier ML.\n"}},"macroMetadata":{"macroId":{"value":"f23e139c-2e69-4eaf-b7d4-5773e3e43ab6"},"schemaVersion":{"value":"1"},"placeholder":[{"type":"icon","data":{"url":"https://d27i9fmzbobp10.cloudfront.net/markdown-mark.png"}}],"title":"Markdown"}}}}],"version":1}

Ayfie Smart Classifier ML Install Guide