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](#service-user)
  - [Installation Directory](#installation-directory)
- [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 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.

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

## HTTPS
The 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:

- 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/2987327489/Obtaining+Correctly+Formatted+SSL+Certificate+Files) for 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 and hashed using MD5, SHA1, or BCrypt. That can on Ubuntu be done this way:
```
sudo apt-get install apache2-utils
```

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

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

Copy the *\<password\>* and the encrypted password (*$apr1$fhrtmbJR$og2srnFdPPFpDiTaFUOxZ0* 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 without *sudo*. Add the service user to the *docker* group:
  ```
  sudo usermod -a -G docker <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 from the output of the command below, they will be required later:
  ```
  id
  ```

Then log back out to the root user:
  ```
  exit
  ```

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

Log in as the service user with this command:
  ```
  su <username>
  ```

Download the Smart Classifier ML installs script:
 ```
  cd /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 [InstallInstallation 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
    > rm smart-classifier-ml.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 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.