Deploying the Service using Docker#

This section describes how to install and use Docker Compose to deploy the Service.

The configuration and installation process must be performed under a superuser account (with root rights).

Docker and Docker Compose are not included in the Service distribution package.

The commands for CentOS are given below.

Docker and Docker Compose installation#

Use the official instructions to install Docker Engine and Docker Compose for CentOS. The current installation instructions are presented below.

Install the yum-utils package (which provides the yum-config-manager utility):

yum install -y yum-utils

Set up the stable repository:

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

Install the latest version of Docker Engine and containerd:

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

Check that the installation was done correctly:

docker -v

Download the current stable release of Docker Compose:

curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

Set permissions (allow execution):

chmod +x /usr/local/bin/docker-compose

Start Docker:

systemctl start docker
systemctl enable docker

Check Docker status:

systemctl status docker

Registry authorization#

To start services, you need to get their images from dockerhub.visionlabs.ru (VisionLabs registry). Authorization is required:

docker login dockerhub.visionlabs.ru --username <username> --password <password>

Enter login and password .

You can get them by contacting VisionLabs specialists.

Preparing and unpacking the distribution#

The distribution package is an archive of the form "clementine_2.24.0".

The archive contains all the components necessary for the installation and operation of the Service.

The archive does not include dependencies that are included in the standard distribution package of the CentOS repository and can be downloaded from open sources.

Place the distribution files in a directory on the server before the installation process. For example, to the /root directory. This directory should not contain other distribution files other than the target files used to install the final product.

Follow these steps.

Switch to the super user:

sudo su

Create a directory for unpacking the distribution package:

mkdir -p /var/lib/clementine

Move the distribution package to the created directory:

mv /root/clementine_2.24.0 /var/lib/clementine

Install the unzip archiver if it is not installed:

yum install unzip

Go to the distribution package folder:

cd /var/lib/clementine

Unpack files:

unzip clementine_2.24.0.zip

Create a symbolic link. The link indicates that it is the current version of the distribution package that is used to run:

ln -s clementine_2.24.0 current

Service configuration#

Selinux and Firewall must be configured so that they do not block the operation of the Service.

Selinux and Firewall configuration is not described in this manual.

The “clementine_2.24.0” archive contains an example of Docker deployment in the /example-docker directory (.env and docker-compose.yml files).

Service configuration is performed in the .env configuration file:

### GLOBAL ###

# Where to preserve persistent data

DATA=./
DOCKER_URL=dockerhub.visionlabs.ru/clementine

# username for databases

CLEMENTINE_USERNAME=clementine

# Password for services

CLEMENTINE_PASSWORD=clementine

# CLEMENTINE tags

CLEMENTINE_AUTH_VER=v1.1.12
CLEMENTINE_DEPARTMENTS_VER=v1.1.4
CLEMENTINE_UI_VER=v1.47.3
VL_NOTIFIER_VER=0.1.16
CLEMENTINE_API_VER=v1.8.0

# 3rd party services tags

POSTGRESQL_VER=12

### Configs ###

# clementine-ui

CLEMENTINE_UI_HOST=clementine_ui
CLEMENTINE_UI_PORT=8080

# clementine-api

CLEMENTINE_API_HOST=clementine_api
CLEMENTINE_API_PORT=9010

# clementine-auth

CLEMENTINE_AUTH_HOST=clementine_auth
CLEMENTINE_AUTH_PORT=9000
CLEMENTINE_AUTH_DOMAIN=127.0.0.1
CLEMENTINE_AUTH_PROTOCOL=HTTP
CLEMENTINE_AUTH_DSN=postgresql://clementine:clementine@clementine_db/clementine_auth

# clementine-departments

CLEMENTINE_DEPARTMENTS_HOST=clementine_departments
CLEMENTINE_DEPARTMENTS_PORT=9100
CLEMENTINE_DEPARTMENTS_DSN=postgresql://clementine:clementine@clementine_db/clementine_departments

# luna

LUNA_API_HOST=127.0.0.1
LUNA_API_PORT=5000
LUNA_LICENSES_HOST=127.0.0.1
LUNA_LICENSES_PORT=5120
LUNA_ACCOUNT_ID=a0000000-0000-4000-a000-000000000000

# lunastreams

LUNA_STREAMS_HOST=127.0.0.1
LUNA_STREAMS_PORT=5160

# vl-notifier API

VLNOTIFIER_HOST=vlnotifier
VLNOTIFIER_PORT=9200
VLNOTIFIER_SUBJECT=«Clementine VL Notifier»

# vl-timetracker

