Manual client installation on linux

Preparing the package

Download A.V.A.T.A.R client zip file from GitHub.
- Click on the button and Download zip.
Extract the A.V.A.T.A.R-Client-master.zip file using "Extract or Extract here" selection.
In your home, create a packager/client directory which will be used to package the application.
Copy the contents of ~/downloads/A.V.A.T.A.R-Client-master/dist to ~/packager/client.
```
: cd ~/downloads/A.V.A.T.A.R-Client-master/dist
: cp - r * ~/packager/client
```

Installing the packager module

Open a terminal
Change to ~/packager/client directory:
```
cd  ~/packager/client
```
Enter the following command to install the packager and all application modules:
```
client: npm install --save-dev @electron/packager
```
About deprecated modules

You can ignore messages about deprecated modules.
These messages are not important and the installation can continue.
After a few moments, you should see the following result:
```
added <xxx> packages, and audited <xxx> packages in 19s

<xx> packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities
```
Check vulnerabilities!

The application is updated regularly, but it is possible that you may discover vulnerabilities (the 'found 0 vulnerabilities' can be more than 0).
If this is the case, installation is unaffected and can continue.
You can also contribute by leaving an issue to update the application.

Running the packager module

In order to have the latest version of Electron for your installation, you need to retrieve the latest version from the Electron GitHub which will be used to package it.

Go to the Electron GitHub web site and on the right, in the Releases section, below the About section, note the latest version (as in the example image below, framed in red):
Run the packager:
- Suppose that the lastest version readed on the Electron site is 34.8.1, then change the XX.X.X value to the latest version in the --electron-version=XX.X.X parameter in the command line below then execute it.
```
client % npx electron-packager . --electron-version=XX.X.X --icon=./avatar.ico --out=output
```
After a few moments, you should see the following result:
```
Packaging app for platform linux x64 using electron vXX.X.X (the latest version from Electron GitHub site)
Wrote new app to: output\A.V.A.T.A.R-Client-linux-x64
```
Warning

The architecture name depends of the packaging, it can be A.V.A.T.A.R-Client-linux-x64 or A.V.A.T.A.R-Client-linux-arm64.

In the section below, we assume that it is A.V.A.T.A.R-Client-linux-x64 but it can be A.V.A.T.A.R-Client-linux-arm64. If it is the case, change the directory name according to your platform.

Installing Electron module

Change to the output/A.V.A.T.A.R-Client-linux-x64/resources/app directory:
```
client: cd ./output/A.V.A.T.A.R-Client-linux-x64/resources/app
```
Enter the following command to install Electron in the package:
```
app: npm install electron --save-dev
```

After a few moments, you should see the following result:

added <xxx> packages, changed <x> packages, and audited <xxx> packages in 13s

<xx> packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities

Deploy A.V.A.T.A.R client as an application

A.V.A.T.A.R client is now ready to be moved into its application directory.

You have two possible choices:

Copy (or move) the contents of the packager/client/output/A.V.A.T.A.R-Client-linux-x64 directory to the home directory and start the client with the a.v.a.t.a.r-client application.
Create an A.V.A.T.A.R-Client application.

Choose what you want to do below (between « Move to the home directory » or « Create an application »)

Create an applicationMove to the home directory

Change to the packager/client directory:
```
cd ~/packager/client
```

Install the required packages:

~/packager/client: sudo apt-get update
~/packager/client: sudo apt-get install fakeroot dpkg

Install electron-installer-debian:

~/packager/client: npm install -g electron-installer-debian

In the /packager/client directory, create the .deb package:

~/packager/client: electron-installer-debian --src output/A.V.A.T.A.R-Client-linux-x64/ --dest installer/ --arch amd64

Go to the packager/client/installer directory and install the package created in this directory (the name may vary depending on the platform and the version):

client: cd ./installer
installer: ls -l 
    # returns the name of the package
    # copy and put the name in the following command (in the example below, it's a.v.a.t.a.r-client_amd64.deb)

installer: sudo apt install ./a.v.a.t.a.r-client_amd64.deb

Changing the owner of the a.v.a.t.a.r-client application:
1. The best simple way to get the owner and group is doing a ls -l command in a terminal:
```
ls -l
```
2. The user and its group are displayed to the left, just after the access rights of all files
  
  in the screenshot example, the is avatar (to the left) and the is avatar (to the right)
