LUNA CARS installation and configuration#

LUNA CARS installation algorithms are described for OS CentOS 8 Stream.

Before Installation#

Before installation, download and unzip the distributive archive and place the distributive files in a separate folder on the server.

1․ Install the archiver if it is not installed:

dnf -y install unzip

2․ Go into the directory where the archive is placed and unzip the archive:

cd <archive_path> && unzip cars-installer_v.2.*.*.zip

Replace * to the relevant version number of CARS Installer.

Also, before the installation it is important to disable Firewalld service and stop SELinux.

Disabling Firewall and SELinux is mandatory when installing on CentOS. In the case of installation on RedOS, these steps are mandatory only if any settings have already been performed on the OS. Also, configuring these services can help in case of System startup errors.

3․ Disable Firewalld service:

systemctl disable --now firewalld

Stop SELinux:

4․ Open configuration file SELinux in the text editor:

nano /etc/selinux/config

Install nano text editor if needed or use any other.

5․ Change the value for the variable SELINUX=disabled. File example is below:

# This file controls the state of SELinux on the system.
# SELINUX= can take one of these three values:
#     enforcing - SELinux security policy is enforced.
#     permissive - SELinux prints warnings instead of enforcing.
#     disabled - No SELinux policy is loaded.
SELINUX=disabled
# SELINUXTYPE= can take one of these three values:
#     targeted - Targeted processes are protected,
#     minimum - Modification of targeted policy. Only selected processes are protected.
#     mls - Multi Level Security protection.
SELINUXTYPE=targeted

6․ Reboot the server to apply the changes:

reboot

Preparation for licensing#

HASP installation and configuration#

Before obtaining a license, you must install the HASP utility on the server.

Installation LUNA CARS using Ansible (section 2.8) provides automatic installation and launch of the HASP utility.

If a separate server to download a network license is used (section 2.3.3.1), HASP must be installed manually regardless of the system installation method.

1․ Go to the directory with the HASP utility distributive:

cd cars-installer_v.2.*.*/extras/hasp/

Run following commands for HASP installation:

2․ Unzip the archive with utility

tar -xf aksusbd-8.tar

3․ Go to the directory with installation file

cd aksusbd-8/

4․ Run installation and starting script

./dinst

5․ Check the status of the utility using the command:

systemctl status aksusbd

If the utility is successfully launched, the result of the executed command will be the following message:

aksusbd.service - LSB: Sentinel LDK RTE
   Loaded: loaded (/etc/rc.d/init.d/aksusbd; bad; vendor preset: disabled)
   Active: active (running) since Tue 2021-06-29 16:32:43 MSK; 1 day 19h ago
     Docs: man:systemd-sysv-generator(8)
   CGroup: /system.slice/aksusbd.service
           ├─909 /usr/sbin/aksusbd
           ├─920 /usr/sbin/winehasp
           └─953 /usr/sbin/hasplmd -s

Server Fingerprint#

A server fingerprint file is required to obtain a license.

The server fingerprint file must be generated while the HASP utility is running.

When installing LUNA CARS using Ansible (section 2.8), it is required to install Ansible preliminarily (section 2.8.1) and run fingerprint generation process only after that.

1․ Go to the /extras/licenseAssist/bin directory:

cd cars-installer_v.2.*.*/extras/licenseAssist/bin

2․ Generate server fingerprint using the following script:

./LicenseAssist fingerprint <name>.c2v

3․ In some cases, an access error may occur. It is necessary to grant permissions to the script and repeat the process:

chmod +x LicenseAssist

After the process of generating a system fingerprint is completed, it will need to added fingerprint to request for technical support.

Send the fingerprint file together with the information mentioned in section 1.3 to the VisionLabs technical support staff for the further license receiving.

Technical support staff will send an email with a license file in «.v2c» format. This file must be used for license activation.

License activation process is described in sections 2.3.3, 2.8.4

LUNA CARS installation using Docker#

Installation of the Docker and Docker-compose#

Installation on CentOS 8 Stream#