VLTIMETRACKER_HOST=127.0.0.1
VLTIMETRACKER_PORT=8003

# vl-access

VLACCESS_HOST=127.0.0.1
VLACCESS_PORT=9091

# OTHER

LOG_LEVEL=1
TELEGRAM_BOT_TOKEN=
SMTP_SERVER=
SMTP_PORT=
SMTP_SENDER=
SMTP_LOGIN=
SMTP_PASSWORD=

Enter the necessary settings in the .env configuration file, as shown in Table 2.

Table 2. Configuration parameters

Parameter	Description
LUNA CLEMENTINE 2.0 database configuration parameters
`DATA=./`	Mount point for container data (optional)
`DOCKER_`url`=`	By default: `dockerhub.visionlabs.ru/clementine`
`CLEMENTINE_USERNAME=`	Name of the database
	By default: `clementine`
`CLEMENTINE_PASSWORD=`	Database password
	By default: `clementine`
Tags
	Clementine tags:
`CLEMENTINE_AUTH_VER=`	`CLEMENTINE_AUTH_VER=v1.1.12`;
`CLEMENTINE_DEPARTMENTS_VER=`	`CLEMENTINE_DEPARTMENTS_VER=v1.1.4`;
`CLEMENTINE_UI_VER=`	`CLEMENTINE_UI_VER=v1.47.3`;
`CLEMENTINE_API_VER=`	`CLEMENTINE_API_VER=v1.8.0`
	Third party service tags:
`VL_NOTIFIER_VER=`	`VL_NOTIFIER_VER=0.1.16`;
`POSTGRESQL_VER=`	`POSTGRESQL_VER=12`
CLEMENTINE UI configuration parameters
`CLEMENTINE_UI_HOST=`	CLEMENTINE UI server address
	By default: `clementine_ui`
`CLEMENTINE_UI_PORT=`	CLEMENTINE UI port
	By default: `8080`
CLEMENTINE API configuration parameters
`CLEMENTINE_API_HOST=`	CLEMENTINE API server address
	By default: `clementine_api`
`CLEMENTINE_API_PORT=`	CLEMENTINE UI port
	By default: `9010`
CLEMENTINE AUTH configuration parameters
`CLEMENTINE_AUTH_HOST=`	CLEMENTINE AUTH server address
	By default: `clementine_auth`
`CLEMENTINE_AUTH_PORT=`	CLEMENTINE UI port
	By default: `9000`
`CLEMENTINE_AUTH_DOMAIN=`	Application domain used to generate links on email
	Depending on the configuration of the network environment, this can be a name domain, for example, `clementine.local` or the IP address of a service available on the network
	This parameter is optional and is only required if you use an email address to register new users and reset passwords
	By default: `127.0.0.1`
`CLEMENTINE_AUTH_PROTOCOL=`	Protocol for working in a web environment. Depends on current infrastructure settings and security requirements
	Possible values:
	- `HTTP` — protocol without encryption;
	- `HTTPS` — protocol with SSL encryption
	By default: `HTTP`
`CLEMENTINE_AUTH_DSN=`	Connecting CLEMENTINE AUTH to the database
	By default: `postgresql://clementine:clementine@clementine_db/clementine_auth`
CLEMENTINE DEPARTMENTS configuration parameters
`CLEMENTINE_DEPARTMENTS_HOST=`	CLEMENTINE DEPARTMENTS server address
	By default: `clementine_departments`
`CLEMENTINE_DEPARTMENTS_PORT=`	CLEMENTINE UI port
	By default: `9100`
`CLEMENTINE_DEPARTMENTS_DSN=`	Port on which the Service will be launched
	By default: `postgresql://clementine:clementine@clementine_db/clementine_departments`
LUNA PLATFORM 5 configuration parameters
`LUNA_API_HOST=`	LP5 host. IP address of the server on which the LP5 is deployed
	By default: `127.0.0.1`
`LUNA_API_PORT=`	LP5 API port
	By default: `5000`
`LUNA_LICENSES_HOST=`	LUNA Licenses host
	By default: `127.0.0.1`
`LUNA_LICENSES_PORT=`	LUNA Licenses port
	By default: `5120`
`LUNA_ACCOUNT_ID=`	User account ID in LP5
	By default: `a0000000-0000-4000-a000-000000000000` ¹
LUNA Streams configuration parameters
`LUNA_STREAMS_HOST=`	LUNA Streams server address
	By default: `127.0.0.1`
`LUNA_STREAMS_PORT=`	LUNA Streams port
	By default: `5160`
VL NOTIFIER configuration and notification parameters
`VLNOTIFIER_HOST=`	Notification component server address
	By default: `vlnotifier`