3. Enter the following commands to change the owner and group of all files of the a.v.a.t.a.r-client application
```
sudo chown -R <owner> *
sudo chgrp -R <group> *
```
Modify the application icon:
- Edit the /usr/share/applications/a.v.a.t.a.r-client.desktop file in your prefered editor
- Change the value of the Icon property by:
```
Icon=/usr/lib/a.v.a.t.a.r-client/resources/app/avatar.ico
```

Create a directory for A.V.A.T.A.R client (e.g. ~/avatar/client).
Copy (or move) the contents of the output/A.V.A.T.A.R-Client-linux-win64 directory to ~/avatar/client.
```
cd ~/packager/client/output/A.V.A.T.A.R-Client-linux-x64
mv -r * ~/avatar/client
```

if you want an application icon to the dock

Create a ~/.local/share/applications/a.v.a.t.a.r-client.desktop file

Open this file and add the following line:

note: Replace <account> by your login account (it is your home directory)

[Desktop Entry]
Name=A.V.A.T.A.R Client
Comment=A.V.A.T.A.R Client
GenericName=A.V.A.T.A.R Client
Exec=/home/<account>/avatar/client/a.v.a.t.a.r-client %U
Icon=/home/<account>/avatar/client/resources/app/avatar.ico
Type=Application
StartupNotify=true
Categories=GNOME;GTK;Utility;

Save the a.v.a.t.a.r-client.desktop file

installing Sox

A client needs Sox to register intercoms with other clients.

sudo apt-get update
sudo apt-get install sox

installing FFmpeg

A client needs ffplay to play sound and music files.

sudo apt-get update
sudo apt-get install ffmpeg

HTTPS certificate

The client's speech recognition uses the Web Speech API interface, which can be accessed by all browsers. As a result, a client embades a version of Google Chrome when it is installed to ensure perfect compatibility with the client's version at all times.

To ensure secure communication between Google Chrome and the client, you need to create an HTTPS certificate.
Follow the first step first, then return to this page to complete the client installation:

Create a self-signed certificate.

Importing the Certificate Authority to the keystore:

Open a terminal

Check if the /usr/local/share/ca-certificates exists

ls /usr/local/share/ca-certificates

if not :

sudo mkdir /usr/local/share/ca-certificates

Change to packager/certificates/CA directory
```
cd  ~/packager/certificates/CA
```

Enter the following commands to import the Certificate Authority in the keystore:

Copy the certificate

sudo cp ./avatarCA.crt /usr/local/share/ca-certificates

Update the keystore

sudo update-ca-certificates

The command returns

Updating certificates in /etc/ssl/certs...
1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

Add certificate to the database keystore

certutil -A -n "avatar" -t "C," -i ./avatarCA.pem -d sql:$HOME/.pki/nssdb/

Importing the host certificate to A.V.A.T.A.R client:

Depending on whether you have chosen “Move to the home directory” or “Create an application” for your installation, select the following steps in the tab below:
Created as applicationCreated in the home directory
1. Create a certificates directory for the host certificate:
  
  Open a terminal
  
  Change to /usr/lib/a.v.a.t.a.r-client/resources/app/core/chrome directory
  
  cd /usr/lib/a.v.a.t.a.r-client/resources/app/core/chrome
  
  Create a certificates directory
  
  mkdir certificates
2. Copy the host certificate to the certificates directory:
  
  Change to ~/packager/client/certificates/hote
  
  cd ~/packager/client/certificates/hote
  
  Copy your <server name>.key and <server name>.crt files to this directory (these files are created in the Create a certificate for the host client step):
  
  cp <server name>.crt <server name>.key /usr/lib/a.v.a.t.a.r-client/resources/app/core/chrome/certificates
1. Create a certificates directory for the host certificate:
  
  Open a terminal
  
  Change to avatar/client/resources/app/core/chrome directory
  
  cd ~/avatar/client/resources/app/core/chrome
  
  Create a certificates directory
  
  mkdir certificates
2. Copy the host certificate to the certificates directory:
  
  Change to packager/client/certificates/hote
  
  cd ~/packager/client/certificates/hote
  
  Copy the <server name\>.crt and <server name\>.key files to the avatar/client/resources/app/core/chrome/certificates directory created in the previous step
  
  cp <server name>.crt <server name>.key avatar/client/resources/app/core/chrome/certificates

Checking Certificate Authority installation

After the installation you can check the import of the certificate authority in the keystore.