Use the official instruction for CentOS to install Docker and Docker-compose. This instruction is the most up to date.

1․ Run the command for Docker and Docker-compose previous versions deletion:

yum remove docker \
                  docker-client \
                  docker-client-latest \
                  docker-common \
                  docker-latest \
                  docker-latest-logrotate \
                  docker-logrotate \
                  docker-engine

2․ Delete utilities that may cause conflicts:

yum remove podman runc

3․ Install additional dependencies:

yum install yum-utils

4․ Add Docker repository to the installation manager:

yum-config-manager \
    --add-repo \
    https://download.docker.com/linux/centos/docker-ce.repo

5․ Install Docker:

yum install docker-ce docker-ce-cli containerd.io docker-compose-plugin

6․ Enable Docker:

systemctl enable docker

7․ Launch Docker:

systemctl start docker

8․ Check Docker installation:

docker -v

9․ Check Docker-compose installation by running the command for getting a version:

docker compose version

Installation on RedOS Murom 7.3.2#

Install Docker and Docker Compose:

dnf install docker-ce docker-compose

Enable Docker:

systemctl enable docker

Launch Docker:

systemctl start docker

Configuration of the «.env» file#

The «.env» file is located at the root of the installer distribution.

Each parameter has its own editing recommendation (ER).

Description of editing recommendations is given in Appendix 1.

The .env file contains passwords and addresses that third parties can learn because the file is not view-protected by default. It is recommended to close access to the file using Linux tools. Working with Linux permissions is outside the scope of this manual.

Before installation, you need to configure the account settings for distributives download. Open the «.env» file in the text editor:

nano .env

Fill the values for parameters DOWNLOAD_USER and DOWNLOAD_PASSWORD.

Request user login and password from VisionLabs technical support staff.

Apply changes in the file and save it.

Other parameters of the «.env» environment file are presented in Appendix 2

License activation#

Method of license activation depends on its type (see section 1.1)

Network license activation#

To activate the Network license on the main server where the HASP was installed, it is required to upload the obtained license file via HASP web-interface.

Go to the following link in the web-browser (this address is only available on the server where HASP is installed):

http://<IP_address_server_with_HASP>:1947

On the «Update/Attach» page, you need to add the license file and click «Apply File» (Figure 1).

After changes are applied, the system will display the following message (Figure 2).

Figure 2. Successful license file application message

After that, configure the «.env» file (see details in section 2.3.2): add IP-address of the server where HASP is installed as a value for HASP_LICENSE_SERVER parameter.

Save the file and exit. After that the installation will be performed correctly.

Trial license activation#

There are 2 ways to activate a trial license: manual and automated.

1․ Manual way to activate a trial license

Using a trial license, it is required to license each container of CARS API and CARS Stream (Figure 3).

Figure 3. Licensing LUNA CARS when deploying containers

To license each container, upload license file via HASP web-interface via the corresponding port (Table 3).

Table 3. HASP ports for CARS API and CARS Stream containers

Container	Port
CARS Stream 1	1948
CARS Stream 2	1949
CARS Stream 3	1950
CARS Stream 4	1951
CARS API 1	1952
CARS API 2	1953

License activation for CARS Stream:

License activation should be performed only for installed CARS Stream instances. If only one instance is installed, activation must be performed only on the its port. When using additional instances, activation should be performed on subsequent ports.

1․ Go to the link:

http://<IP_address_server_with_HASP>:<CARS Stream port>

2․ On the «Update/Attach» page, you need to add the license file and click «Apply File» see Figure 1.

3․ After changes are applied, the system will display the message of successful upload see Figure 2.

License activation for CARS API containers:

CARS API 1 container

Go to the link in the web-browser:

http://<IP_address_server_with_HASP>:1951

Repeat steps 2 and 3 described above.

CARS API 2 container

Go to the link in the web-browser:

http://<IP_address_server_with_HASP>:1952

Repeat steps 2 and 3 described above.