`VLNOTIFIER_PORT=`	Notification component port
	By default: `9200`
`VLNOTIFIER_SUBJECT`	The text in the header of the sent email with notification
	By default: `Clementine VL Notifier`
Time tracking module configuration parameters
`VLTIMETRACKER_HOST=`	Time tracking component server address
	By default: `127.0.0.1`
`VLTIMETRACKER_PORT=`	Time tracking component port
	By default: `8003`
VL Access configuration parameters
`VLACCESS_HOST=`	Time tracking component server address
	By default: `127.0.0.1`
`VLACCESS_PORT=`	Time tracking component port
	By default: `9091`
SMTP configuration parameters
`LOG_LEVEL=`	Logging level. Available Values:
	`0` — recording only errors;
	`1` — recording errors and informational messages;
	`2` — recording errors, informational messages and debugging information
	By default: `1`
`TELEGRAM_BOT_TOKEN=`	Telegram bot token where notifications will be sent
`SMTP_SERVER=`	SMTP server address
`SMTP_PORT=`	SMTP server port. Available Values:
	`25` — no encryption;
	`465` — `SSL`;
	`587` — `TLS`
`SMTP_SENDER=`	Email of the sender to send notifications to users. For example, `robot@clementine.local`
`SMTP_LOGIN=`	Login to connect to SMTP server
`SMTP_PASSWORD=`	Password for connecting to SMTP server

The configuration parameters for the SMTP email server are optional and only required if you are using an email address to register new users and reset passwords.

The SMTP configuration parameters are also used for the notification component.

Data loading errors are written to the system log through the logging subsystem with three logging levels.

Internal errors are written to the system log using the logging subsystem:

with error severity level if the further execution of the program is impossible;
with warning severity level if the program remains functional.

Configuring the web interface#

The Service web interface is configured in the config.json configuration file (located in example-docker/config/ui/):

{
  "auth": {
    "allowPasswordChange": {
      "ui": true,
      "email": true
    }
  },
  "similarityThresholds": {
    "low": 0.75,
    "medium": 0.95
  },
  "maxImageSize": "2G"
}

Table 3. Web interface configuration parameters

Parameter	Description
allowPasswordChange	Configuring the registration type in the Service.
	All users in the Service interface are created by the administrator. The new user receives a link to his email address to continue registration (for details, see “VISIONLABS LUNA CLEMENTINE 2.0. User Manual”).
	It is also possible to create a new user with an explicit password in the Service. To do this, you need to configure the ability to set passwords in the web interface of the Service.
	By default: “ui”: `true,` “email”: `true`
similarityThresholds	The color coding of similarity thresholds:
	- similarity values below “low” will be marked in red;
	- similarity values between “low” and “medium” will be marked in yellow;
	- similarity values above “medium” will be marked in green.
	By default: `low: 0.75`, `medium": 0.95`
maxImageSize	The maximum image size.
	Changing this parameter should set `CLIENT_MAX_BODY_SIZE` for the `clementine-ui` container in`docker-compose.yml`.
	By default: `2G`

Setting up a logo in the interface#

Users can set their own logo for the interface, which will be displayed in the left corner of the top menu. To do this:

1․ Go to the media folder.

2․ Move the files with logo images in .svg format to the folder.

3․ Name the file "logo.svg" for the light theme and "dark-logo.svg" for the dark theme.

3․ In the config.json file, specify the paths for the files (Figure 2):

"logoUrl": "/static/media/logo.svg",
"darkLogoUrl": "/static/media/dark-logo.svg"

Figure 2. Paths for logo files in config.json

Launching the Service#

Go to Docker directory:

cd /var/lib/clementine/current/example-docker

To start the Service, enter the command:

./start_clementine.sh

Check the status of all running Docker-containers:

docker-compose ps

The containers must have the "UP" status:

example-docker_clementine_api_1
example-docker_clementine_auth_1
example-docker_clementine_departments_1
example-docker_clementine_db_1
example-docker_clementine_ui_1
example-docker_vlnotifier_1

Adding an administrator account#

After the Service starts, create a new account, and follow the instructions:

docker-compose exec clementine_auth python3 cli.py createaccount

Specify the login (email address) and password of the account, set the user role.

To log into the Service, you must use the specified email address as a login.

Create a new authorization for the account and follow the instructions:

docker-compose exec clementine_auth python3 cli.py createauth

Run the account role change and follow the instructions:

docker-compose exec clementine_auth python3 cli.py setaccountrole

Is an example of an identifier, not a real parameter. It is necessary to substitute ID from LP5. ↩