Open a terminal
Enter the following command to verify if the certificate is valid:
```
certutil -d sql:$HOME/.pki/nssdb -L
```
Result:

Voices

Platform	System voices	Google Chrome remote voices	Comment
Linux			No system or Chrome voices available. Voices available through `espeak` and `mbrola`.

espeak is a multi-language speech synthesizer, which we'll use only for phonetic conversion.
mbrola is a multi-language voice synthesizer that offers improved rendering and can be coupled with espeak.

Installing espeak and mbrola

Enter the following commands:

sudo apt install espeak 
sudo apt install mbrola

Start the client

Warning

Start the A.V.A.T.A.R server first!

Start the client according to the installation choice.

Type	Action
linux application	1. Search for the A.V.A.T.A.R Client application
In a directory	1. Open an Explorer and change to the avatar/client. 2. Double-click on the a.v.a.t.a.r-client application

Warning

Warning: if you have anti-virus software, it may notify you that the application does not have a valid digital signature. Click on "always authorize".

The first connection window appears:

Add required information

Enter the information required to start the client:
- The client name.
- The server's UDP search range:
  - You can enter a search range in the format XXX.XXX.XXX.XXX-XXX
    - For example:
      - with 192.168.2.100-110, the client will look for the server at addresses 192.168.2.100 to 110
    - You can also enter the server address directly, for example: 192.168.2.100
- The UDP search port:
  - By default: 3333
  - This port number must be identical to the one defined in the server properties.
  - If you haven't changed it on the server, leave the default port.
Click on "Save"
The client restarts

Add the host certificate

The client window displays a warning message telling you that HTTPS has not been configured by an orange message:
Left-click on the client's name to open its context menu.

Warning

Always wait until the client is fully initialized before clicking on its name to open its context menu.
Wait until you see the the The HTTPS certificate is missing... message in the console.
Click on Edit -> Plugin Studio:
In Plugin Studio, click on the Plugins tab, then click on the Chrome plugin.
Click on the Properties tab:
- Add the <server name>.key file name to the key property (see HTTPS certificates for more details).
- Add the <server name>.crt file name to the cert property (see HTTPS certificates for more details).
- Add the server name to the address property.
- Uncheck the headless property to display Chrome on next startup and check if the certificate is valid.
Tip

In the image, a “sb-portable” is placed in the fields.

This is just an example!

You should see the name of your <server name>.crt and <server name>.key files (located in the app/core/chrome/certificates directory)
Right-click and click Save to save the properties
Close the window (using the cross)
Restart the client

Checking the host certificate

After restarting the client, Chrome appears.
Verify if the HTTPS certificate is valid in the Chrome browser.

Expected result (the sb-portable hostname is only a example, you must see the hostname of your platform):

Warning

If your certificate is not valid, maybe the certificate has not been made correctly.
Repeat the certificate creation step.

If the certificate is valid, open Plugin Studio again and change the headless property to true to hide Chrome the next time it is started. Do not forget to save the properties:

Tip

Chrome properties are defined in a chrome plugin so that they can be easily modified from within Plugin Studio.

Never delete this plugin, or the client will stop working!

You can now set some mandatory parameters at client startup.

Mandatory parameters

You're starting the client for the first time.
Although some client properties have been configured automatically, others need to be changed quickly.

Do a right click here and select 'Open link in new tab' to display the Client Settings page access.
Then, change these parameters to complet the installation:
- Dialog language - Mandatory -
  - Defines the language used for voice rules.
  - By default the language is seted to "English".
  - You have to define the language you want and associated voice parameters (voice preference and current voice).
- Trigger keywords - Optional/Mandatory -
  - Defines trigger keywords to start listening.
  - The default keywords are "Sarah" and "Jarvis".
  Warning
  
  Depending on the language you've chosen, the Trigger keywords may not be understood.
  If you've changed the dialog language, you'll need to change the trigger keyword.
- Rules - Optional/Mandatory -
  - Defines phrases that are used by you or by the client when replying to you.
  - At the installation, these parameters are set in "English" language.
  - If you've changed the dialog language, you'll need to change the rules.
- Application language - Optional -
  - Defines the language used for all graphical interfaces and application messages.
  - At the installation, this parameter is set to "English" (you can choose between "English or "French").
  - If "English" is the language you need, you can bypass this step.
- The background image - Optional -
  - A Background image for the client. Not mandatory but so much nicer!

Test the installation

You can now test the installation by downloading your first plugin.

Server installation Test the installation