The HASP ports of the CARS API and CARS Stream containers are set during installation in the API_HASP_PORT_START, API_HASP_PORT_START and STREAM_HASP_PORT variables in the «.env file».

Note that variables API_HASP_PORT_START and STREAM_HASP_PORT are the range of the ports. Installing CARS API on the several servers, put the values of the first and last ports. License should be uploaded for each port in the range.

After that the installation will be performed correctly.

This way of license activation must be repeated after each stop and start of containers.

2․ Automated way to activate trial license

For automated activation of a trial license, it is necessary:

Save the trial license file on the server where the system is being installed.
Make changes to the configuration file ".env" (see more details in section 2.3.2): it is necessary to specify the full path to the license file on the server in the HASP_LICENSE_FILE parameter.

These steps need to be performed only once, even if multiple instances of CARS Stream and CARS API are installed.

Save the file and exit it. After that, the installation of the LUNA CARS system will be performed correctly.

Troubleshooting#

1․ License expired. Example of error message in CARS Stream container logs:

stream_1 | E0323 03:30:44.465771 61 LicenseChecker.cpp:14] [23.03.2023 03:30:44] [Error] [Session] Sentinel protection key not available. (HASP_HASP_NOT_FOUND). 
stream_1 | E0323 03:30:44.465786 61 LicenseChecker.cpp:48] Licensing. Feature with id = 303 doesn't exist.
stream_1 | E0323 03:30:44.465792 61 main.cpp:213] Couldn't initialize app

It warns you about using not relevant license version or about license absence. Please contact VisionLabs engineers for help.

2․ License mismatch with equipment composition. Example of error message in CARS Stream container logs:

stream2_1 | E0317 05:52:01.408428 20 LicenseChecker.cpp:59] Licensing error. Maximum number of processors for this machine is equal 8, current number of processors is equal 72

It warns you that the number of CPU mentioned in license request is not equal to the actual number of CPU. Please contact VisionLabs engineers for help.

Starting installation using Docker#

The installation script is located in the root of the installer distributive. Go to the root of the installer distributive:

cd cars-installer_v.2.*.*

Run the installation script with the required key:

./docker_start_all.sh MODE

Instead of MODE, specify the startup key. The list of available keys:

Key	Description
vanilla	Start in standard mode of operation
checkpoint	Start in Extended Event mode (see User Manual - Operation mode "Extended event")
full	Starting with full services, used for testing

The initial startup may take several minutes.

System launch#

After the installation you can enter the CARS Analytics UI opening following link in the web-browser:

http://<IP_address>:8080

The default port is specified, the port is set in the ANALYTICS_FRONTEND_PORT variable in the «.env» configuration file.

To enter the service on behalf of the system administrator, use the following data:

Login – admin@test.ru;
Password – test_admin.

Stopping LUNA CARS using Docker#

If it is needed to stop the LUNA CARS system, regardless of the configuration of the running components, run the stop script from the root of installer distributive:

./docker_stop_all.sh

Installing LUNA CARS without Internet Access#

In cases where the server does not have access to the Internet, you must perform the following algorithm.

That server must have Docker, Docker-compose and HASP installed.

1․ Configure and prepare the system by editing the «.env» file accordingly to section 2.3.2 on a server with Internet access.

2․ Run the build script:

./docker_save_all.sh

3․ Transfer the installer distribution kit to the target server in any convenient way.

4․ Run the restore script:

./docker_restore.sh

5․ Check the system work by opening the following link in the web-browser:

 http://<IP_address>:8080

The default port is specified, the port is set in the ANALYTICS_FRONTEND_PORT variable in the «.env» configuration file.

To enter the service on behalf of the system administrator, use the following data:

Login – admin@test.ru;
Password – test_admin.

Individual installation of subsystems using Docker#

LUNA CARS supports scenarios for the operation of components in various configurations and with various third-party services, for this it is possible to deploy the service one at a time.

No performance testing has been done on a single instance of CARS API, CARS Stream, or CARS Analytics under a given load.

Installation Algorithm#

