Page Comparison

- [Introduction](#introduction)
  - [Target Audience](#target-audience)
  - [End User License Agreement](#end-user-license-agreement)
- [Prerequisites](#prerequisites)
  - [Gateway Hostname](#gateway-hostname)
  - [Hardware Requirements](#hardware-requirements)
  - [Operating System](#operating-system)
  - [Root User](#root-user)
  - [Docker](#docker)
  - [PowerShell](#powershell)
  - [HTTPS](#https)
  - [Gateway Basic Auth Password](#gateway-basic-auth-password)
  - [Service User uid](#user#service-uiduser)
  - [DockerInstallation group gidDirectory](#docker#installation-group-giddirectory)
- [Installing](#installing)
  - [Running the Install Script](#running-the-install-script)
      - [Smart Classifier ML](#smart-classifier-ml)
      - [Gateway](#gateway)
  - [Enable Smart Classifier Feature](#enable-smart-classifier-feature)
  - [Major Version Upgrades](#major-version-upgrades)
    - [Upgrading from major version 5 to 6](#upgrading-from-major-version-5-to-6)
- [Starting and Stopping](#starting-and-stopping)
  - [Stopping](#stopping)
  - [Starting](#starting)

# Introduction
The 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.

## Target Audience
This guide is directed towards system administrators that are to install the Smart Classifier ML.

## End User License Agreement
By installing the software one is accepting the [End User License Agreement](https://www.ayfie.com/hubfs/terms/eula.pdf).

# Prerequisites

## Gateway Hostname
The first prerequisite to completefulfill is to decide on the Gateway Hostname of the Smart Classifier ML APIs as otherAPI's Gateway Hostname. Other prerequisites as well as the Saga Installerinstall script dependsdepend on knowing it. The recommended Gateway Hostname isUsing the FQDN of the Smart Classifier ML host. Setting is the easiest alternative as setting it to anything else will requiresrequire a DNS entry.

## Hardware Requirements
The more CPU cores, the faster ML model training.
|CPU Speed|CPU Cores   |RAM     | Drive Size|
|:-------:|:----------:|:------:|:---------:|
|   ~2 GHz|           4|    8 GB|      50 GB|

## Operating System
Tested on Ubuntu 22.04.

## Root User
A 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.

## Docker
Install Docker:
```
sudo apt-get update

sudo apt-get install ca-certificates curl gnupg lsb-release

sudo mkdir -p /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin
```

## PowerShell
The Smart Classifier ML install installerscript requires that PowerShell is installed. Consult [Install PowerShell on LinuxUbuntu](https://docslearn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linuxinstall-ubuntu?view=powershell-7.2) on how to install PowerShell on Linux.

## HTTPS
The this.

## HTTPS
The Smart Classifier ML APIs require the use of the HTTPS protocol. To facilitate that, the Smart Classifier ML requires the HTTPS protocol. The steps to configure HTTPS are the same as in the Saga platform. Please refer to the [Saga Install Guide APIs need to be set up with an SSL certificate. The prerequisite for this depends on how the certificate is to be provided:

- Received from a commercial Certificate Authority (CA) such as for instance IdenTrust, DigiCert, Sectigo, GoDaddy, etc.
- Automatically generated by Let’s Encrypt during the Smart Classifier ML installation

The prerequisites in regard to the first option are:
- two PEM formatted files, \<name\>.crt and \<name\>.key.
- the \<name\>.crt has [Gateway Hostname](#gateway-hostname) set in the Subject Alternative Name attribute. This applies even if there technically are no alternative names.
- the \<name\>.key has an unencrypted private key.

See [Obtaining Correctly Formatted SSL Certificate Files](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2400714758/Ayfie+Locator+Installation+Guide2987327489/Obtaining+Correctly+Formatted+SSL+Certificate+Files) for how to configure HTTPS.

details.

The two files are to be placed into directory _/var/ayfie/smart-classifier-ml/volumes/traefik/certs_ during installation.

The prerequisites in regard to the second option of using Let’s Encrypt's are network related:

- One is using an approved public Top Level Domain (TLD)
- The Smart Classifier ML server is exposed to the public Internet
- The firewall is open for port 80 on the Smart Classifier ML host
- There is a DNS A record entry for the Smart Classifier ML host FQDN and its public IP

## Gateway Basic Auth Password
The 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. The password must be and hashed using MD5, SHA1, or BCrypt. WhenThat configuringcan theon SmartUbuntu Classifierbe featuredone inthis Sagaway:
platform,```
onesudo needsapt-get to set the un-hashed version of this password. The hashed Basic Auth password is required by the installer.

One can use the *htpasswd* application on Ubuntu to generate the hashed password. Replace password with the password.
install apache2-utils
```

Replace *\<password\>* and run the command:
```
htpasswd -nb smart-classifier-ml password\<password\>
```

The command Thisoutput will outputbe something like this:
```
smart-classifier-ml:$apr1$fhrtmbJR$og2srnFdPPFpDiTaFUOxZ0
```

Copy 
Thethe *\<password\>* and the encrypted password, (*$apr1$fhrtmbJR$og2srnFdPPFpDiTaFUOxZ0*, will be input when running the install script later.

## User uid
Decide which user should run Smart Classifier ML and log in as this user.
* Get the *uid* of this user. The *uid* is required by the installer. The *uid* is used to set the file permission:
    ```
    id
    ```
* This One should run the Smart Classifiin our example above) as both will be required later, the *\<password\>* when enabling the Smart Classifier feature in the Saga install script and the encrypted password when running the Smart Classifier ML install script.

## Service User
One 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 *\<username\>*:
```
sudo useradd <username>
sudo passwd <username>
```

This service user needs to be member of the *docker* group to run the installer wihtoutwithout *sudo*:. Add the service user to  ```the *docker* group:
  ```
  sudo usermod -a -G docker username
    ```

* Log out and in if you are logged in with this user. Verify that the user is a member <username>
  ```

The *uid* of the service user and the *gid* of the *docker* group will be required later when [installing](#installing).

Then log in as the service user:
  ```
  su <username>
  ```

Take note of the *uid* of the service user and the *gid* of the *docker* group with:
 from the output of the command below, they will be required later:
  ```
  id
  ```

Then log back  id | grep docker
 out to the root user:
  ```
  exit
  ```

## Docker group gid
* Get the gid of the Docker group. The *gid* is required by the installer. The *gid* is used to set the file permissions:
    ```
    id | grep docker
  Installation Directory

Run the command below to create the install directory for Smart Classifier ML:
  ```
  sudo mkdir -p /var/ayfie/smart-classifier-ml
  ```
Grant permissions with these commands after having replaced *\<username\>* with the service user:
  ```
  sudo chown <username>:docker /var/ayfie/smart-classifier-ml
  sudo chmod g+s /var/ayfie/smart-classifier-ml
  ```

# Installing
New 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.

## Running the Install Script
* Create the folder for
Log in as the service user with this command:
  ```
  su <username>
  ```

Download the Smart Classifier ML installs script:
  ```
  cd  sudo mkdir -p /var/ayfie/smart-classifier-ml
    ```
* Set permissions. Replace *username* with the name of the user:
    ```
    sudo chown username:docker /var/ayfie/smart-classifier-ml
    sudo chmod g+s /var/ayfie/smart-classifier-ml
    ```
* Download the Smart Classifier ML installer:/var/ayfie/smart-classifier-ml
  wget https://nexus.ayfie.dev/repository/Raw-Hosted/smart-classifier-ml-releases/6/smart-classifier-ml.ps1
  ```
Run the install script:
  ```
  pwsh smart-classifier-ml.ps1
  ```

In the install script menu, fill in the information obtained in the prerequisites sections.

The full menu looks like this:
```
Your customized configuration values. Please choose from the list below to change.
    Smart Classifier ML UID:
    Smart Classifier ML GID:
    Smart Classifier ML Worker Count: 5
    Gateway Host Name:
    Gateway Basic Auth Password:
    Gateway Certificate Name:
    Gateway Certificates Resolver:
    Gateway Acme Email:
```

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

Navigate the fields using the up and down arrow keys and press enter to edit, or as in some cases, to toggle the field value.

### Smart Classifier ML

- **Smart Classifier ML UID:** The *uid* of the service user, see the [Service User](#service-user) section.
- **Smart Classifier ML GID:** The *gid* of the *docker* group, see the [Service User](#service-user) section.
- **Smart Classifier ML Worker Count:** The number of *uvicorn* workers. *uvicorn* is the web server hosting the Smart Classifier ML APIs.


### Gateway
The 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):

|                                    | Certificate Authority provided        | Let's Encrypt generated                |
|:-----------------------------------|:--------------------------------------|:---------------------------------------|
| **Gateway Host Name:**             | [Gateway Hostname](#gateway-hostname) | [Gateway Hostname](#gateway-hostname)  |
| **Gateway Certificate Name:**      | the \<name\> of \<name\>.crt          |                                        |
| **Gateway Certificates Resolver:** |                                       | "letsencrypt"                          |
| **Gateway Acme Email:**            |                                       | contact email                          |

A quoted value means that it is to be used as-is (but without the quotes). Empty fields means to leave the menu field empty.

## Enable Smart Classifier Feature
Consult 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.

## Major Version Upgrades

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

### Upgrading from major version 5 to 6

1. Stop Smart Classifier ML, see [Stopping](#stopping).
2. Run the following commands to delete the current version of the install script (the path assumes recommended install directory):
    ```
    > cd /var/ayfie/smart-classifier-ml
    > wget https://nexus.ayfie.dev/repository/Raw-Hosted/rm smart-classifier-ml-releases/5/.ps1
    ```
3. Download and run the 6.x version of the *smart-classifier-ml.ps1* install script, see [Running the Install Script](#running-the-install-script).

# Starting and Stopping

A start or restart of the Smart Classifier ML  ```
* Run the installer:
    ```
    pwsh requires a subsequent restart of Saga. That Saga restart should not be performed before the Smart Classifier ML services are up and running.

## Stopping

Use this command to start Smart Classifier ML:

```
> pwsh stop-smart-classifier-ml.ps1
```


## Starting

```
> pwsh smart-classifier-ml.ps1
```

The *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.