1․ Configure and prepare the system accordingly to sections 2.1-2.4.3.

To install subsystems individually correctly, add IP-addresses for other subsystems in the «.env» file.

Set the addresses where the systems are installed or set the 127.0.0.1 if systems have not been installed yet.

2․ Run the local build script for the required service:

For CARS API

./docker_start_api.sh

For CARS Stream

./docker_start_stream.sh

For CARS Analytics

./docker_start_analytics.sh

Configuration of CARS API and CARS Stream#

CARS Stream and the CARS API include several configuration files that can be customized after installation.

Since the CARS Installer distribution does not include distributions of LUNA CARS components, editing parameters is possible only after downloading and running the distributions.

Algorithm for changing parameters:

1․ Run the command to view the Docker container ID:

docker ps

2․ Enter the container using its ID:

docker exec -it <container id> bash

3․ Edit the necessary configuration files using text editors and save the changes.

For a list and location of configuration files, see the CARS Stream and CARS API Administration Manuals.

4․ Exit the container and restart the container

docker restart <container id>

CARS Analytics does not require the setting of configuration files.

Installation using Ansible#

LUNA CARS system may be installed on the server using Ansible.

Several servers may be used for installation using Ansible:

Installation server – the server where the Ansible is installed. This server connects to the target server via SSH and LUNA CARS is installed remotely on the target server:
Target server – the server where LUNA CARS or one of the subsystems will be installed.

The scheme for using two servers (Figure 4).

Using installation and target server while installing LUNA CARS using Ansible is not a necessary requirement. Full installation of all software may be performed on one server. In this case, this one server will perform as an installation and a target server at the same time.

Ansible installation#

Prepare the installation server (see section 2.1) and install the Ansible package using following commands.

For CentOS 8 Stream OS, Ansible is installed using a batch manager.

Install additional repositories:

dnf install epel-release

Install Ansible:

dnf install ansible

Troubleshooting#

If the localization error appears, run following commands to solve this problem:

export LC_ALL="en_US.UTF-8"
export LC_CTYPE="en_US.UTF-8"

SSH settings#

To configure ansible on the installation server and install the system on the target server, it is required to generate an SSH key and add it to the target server. At first check and configure the SSH service.

Install SSH service on the target server:

yum install -y openssh-server

Run the service:

systemctl start sshd

Check if the service is working

systemctl status sshd

Generate public SSH-key on the installation server:

ssh-keygen

A keyword can be set with a value or left empty in needed.

To copy the key to the target server, run the command:

ssh-copy-id username@hostname

Where username - name of an authorized user, and hostname - IP-address of a target server.

This approach is not the only one possible. You can use any other comfortable approach to provide an SSH-access to the target server.

Settings of inventory file#

The package includes files «hosts» and «hosts-single». These files are placed in /ansible directory. File «hosts-single» is an example of the inventory file for installing components on one server (Figure 5).

Figure 5. Components installation on one server

File «hosts» is an example of the inventory file for installing components on different servers (Figure 6).

Figure 6. Components installation on different server

Installing components on one server, file «hosts-single» should include the external IP-address of the target server where the system will be installed. If the installation will be run locally using the distributive located in an external machine, provide IP_address of a local machine.

Installation can be run locally on one machine, but it is necessary to comply with the requirements for the need to enter an external IP-address and the possibility of SSH access.

#frontend component
[frontend]
<IP_address>

#Only 1 host
#ip-address DB
[postgres]
<IP_address>

#Only 1 host
#ip-address redis
[redis]
<IP_address>

#CARS API
#Multiple hosts allowed
#ip-address CARS API
[api]
<IP_address>

#Only 1 host
#ip-address nginx for CARS API
[nginx]
<IP_address>

#CARS Stream
#Only 1 host
#ip-address CARS Stream
[stream]
<IP_address>

Installing components on different servers, file «hosts» should include the external IP-address of the target server where the exact component will be installed for each component.

#CARS.Analytics
#Only 1 host
[frontend]
<IP_address>

#Only 1 host
[backend]
<IP_address>

#Only 1 host
[postgres]
<IP_address>

#Only 1 host
[redis]
<IP_address>

#CARS.API
#Multiple hosts allowed
[api]
<IP_address1>
<IP_address2>
    <…>
    <IP_address#>

#Only 1 host
[nginx]
<IP_address>

#CARS.Stream
#Multiple hosts allowed
[stream]
<IP_address1>
<IP_address2>
    <…>
    <IP_address#>

[Analytics_ALL:children]
frontend
backend
postgres
redis

[Api_ALL:children]
api
nginx

Licensing for installation using Ansible#

Installation using Ansible does not require separate installation of the HASP utility.

To obtain a license, generate a server fingerprint (see section 2.2.2) and send it to the VisionLabs technical support staff.

Local commercial license may be used for installation on one server. For installation on different servers it is recommended to use the Network license.

Installing the system on different servers, choose the most stable server for generating a fingerprint. Make sure this server will be the main one and will work continuously.

Commercial license activation#

Local commercial license and Network commercial license have the same algorithm of activation described in the section 2.3.3.1.

Network license activation must be performed on the main installation server.

Trial license activation within installation on different servers#

There are 2 ways to activate a trial license within installation on different servers: manual and automated.

1․ Manual way to activate a trial license

Using a Trial license within system installation on different servers, it is required to license each server where CARS API and CARS Stream are installed.

License activation for CARS Stream server:

1․ Go to the link:

http://<IP_address_Stream_server>:1947

2․ On the «Update/Attach» page, you need to add the license file and click «Apply File» (section 2.3.3.1, Figure 1).

3․ After changes are applied, the system will display the message of successful upload (section 2.3.3.1, Figure 2).

License activation for CARS API servers:

CARS API 1 server

Go to the link in the web-browser:

http://<IP_address_API_server1>:1947

Repeat steps 2 and 3 described above.

CARS API 2 server

Go to the link in the web-browser:

http://<IP_address_API_server2>:1947

Repeat steps 2 and 3 described above.

2․ Automated way to activate trial license

For automated activation of a trial license, it is necessary:

Save the trial license file on the server where the system is being installed.
Make changes to the configuration file ".env" (see more details in section 2.3.2): it is necessary to specify the full path to the license file on the server in the HASP_LICENSE_FILE parameter.

These steps need to be performed only once, even if multiple instances of CARS Stream and CARS API are installed.

Save the file and exit it. After that, the installation of the LUNA CARS system will be performed correctly.

Settings of «all.yml» configuration file#

Configure «all.yml» configuration file if needed.

«all.yml» file parameters are described in Appendix 3.

The «all.yml» file is located in the ./ansible/group_vars/ directory.

Each parameter has its own editing recommendation (ER).

Description of editing recommendations is given in Appendix 1.

Apply the changes and save the «all.yml» file.

Configuration of the «.env» file#

Before installation, you need to configure the account settings for distributives download.

Go to the installer root directory:

cd cars-installer_v.*.*.*

Open the «.env» file in the text editor:

nano .env

Fill the values for parameters DOWNLOAD_USER and DOWNLOAD_PASSWORD.

Request user login and password from VisionLabs technical support staff.

Apply changes in the file and save it.

Other parameters of the «.env» environment file are presented in Appendix 2.

Launching Ansible installation#

After adding the data in the «.env» file, start the Ansible installation.

Run installation script from the root directory:

./ansible_download_zip.sh

Launching LUNA CARS installation via Ansible#

Go to the /ansible directory:

cd ansible

Execute the following command to start the installation procedure for CARS Stream and CARS Analytics:

ansible-playbook -i hosts-single install_analytics.yml install_stream.yml install_api.yml

Replace hosts-single with hosts if installing on several servers.

In case on an error of unavailability of repositories, restart the installation.

System launch#

Check the system work by opening the following link in the web-browser:

 http://<IP_address>:8080

To enter the service on behalf of the system administrator, use the following data:

Login – admin@test.ru;
Password – test_admin.