Skip to content

# Introduction

This document provides example steps for performing a migration of the LUNA PLATFORM environment using the Storages utility.

Migration includes both an upgrade to a newer version and a downgrade to an earlier version. Therefore, the same migration process is used for both upgrades and downgrades. This document provides step-by-step instructions for completing this task and then launching containers.

It is recommended to familiarize yourself with the Storages utility manual before deploying the LUNA PLATFORM.

> This document includes an example of LUNA PLATFORM deployment. It implements LUNA PLATFORM minimum power operating for demonstration purposes and cannot be used for the production system.

Important: Migration using Storages is only possible for LUNA PLATFORM versions v.5.46.1 and higher. To upgrade from earlier versions, please request documentation from VisionLabs specialists. Using the documentation received, upgrade to v.5.46.1 (with Storages support), then use this guide to migrate to the target version of LUNA PLATFORM.

Note that starting from versions 5.46.1, there may have been critical changes, such as updates to thresholds or neural network versions, deprecation of FaceDetV1 and FaceDetV2 detectors, and others (see the full list in the "Key changes from previous versions" section). A change such as updating the thresholds may give a different result when performing estimation than in the old build. This manual is for upgrading from a previous build and these commands are for advanced users only. These commands are marked accordingly. Be careful and do not perform unnecessary actions if you are updating from from LUNA PLATFORM v.5.128.0.

To migrate LUNA PLATFORM, you need to perform the actions from the following sections:

- "Before migrate" — Actions to unpack archives, prepare directories, configure a license, etc. Some actions may be optional.
- "Run third-party services" — Launching PostgreSQL, Redis, Influx databases.
- "Migrate environment" — performing environment migration (updating or rolling back versions of databases, settings, etc.)
- "Services launch" — Launching containers with LUNA PLATFORM services.

The section "Additional information" provides useful information on the description of service launch parameters, Docker commands, using Grafana, etc.

This manual is designed with an assumption that:

- You already have a previous minor version of LUNA PLATFORM installed and the required environment is up and running at your server(s).
- LP 5 is installed according to LP 5 installation manual, and the default paths are used. Otherwise, you should consider your manual changes during the migration process.

# Before migrate

Make sure that you are the root user before migration procedure!

Before migrating, you must perform the following actions, which apply to both upgrading and downgrading LUNA PLATFORM:

1․ See key changes from previous versions if you are migrating from a version other than LUNA PLATFORM v.5.128.0.

2․ Create backups.

3․ Prepare to change the version of the neural network to extract descriptors if necessary.

4․ Delete old symbolic link.

5․ Unpack the distribution of the new version of LUNA PLATFORM.

6․ Create new symbolic link.

7․ Change group and owner for new directories.

8․ Save user configurations of the Configurator service if they have changed.

9․ Create log directories for new services if you have previously used logging to file.

10․ Update license if necessary.

11․ Set up GPU computing if you plan to use GPU.

12․ Remove old containers if necessary.

Important: The migration procedure using the Storages utility is universal and allows both upgrading and downgrading the platform version. All subsequent steps apply to both scenarios.

## Key changes from previous versions

Note: If you are migrating between adjacent versions of LUNA PLATFORM, you can skip this section.

Below are key changes from previous versions of LUNA PLATFORM that may impact your migration process. Some of these changes require mandatory actions to be performed, otherwise the LUNA PLATFORM may not start or function incorrectly.

> Not all changes are listed in the table below. See the LUNA PLATFORM release notes for details on all changes.

Version | Changes | Mandatory actions
--- | --- | ---
5.96.0 | Now, by default, the 65th neural network model is used for extracting face descriptors. | Read the information described in the section "Prepare to change the neural network version", and perform certain actions before launching Remote SDK or Video Agent, because the default version has changed.
5.88.0 | Now Redis in the LUNA PLATFORM delivery is password protected. The password is passed when starting the Redis container in the Docker Compose script. Also, in the documentation, the default password has been passed to the Redis container startup command. | Since some of the LUNA PLATFORM settings require authentication to Redis, and Redis is now password-protected by default, when upgrading, you must requiredly add a password to the following settings: `LUNA_ATTRIBUTES_DB`, `REDIS_DB_ADDRESS`, `TASKS_REDIS_DB_ADDRESS`.
5.84.0 | The 110th neural network model for extracting body descriptors has been removed from the Remote SDK container. Now, by default, the 116th neural network model is used for extracting body descriptors. | Read the information described in the section "Prepare to change the neural network version", and perform certain actions before launching Remote SDK, because the default version has changed.
5.76.0 | The "INFLUX_MONITORING" section has been renamed to "LUNA_MONITORING" section. | When preparing the environment using Storages with different entities specified (e.g. "luna_prepare configs", "luna_prepare database", etc.), you must update the environment for InfluxDB (arguments "aggregated_influx_bucket" and "influx_bucket") strictly after migrating the settings (argument "configs"). Otherwise, the environment will not be prepared correctly. When performing the entire environment using the argument "all_entities", no additional actions are required.
5.72.1 | The 107th neural network model for extracting body descriptors has been removed from the Remote SDK container. | Read the information described in the section "Prepare to change the neural network version" and perform certain actions before launching the Remote SDK if the 107th model was used.
5.67.0 | The threshold value from the "redetect_score_threshold" setting of the "LUNA_REMOTE_SDK_FACE_DETECTOR_SETTINGS" section has been updated from "0.3" to "0.5". | Update the threshold value according to user logic.
5.62.3 | Now, by default, the neural network model 62 for extracting face descriptors is used. | Read the information described in the section "Prepare to change the neural network version", and perform certain actions before launching Remote SDK, because the default version has changed.
5.53.0 | The VisionLabs image for PostgreSQL has been updated from version 12 to version 16. | If this image was previously used, then you need to perform the migration yourself according to official documentation.

## Create backups

Creating backups will enable you to restore your system in case of any problems during the migration process.

For production use of LUNA PLATFORM, backups are mandatory to prevent the loss of important data.

If the data is used only for testing purposes and its loss is not critical, backups are not necessary. However, it is recommended to create copies of the following components:

- Backups of all databases used with LUNA PLATFORM;
- Backup of Image Store buckets;
- Backup of LUNA PLATFORM service settings.

### Backup of PostgreSQL DMBS

A PostgreSQL database backup is performed using the pg_dumpall or pg_dump utilities.

Use the official instructions to perform a backup.

### Backup of Influx database

An InfluxDB backup is performed using the influxd backup command.

Use the official instructions to perform a backup.

### Backup of Image Store buckets

Create a backup of buckets using the following command:

    cp -r /var/lib/luna/image_store /var/lib/luna/BACKUP_image_store

### Dump file with service settings

Custom values of settings for LUNA PLATFORM services (all except the Configurator service) are automatically migrated using the Configurator service migration mechanism.

If the migration of the service for some reason has lost the user configuration or the user just wants to store the old service settings for different LP versions, then you can create a dump file.

To create a dump file, use the following command (may be executed from anywhere on your server):

    wget -O /var/lib/luna/BACKUP_settings_dump.json 127.0.0.1:5070/1/dump

or

    curl 127.0.0.1:5070/1/dump > /var/lib/luna/BACKUP_settings_dump.json

Important: This file will not be used during a normal installation of LUNA PLATFORM. To apply the saved settings, you need to run the Storages command to load the dump (`load_dump`) with the `--dump-file` argument: `--dump-file=/srv/settings_dump.json`. You can apply full settings dump on an empty database only. See the detailed information in the Load_dump command section.

## Prepare to change the neural network version

In some LUNA PLATFORM builds, neural network models for extracting face and body descriptors are removed, and the default model usage settings are changed. See the section "Key changes from previous versions" for more information about these changes.

If you are updating from a version where neural networks were removed, and in the previous build one of the deleted models was specified in the "DEFAULT_FACE_DESCRIPTOR_VERSION" or "DEFAULT_HUMAN_DESCRIPTOR_VERSION" settings, then the Remote SDK service will not start.

The current build of LUNA PLATFORM supports neural network models for extracting descriptors:

Object from which descriptor is extracted | Neural network models | Default model
--- | --- | ---
Face | 59, 60, 62, 65 | 65
Body | 108, 116 | 116

It is necessary to perform one of the additional actions depending on the following scenarios of the work:

Continuation of the use of missing neural networks

Request to VisionLabs an old neural network model and prepare it for transfer to the new Remote SDK or Video Agent container after its launch (see instructions in the section "Use non-delivery neural network model" of administrator manual).

Switching to new version of the neural network with continuation of the use of old descriptors

You can switch to a new version while continuing to use old templates by completing the Additional extraction task. This will convert old templates to the new version of the neural network.

In LUNA PLATFORM releases, support for a model is first added, and only then, after several versions, the default model is updated, which ensures that the new model is available in the container when upgrading from a previous version. However, if you are upgrading from an old version of LUNA PLATFORM, it is important to make sure that the old version of the Remote SDK or Video Agent container has the required model to perform the Additional extraction task. The model can be requested from VisionLabs specialists or transferred from a newer version of the Remote SDK or Video Agent container.

Important: An exception is the process of additional extraction body descriptors, which allows you to use the Additional extraction task after launching a new Remote SDK or Video Agent container, which is guaranteed to have a new model. In this case, you do not need to worry about whether the neural network model is in the old container.

Steps to migrate to a new version of the neural network while continuing to use old descriptors:

- Perform preliminary actions if you are not migrating from a previous version of LUNA PLATFORM:

  - additional extraction for body descriptors: If you prefer to run the Additional extraction task before migration, be sure to check that the old Remote SDK or Video Agent container has the new neural network model. If you prefer to run the Additional extraction task after migration (recommended), no additional actions are required.
  - additional extraction for face descriptors: Be sure to check that the Remote SDK or Video Agent container has the new neural network model.

  You can check that the model is present using the following command:

      docker exec -it luna-remote-sdk ls fsdk/data

  The directory should contain files like `cnn<model>_<architecture>.plan` and `cnndescriptor_<nn_version>.conf`.

- Run the Additional extraction task:

  - additional extraction for body descriptors: before or after the migration
  - additional extraction for face descriptors: before the migration

See the "Additional extraction task" section in the administrator manual.

- Specify the new neural network version in the "DEFAULT_FACE_DESCRIPTOR_VERSION" or "DEFAULT_HUMAN_DESCRIPTOR_VERSION" settings according to the "Changing the neural network version in Configurator" section:

  - additional extraction for body descriptors:
    - after the migration if the Additional extraction task is run before the migration
    - before the migration if the Additional extraction task is run after the migration (otherwise the Remote SDK or Video Agent service may not start if the model was removed from the container)
  - additional extraction for face descriptors: after the migration

Switching to new version of the neural network with cessation of the use of old descriptors

Specify the new version of the neural network in the settings "DEFAULT_FACE_DESCRIPTOR_VERSION" or "DEFAULT_HUMAN_DESCRIPTOR_VERSION" before launching the Remote SDK or Video Agent service in accordance with the section "Change neural network version using Configurator".

> If it is not necessary to extract body descriptors, then you can disable the use of the neural network using the command `--env=EXTEND_CMD="--enable-body-descriptor-estimator=0"` when launching Remote SDK or Video Agent container (see the detailed information in the section "Enable/disable several estimators and detectors" of the administrator manual).

### Change neural network version using Configurator

To change the version of the neural network, you must perform the following steps:

- Open the Configurator user interface `http://<configurator_server_ip>:5070`.
- Enter the name of the setting "DEFAULT_FACE_DESCRIPTOR_VERSION" or "DEFAULT_HUMAN_DESCRIPTOR_VERSION" in the "Setting name" field and click "Apply Filters".
- Set the necessary neural network model in the "DEFAULT_FACE_DESCRIPTOR_VERSION" or "DEFAULT_HUMAN_DESCRIPTOR_VERSION" setting.
- Save the changes by clicking the "Save" button.

Important: Changing the "DEFAULT_FACE_DESCRIPTOR_VERSION" setting applies to two containers - Remote SDK and Video Agent. Accordingly, the neural network model for face extraction must be present in both containers. If it is present only in one container, the second one will not be able to start.

## Delete old symbolic link

Delete the symbolic link to the previous minor version directory using the following command:

    rm -f /var/lib/luna/current

## Distribution unpacking

The distribution package is an archive luna_v.5.130.0, where v.5.130.0 is a numerical identifier, describing the current LUNA PLATFORM version.

The archive includes configuration files, required for installation and exploitation. It does not include Docker images for the services. They should be downloaded from the Internet.

Move the distribution package to the directory on your server before the installation. For example, move the files to `/root/` directory. The directory should not contain any other distribution or license files except the target ones.

Move the distribution to the created directory.

    mv /root/luna_v.5.130.0.zip /var/lib/luna

Install the unzip archiver if it is necessary.

    dnf install -y unzip

Go to the folder with distribution.

    cd /var/lib/luna

Unzip files.

    unzip luna_v.5.130.0.zip

## Symbolic link creation

Create a symbolic link.

> The link indicates that the current version of the distribution file is used to run LUNA PLATFORM.

    ln -s luna_v.5.130.0 current

## Changing group and owner for directories

LP services are launched inside the containers by the "luna" user. Therefore, it is required to set permissions for this user to use the mounted volumes.

Go to the LP "example-docker" directory.

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

Create a directory to store settings.

    mkdir luna_configurator/used_dumps

Set permissions for the user with UID 1001 and group 0 to use the mounted directories.

    chown -R 1001:0 luna_configurator/used_dumps

## Save user configurations of the Configurator

Note: Skip this step if the Configurator settings have not been changed.

The configurations of the Configurator service are not automatically migrated, unlike the configurations of all other services.

If your previous LP version was used with non-default Configurator service configurations, back up your "luna_configurator_postgres.conf" config file in the separate directory on your server.

    cp /var/lib/luna/<your_previous_lp_version>/example-docker/luna_configurator/configs/luna_configurator_postgres.conf /var/lib/luna/BACKUP_luna_configurator_postgres.conf

This backup must be mounted to the Configurator service container that is being run.

If you are not sure if the Configurator service configurations have changed, you can compare the created backup with the Configurator configurations from the current distribution using the following command:

    diff /var/lib/luna/current/example-docker/luna_configurator/configs/luna_configurator_postgres.conf /var/lib/luna/BACKUP_luna_configurator_postgres.conf

## Create log directory for new services

Skip this section if no logs were previously stored on the server.

In the target version of LUNA PLATFORM, new services could appear, for which you need to create directories with logs. It depends on the version from which you are migrating. For example, version 5.30.0 introduced the Accounts service.

> See "Logging to server" section if you have not previously used logging to a file, but want to enable it.

Following are the commands to create directories for all existing services. These commands will create and assign permissions only to missing directories.

    mkdir -p /tmp/logs/configurator /tmp/logs/image-store /tmp/logs/accounts /tmp/logs/faces /tmp/logs/licenses /tmp/logs/events /tmp/logs/python-matcher /tmp/logs/handlers /tmp/logs/remote-sdk /tmp/logs/tasks /tmp/logs/tasks-worker /tmp/logs/sender /tmp/logs/api /tmp/logs/admin /tmp/logs/luna-video-agent /tmp/logs/luna-video-manager /tmp/logs/luna-streams-retranslator

    chown -R 1001:0 /tmp/logs/configurator /tmp/logs/image-store /tmp/logs/accounts /tmp/logs/faces /tmp/logs/licenses /tmp/logs/events /tmp/logs/python-matcher /tmp/logs/handlers /tmp/logs/remote-sdk /tmp/logs/tasks /tmp/logs/tasks-worker /tmp/logs/sender /tmp/logs/api /tmp/logs/admin /tmp/logs/luna-video-agent /tmp/logs/luna-video-manager /tmp/logs/luna-streams-retranslator

If you need to use the Python Matcher Proxy service, then you need to additionally create the `/tmp/logs/python-matcher-proxy` directory and set its permissions.

## License update

To update the license, follow these steps:

- Follow the steps from license activation manual.
- Set settings for HASP license or Guardant license before starting Licenses container.

### Actions from License activation manual

Open the license activation manual and follow the necessary steps.

Note: This action is mandatory. The license will not work without following the steps to activate the license from the corresponding manual.

Note. When updating Guardant Control Center, you must re-issue the license key.

## Calculations using GPU

You can use GPU for the general calculations performed by Remote SDK.

Skip this section if you are not going to utilize GPU for your calculations.

You need to install NVIDIA Container Toolkit to use GPU with Docker containers. The example of the installation is given below.

    distribution=$(. /etc/os-release;echo $ID$VERSION_ID)

    curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.repo | tee /etc/yum.repos.d/nvidia-docker.repo

    dnf install -y nvidia-container-toolkit

    systemctl restart docker

Check the NVIDIA Container toolkit operating by running a base CUDA container (this container is not provided in the LP distribution and should be downloaded from the Internet):

    docker run --rm --gpus all nvcr.io/nvidia/cuda:12.4.0-base-ubi8 nvidia-smi

See the NVIDIA documentation for additional information.

> Attributes extraction on the GPU is engineered for maximum throughput. The input images are processed in batches. This reduces computation cost per image but does not provide the shortest latency per image.

> GPU acceleration is designed for high load applications where request counts per second consistently reach thousands. It won’t be beneficial to use GPU acceleration in non-extensively loaded scenarios where latency matters.

## Remove old containers (optional)

Note: Removing old containers is not necessary when preparing your environment using the Storages utility. It is enough to simply limit the number of queries to the database, but in this case it is necessary to understand certain consequences. See the "Recommendations services behavior during environment preparation" section in the Storages utility manual.

Important: The Image Store service is an exception. During the preparation of the bucket environment, Storages makes a request to the Image Store service to obtain information about the buckets. If the Image Store container is removed, the request will fail and a migration error will occur. To migrate buckets when the Image Store container is removed, you must explicitly tell the Storages utility the location of the buckets using the `--local-buckets` or `--s3-buckets` arguments. When using local buckets, you must also mount the directory with the buckets to the Storages container.

Before launching the containers of the current minor version, stop all LUNA PLATFORM related containers of the previous minor version. It is not necessary to delete third-party services containers.

For example, to remove LP containers only use the following command:

    docker container rm -f luna-configurator luna-sender luna-tasks luna-handlers luna-remote-sdk luna-python-matcher luna-events luna-licenses luna-faces luna-image-store luna-admin luna-api luna-tasks-worker luna-accounts luna-lambda luna-video-agent luna-video-manager luna-streams-retranslator

To see the containers names or IDs, use the following command:

    docker ps -a

It is also recommended to delete old images of the containers to free space. You can use the following command to delete all unused images.

> If there is enough space on the server it is recommended to perform this action only after new version of LP is successfully launched.

> The command deletes all the unused images, not only the images related to LP.

    docker image prune -a -f

# Run third-party services

This section describes the launching of databases in docker containers. They must be launched before environment preparation and LP services.

## InfluxDB

Note: If you haven't deleted the old container, skip this step.

Monitoring LUNA PLATFORM services requires running the Influx 2.0.8-alpine database. Below are the commands to launch the InfluxDB container.

> For information on selecting a database for monitoring and working with Prometheus, see the "Monitoring" section of the Administrator's Guide.

Note: Alternatively, you can use the ClickHouse database. For instructions on launching it, see the section "Using ClickHouse as an Alternative to InfluxDB". For information on selecting a database for monitoring, see the "Monitoring" section of the Administrator's guide.

> If necessary, you can configure the visualization of monitoring data using the LUNA Dashboards service, which includes a configured Grafana data visualization system. In addition, you can launch the Grafana Loki tool for advanced work with logs. See the instructions for launching LUNA Dashboards and Grafana Loki in the "Monitoring and logs visualization using Grafana" section.

Note: If necessary, you can use an external InfluxDB 2.0.8-alpine. In this case, you can skip the command below, but you will have to set custom settings for each LUNA PLATFORM service.

Use the `docker run` command with these parameters:

    docker run \
    -e DOCKER_INFLUXDB_INIT_MODE=setup \
    -e DOCKER_INFLUXDB_INIT_BUCKET=default \
    -e DOCKER_INFLUXDB_INIT_USERNAME=luna \
    -e DOCKER_INFLUXDB_INIT_PASSWORD=password \
    -e DOCKER_INFLUXDB_INIT_ORG=luna \
    -e DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=kofqt4Pfqjn6o0RBtMDQqVoJLgHoxxDUmmhiAZ7JS6VmEnrqZXQhxDhad8AX9tmiJH6CjM7Y1U8p5eSEocGzIA== \
    -v /etc/localtime:/etc/localtime:ro \
    -v /var/lib/luna/influx:/var/lib/influxdb2 \
    --restart=always \
    --detach=true \
    --network=host \
    --name influxdb \
    dockerhub.visionlabs.ru/luna/influxdb:2.0.8-alpine

> The command above creates a default bucket. The bucket for storing monitoring data LUNA PLATFORM will be created during the environment preparation step using the Storages utility. Note that attempting to prepare an environment (create a bucket) for InfluxDB via the Storages utility will fail if the bucket already exists and the `-ii` flag (ignore the entity if it already exists) is not specified in the environment preparation command.

## PostgreSQL

### Migrate PostgreSQL 12 to PostgreSQL 16

In LUNA PLATFORM v.5.53.0, the VisionLabs image for PostgreSQL has been updated from version 12 to version 16.

If this image was previously used, then you need to perform the migration yourself according to official documentation. If necessary, you can continue using PostgreSQL 12 by specifying the image "postgis-vlmatch:12" in the container launch command.

Mounting PostgreSQL 12 data from the directory "/var/lib/luna/postgres" into a container for PostgreSQL 16 will result in an error.

### Launch PostgreSQL

Note: If you haven't deleted the old container, skip this step.

Use the following command to launch PostgreSQL.

Use the following command to launch PostgreSQL.

    docker run \
    --env=POSTGRES_USER=luna \
    --env=POSTGRES_PASSWORD=luna \
    --shm-size=1g \
    -v /var/lib/luna/postgresql/data/:/var/lib/postgresql/data/ \
    -v /etc/localtime:/etc/localtime:ro \
    --name=postgres \
    --restart=always \
    --detach=true \
    --network=host \
    --health-cmd="pg_isready -U luna -d postgres" \
    dockerhub.visionlabs.ru/luna/postgis-vlmatch:16.1

`-v /var/lib/luna/current/example-docker/postgresql/data/:/var/lib/postgresql/data/` — The volume command enables you to mount the "data" folder to the PostgreSQL container. The folder on the server and the folder in the container will be synchronized. The PostgreSQL data from the container will be saved to this directory.

`--network=host` — If you need to change the port for PotgreSQL, you should change this string to `-p 5440:5432`. Where the first port `5440` is the local port and `5432` is the port used inside the container.

> You should create all the databases for LP services manually if you are going to use an already installed PostgreSQL.

## Redis

Note: If you haven't deleted the old container, skip this step.

Note: Redis is set to `lunapass` by default when starting. It is highly recommended to change the password for increased security. Note that the password must be specified in the corresponding service setting, for example, in the "password" parameter of the "LUNA_ATTRIBUTES_DB" group of the Events service. By default, the dump file already contains the password `lunapass`.

Use the following command to launch Redis.

    docker run \
    -v /etc/localtime:/etc/localtime:ro \
    --name=redis \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/redis:7.2 \
    redis-server --requirepass lunapass

# Migrate environment

Environment migration is performed using the Storages utility. Using the command below will execute:

- Creating buckets in InfluxDB for monitoring work (if not done previously)
- Creating buckets for the Image Store service (if not done previously)
- Preparing the Influx database for collecting aggregated statistics using the Admin service (if not done previously)
- Database migration
- Migration of settings to the Configurator database

> Important: The Storages utility supports migration to both newer and older versions of LUNA PLATFORM. When migrating to a previous version, the appropriate rollback scripts for changes to databases and settings will be executed.

## Select services

Note: Perform the settings in this section only if you need to launch services that are not included in the standard LUNA PLATFORM configuration.

You can migrate the environment either for each service separately or for all services at once. In this documentation, the environment is migrated with the `all_entities` argument, meaning that all entities for the set of services defined in the Storages configuration will be updated.

However, after migrating the environment, you must enable usage of the corresponding services in the LUNA PLATFORM settings.

Thus, selecting services for updating the environment and further launch consists of two stages:

- selecting services in the "ADDITIONAL_SERVICE_USAGE" setting in the Storages configuration file so that the Storages utility can update all the necessary entities for future services
- selecting services in the "ADDITIONAL_SERVICE_USAGE" setting in the LUNA PLATFORM settings to tell the system which services to use. You can load the setting either using a dump file or in the Configurator settings after it is launched directly.

> Since the standard dump file overwrites existing settings from the previous version of LUNA PLATFORM during migration, it is recommended to select services in the Configurator settings.

As a result, to select services, you need to:

- fill in the Storages configuration file
- select services to launch using the Configurator service

List of services for which environment migration can be enabled/disabled:

- Faces
- Events
- Image Store
- Tasks
- Sender
- Handlers
- Remote SDK
- Python Matcher
- Python Matcher Proxy (disabled by default)
- Lambda (disabled by default)
- Video Manager (disabled by default)
- Video Agent (disabled by default)
- Streams Retranslator (disabled by default)

> Working with the Lambda service is only possible when deploying LUNA PLATFORM services in Kubernetes. For more information, see the Deploying LP on Kubernetes guide.

Important! Disabling environment migration for core services has certain consequences. For more information, see the "Services to Disable" section of the Administrator's Guide.

## Setting Storages configuration file

Note: Skip this section if you want to launch LUNA PLATFORM in a standard configuration.

When migrating the environment, the Storages service configuration file is used, which contains:

- a list of services for which the environment will be updated
- database connection settings
- bucket connection settings
- S3 connection settings
- monitoring settings
- other

This file must be mounted to the Storages service container and specified in the `--config` argument.

As an example, the `storages_config.conf` file is mounted, containing standard settings for deploying LUNA PLATFORM in a minimal base configuration.

Edit the Storages configuration file to specify custom settings:

    vi /var/lib/luna/current/extras/conf/storages_config.conf

## Migrate environment command

> Before performing an environment migrate, make sure that all services you plan to use are enabled in the "ADDITIONAL_SERVICES_USAGE" setting of the Storages configuration file.

You can migrate the environment using the following command:

> The command below is an example for upgrading to the latest version of LUNA PLATFORM. If you need to migrate to a different version, replace the `--platform_version` and `storages` image values ​​with the target ones.

    docker run \
    --rm \
    --network=host \
    -v /var/lib/luna/current/extras/conf/storages_config.conf:/srv/storages_config.conf \
    -v /var/lib/luna/image_store/:/srv/local_storage/ \
    dockerhub.visionlabs.ru/luna/storages:v.0.104.0 \
    bash -c "luna_prepare prepare all_entities \
        --platform_version=v.5.130.0 \
        --profile=common \
        --config=/srv/storages_config.conf \
        --monitoring-ttl=30 \
        --local-buckets=/srv/local_storage"

Here:

- `-v /var/lib/luna/current/extras/conf/storages_config.conf:/srv/storages_config.conf` — Command to mount the Storages configuration file.
- `-v /var/lib/luna/image_store/:/srv/local_storage/` — Command to mount a directory with Image Store buckets.
- `luna_prepare prepare all_entities` — — Command "prepare" to prepare all entities.
- `--platform_version` — Named argument containing the LUNA PLATFORM version.
- `--profile` — Named argument containing the profile (list of services) `backports`, which means that the environment will be prepared for all services.
- `--config=/srv/storages_config.conf` — Named argument containing the address of the configuration file for use by the Storages service.
- `--monitoring-ttl=30` — Named argument that allows you to configure the retention policy for non-aggregated monitoring data. It specifies the maximum period in days that data will be stored in the monitoring system before being automatically deleted.
- `-local-buckets=/srv/local_storage` — Named argument containing the directory where the Image Store buckets should be created.

If additional services were enabled in the Storages configuration file, you must also enable their use in the "ADDITIONAL_SERVICES_USAGE" setting in the Configurator service (See Selecting services to launch using the Configurator service).

# Services launch

This section provides examples of commands for launching LUNA PLATFORM services.

LUNA PLATFORM services must be launched in the following sequence:

- Databases, Balancers, HASP service and other third-party party software.
- Configurator
- Image Store
- Accounts
- Licenses
- Faces
- Events
- Python Matcher
- Python Matcher Proxy. The service is disabled by default
- Remote SDK
- Handlers
- Tasks
- Sender
- Streams Retranslator
- Video analytics services
- API
- Admin

It is recommended to launch containers one by one and wait for the container status to become "up" (use the `docker ps` command).

Some of these services are optional and you can disable their use. It is recommended to use Events, Tasks, Sender and Admin services by default. See the "Select services" section for details.

When launching each service, certain parameters are used, for example, `--detach`, `--network`, etc. See the section "Launching parameters description" for more detailed information about all launch parameters of LUNA PLATFORM services and databases.

See the "Docker commands" section for details about working with containers.

## Configurator

### Run Configurator container

Note: Configurator service configurations are not automatically migrated, unlike all other service configurations. If the configurations of the Configurator service were changed in the previous version of LP and you need to save custom values, then in the command below you need to replace the path `/var/lib/luna/current/example-docker/luna_configurator/configs/luna_configurator_postgres.conf` with the path with a backup copy of the configurations Configurator service `/var/lib/luna/BACKUP_luna_configurator_postgres.conf` (see "Save user configurations of the Configurator" section).

Use the `docker run` command with these parameters to launch Configurator:

> The following command is an example of starting the Configurator service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Configurator image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=PORT=5070 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /var/lib/luna/current/example-docker/luna_configurator/configs/luna_configurator_postgres.conf:/srv/luna_configurator/configs/config.conf \
    -v /tmp/logs/configurator:/srv/logs \
    --name=luna-configurator \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-configurator:v.2.4.26

> At this stage, you can activate logging to file if you need to save them on the server (see the "Logging to server" section).

### Selecting services to launch using the Configurator service

> Skip this section if you are running LUNA PLATFORM in a standard configuration.

Note: Before selecting services, make sure you have prepared the environment for the required services. See "Select services".

To enable/disable services, do the following:

- go to the Configurator service interface `http://<configurator_server_ip>:5070/`;

- enter the value "ADDITIONAL_SERVICES_USAGE" in the "Setting name" field and click "Apply Filters";

- for each service in the list, specify the value "true" (enable) or "false" (disable) depending on whether you need to use it;

- click "Save".

## Image Store

### Image Store container launch

Note: If you are not going to use the Image Store service, do not launch this container and disable the service utilization. See section "Select services".

Use the following command to launch the Image Store service:

> The following command is an example of starting the Image Store service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Image Store image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5020 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    -v /var/lib/luna/image_store/:/srv/local_storage/ \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/image-store:/srv/logs \
    --name=luna-image-store \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-image-store:v.3.19.0

Here `-v /var/lib/luna/image_store/:/srv/local_storage/` is the data from the specified folder is added to the Docker container when it is launched. All the data from the specified Docker container folder is saved to this directory.

> If you already have a directory with LP buckets you should specify it instead of `/var/lib/luna/image_store/`.

## Accounts

### Accounts container launch

Use the following command to launch the service:

> The following command is an example of starting the Accounts service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Accounts image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5170 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/accounts:/srv/logs \
    --name=luna-accounts \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-accounts:v.0.8.0

## Licenses

Note: To use a trial license, it is required to launch the Licenses service on the same server where trial license is being used.

### Specify license settings using Configurator

Follow the steps below to set the settings for HASP-key or Guardant-key.

#### Specify HASP license settings

Note: Perform these actions only if the HASP key is used. See the "Specify Guardant license settings" section if the Guardant key is used.

To set the license server address, follow these steps:

- Go to the Configurator service interface `http://<configurator_server_ip>:5070/`.

- Specify the "LICENSE_VENDOR" value in the "Setting name" field and click "Apply Filters".

- Set the IP address of the server with your HASP key in the field "server_address" in the format "127.0.0.1".

- Click "Save".

> If the license is activated using the HASP key, then two parameters "vendor" and "server_address" must be specified. If you want to change the HASP protection to Guardant, then you need to add the "license_id" field.

#### Specify Guardant license settings

Note: Perform these actions only if the Guardant key is used. See the "Specify HASP license settings" section if the HASP key is used.

To set the license server address, follow these steps:

- Go to the Configurator service interface `http://<configurator_server_ip>:5070/`.

- Enter the value "LICENSE_VENDOR" in the "Setting name" field and click "Apply Filters".

- Set the IP address of the server with your Guardant key in the "server_address" field.

- Set the license ID in the format `0x<your_license_id>`, obtained in the section "Save license ID" in the License activation manual, in the "license_id" field.

- Click "Save".

> If the license is activated using the Guardant key, then three parameters "vendor", "server_address" and "license_id" must be specified. If you want to change the Guardant protection to HASP, then you need to delete the "license_id" field.

### Licenses container launch

Use the following command to launch the service:

> The following command is an example of starting the Licenses service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Licenses image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5120 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/licenses:/srv/logs \
    --name=luna-licenses \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-licenses:v.0.18.0

## Faces

### Faces container launch

Note: If you are not going to use the Faces service, do not launch this container and disable the service utilization. See section "Select services".

Use the following command to launch the service:

> The following command is an example of starting the Faces service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Faces image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5030 \
    --env=WORKER_COUNT=2 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/faces:/srv/logs \
    --name=luna-faces \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-faces:v.4.16.26

## Events

### Events container launch

Note: If you are not going to use the Events service, do not launch this container and disable the service utilization. See section "Select services".

Use the following command to launch the service:

> The following command is an example of starting the Events service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Events image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5040 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/events:/srv/logs \
    --name=luna-events \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-events:v.4.28.0

## Python Matcher services

For matching tasks, you can use either only the Python Matcher service, or additionally use the Python Matcher Proxy service, which redirects matching requests to either the Python Matcher service or matching plugins. This section describes how to use Python Matcher without Python Matcher Proxy.

> You need to use the Python Matcher Proxy service only if you are going to use matching plugins. Using Python Matcher Proxy and running the corresponding docker container are described in the "Use Python Matcher with Python Matcher Proxy" section.

> See the description and usage of matching plugins in the administrator manual.

### Use Python Matcher without Python Matcher Proxy

The Python Matcher service with matching by the Faces DB is enabled by default after launching.

The Python Matcher service with matching by the Events is also enabled by default. You can disable it (see "Select services" section). Thus, the Events service will not be used for LUNA PLATFORM.

The Python Matcher that matches using the matcher library is enabled when "CACHE_ENABLED" is set to "true" in the "DESCRIPTORS_CACHE" setting.

> A single image is downloaded for the Python Matcher service and the Python Matcher Proxy service.

### Python Matcher container launch

Use the following command to launch the service:

> The following command is an example of starting the Python Matcher service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Python Matcher image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5100 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/python-matcher:/srv/logs \
    --name=luna-python-matcher \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-python-matcher:v.1.20.10

## Remote SDK

### Change the neural network model for extracting descriptors

Some builds of LUNA PLATFORM remove the neural network models for extracting descriptors of faces and bodies, and also change the default settings for using models.

If you are upgrading from a version where neural networks were removed, and in the previous build one of the deleted models was specified in the "DEFAULT_FACE_DESCRIPTOR_VERSION" or "DEFAULT_HUMAN_DESCRIPTOR_VERSION" settings, then the service will not start unless you do one of the following actions:

- request old neural network model from VisionLabs specialists and transfer it to new container
- switch to new version of the neural network, having previously completed the Additional extraction task to re-extract existing descriptors using the new version of the neural network for their further use
- switch to new version of the neural network with cessation of the use of old descriptors

See "Prepare to change the neural network version" for details.

### Remote SDK container launch

Note: If you are not going to use the Remote SDK service, do not launch this container and disable the service utilization. See section "Select services".

You can run the Remote SDK service utilizing CPU (set by default) or GPU.

> By default, the Remote SDK service is launched with all estimators and detectors enabled. If necessary, you can disable the use of some estimators or detectors when launching the Remote SDK container. Disabling unnecessary estimators enables you to save RAM or GPU memory, since when the Remote SDK service launches, the possibility of performing these estimates is checked and neural networks are loaded into memory. If you disable the estimator or detector, you can also remove its neural network from the Remote SDK container. See the "Enable/disable several estimators and detectors" section of the administrator manual for more information.

Run the Remote SDK service using one of the following commands according to the utilized processing unit.

#### Run Remote SDK utilizing CPU

Use the following command to launch the Remote SDK service using CPU:

> The following command is an example of starting the Remote SDK service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Remote SDK image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5220 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/remote-sdk:/srv/logs \
    --network=host \
    --name=luna-remote-sdk \
    --restart=always \
    --detach=true \
    dockerhub.visionlabs.ru/luna/luna-remote-sdk:v.0.27.3

#### Run Remote SDK utilizing GPU

The Remote SDK service does not utilize GPU by default. If you are going to use the GPU, then you should enable its use for the Remote SDK service in the Configurator service.

If you need to use the GPU for all estimators and detectors at once, then you need to use the "global_device_class" parameter in the "LUNA_REMOTE_SDK_RUNTIME_SETTINGS" section. All estimators and detectors will use the value of this parameter if the "device_class" parameter of their settings like "LUNA_REMOTE_SDK_estimator-or-detector-name_SETTINGS.runtime_settings" is set to "global" (by default for all estimators and detectors).

If you need to use the GPU for a specific estimator or detector, then you need to use the "device_class" parameter in sections like "LUNA_REMOTE_SDK_estimator-or-detector-name_SETTINGS.runtime_settings".

See section "Calculations using GPU" for additional requirements for GPU utilization.

Use the following command to launch the Remote SDK service using GPU:

> The following command is an example of starting the Remote SDK service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Remote SDK image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5220 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    --gpus device=0 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/remote-sdk:/srv/logs \
    --network=host \
    --name=luna-remote-sdk \
    --restart=always \
    --detach=true \
    dockerhub.visionlabs.ru/luna/luna-remote-sdk:v.0.27.3

Here `--gpus device=0` is the parameter specifies the used GPU device and enables GPU utilization. A single GPU can be utilized per Remote SDK instance. Multiple GPU utilization per instance is not available.

#### Run slim version of Remote SDK

You can run a slim version of the Remote SDK service that contains only configuration files without neural networks. It is assumed that the user himself will add the neural networks he needs to the container.

The launch of the slim version of the Remote SDK service is intended for advanced users.

To successfully launch the Remote SDK container with a custom set of neural networks, you need to perform the following actions:

- Request the required neural networks from VisionLabs.
- Place neural networks in a folder with LUNA PLATFORM installed.
- Assign appropriate rights to neural network files.
- Mount neural network files to the `/srv/fsdk/data` folder of the Remote SDK container.
- Using the arguments of the variable "EXTEND_CMD" to explicitly specify which of the neural networks should be used.

> Using the "enable-all-estimators-by-default" flag for the "EXTEND_CMD" variable, you can disable the use of all neural networks (estimators) by default, and then use special flags to explicitly specify which neural networks should be used. If you do not specify this flag or set the value "--enable-all-estimators-by-default=1", the Remote SDK service will try to find all neural networks in the container. If one of the neural networks is not found, the Remote SDK service will not start.

List of available estimators:

Argument | Description
--- | ---
--enable-all-estimators-by-default | Enable all estimators by default.
--enable-human-detector | Simultaneous detector of bodies and bodies.
--enable-face-detector | Face detector.
--enable-body-detector | Body detector.
--enable-face-landmarks5-estimator | Face landmarks5 estimator.
--enable-face-landmarks68-estimator | Face landmarks68 estimator.
--enable-head-pose-estimator | Head pose estimator.
--enable-liveness-estimator | Liveness estimator.
--enable-fisheye-estimator | FishEye effect estimator.
--enable-face-detection-background-estimator | Image background estimator.
--enable-face-warp-estimator | Face sample estimator.
--enable-body-warp-estimator | Body sample estimator.
--enable-quality-estimator | Image quality estimator.
--enable-image-color-type-estimator | Face color type estimator.
--enable-face-natural-light-estimator | Natural light estimator.
--enable-eyes-estimator | Eyes estimator.
--enable-gaze-estimator | Gaze estimator.
--enable-mouth-attributes-estimator | Mouth attributes estimator.
--enable-emotions-estimator | Emotions estimator.
--enable-mask-estimator | Mask estimator.
--enable-glasses-estimator | Glasses estimator.
--enable-eyebrow-expression-estimator | Eyebrow estimator.
--enable-red-eyes-estimator | Red eyes estimator.
--enable-headwear-estimator | Headwear estimator.
--enable-basic-attributes-estimator | Basic attributes estimator.
--enable-face-descriptor-estimator | Face descriptor extraction estimator.
--enable-body-descriptor-estimator | Body descriptor extraction estimator.
--enable-body-attributes-estimator | Body attributes estimator.
--enable-people-count-estimator | People count estimator.
--enable-deepfake-estimator | Deepfake estimator.

> See the detailed information on enabling and disabling certain estimators in the section "Enable/disable several estimators and detectors " of the administrator manual.

Below is an example of a command to assign rights to a neural network file:

    chown -R 1001:0 /var/lib/luna/current/<neural_network_name>.plan

Example of a command to run Remote SDK container with mounting neural networks for face detection and face descriptor extraction:

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5220 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    --env=EXTEND_CMD="--enable-all-estimators-by-default=0 --enable-face-detector=1 --enable-face-descriptor-estimator=1" \
    -v /var/lib/luna/current/cnndescriptor_59.conf:/srv/fsdk/data/cnndescriptor_59.conf \
    -v /var/lib/luna/current/cnn59b_cpu-avx2.plan:/srv/fsdk/data/cnn59b_cpu-avx2.plan \
    -v /var/lib/luna/current/FaceDet_v3_a1_cpu-avx2.plan:/srv/fsdk/data/FaceDet_v3_a1_cpu-avx2.plan \
    -v /var/lib/luna/current/FaceDet_v3_redetect_v3_cpu-avx2.plan:/srv/fsdk/data/FaceDet_v3_redetect_v3_cpu-avx2.plan \
    -v /var/lib/luna/current/slnet_v3_cpu-avx2.plan:/srv/fsdk/data/slnet_v3_cpu-avx2.plan \
    -v /var/lib/luna/current/LNet_precise_v2_cpu-avx2.plan:/srv/fsdk/data/LNet_precise_v2_cpu-avx2.plan \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/remote-sdk:/srv/logs \
    --network=host \
    --name=luna-remote-sdk \
    --restart=always \
    --detach=true \
    dockerhub.visionlabs.ru/luna/luna-remote-sdk:v.0.27.3

## Handlers

Note: If you are not going to use the Handlers service, do not launch this container and disable the service utilization. See section "Select services".

### Handlers container launch

Use the following command to launch the service:

> The following command is an example of starting the Handlers service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Handlers image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5090 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/handlers:/srv/logs \
    --name=luna-handlers \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-handlers:v.3.23.8

## Tasks

Note: If you are not going to use the Tasks service, do not launch the Tasks container and the Tasks Worker container. Disable the service utilization. See section "Select services".

### Tasks and Tasks Worker containers launch

Tasks service image includes the Tasks service and the Tasks Worker. They both must be launched.

> If it is necessary to use the Estimator task using a network disk, then you should first mount the directory with images from the network disk into special directories of Tasks and Tasks Worker containers. See the "Estimator task" section in the administrator manual for details.

#### Tasks Worker launch

Use the following command to launch the service:

> The following command is an example of starting the Tasks Worker service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Tasks Worker image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5051 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    --env=SERVICE_TYPE="tasks_worker" \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/tasks-worker:/srv/logs \
    --name=luna-tasks-worker \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-tasks:v.3.29.13

#### Tasks launch

Use the following command to launch the service:

> The following command is an example of starting the Tasks service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Tasks image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5050 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/tasks:/srv/logs \
    --name=luna-tasks \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-tasks:v.3.29.13

## Sender

### Sender container launch

Note: If you are not going to use the Sender service, do not launch this container and disable the service utilization. See section "Select services".

Use the following command to launch the service:

> The following command is an example of starting the Sender service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Sender image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5080 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/sender:/srv/logs \
    --name=luna-sender \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-sender:v.2.14.31

## Streams Retranslator

### Streams Retranslator container launch

Note: The Streams Retranslator service is disabled by default. To avoid an error when running, enable it. See section "Select services".

Use the following command to launch the service:

> The following command is an example of starting the Streams Retranslator service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Streams Retranslator image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5250 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/streams-retranslator:/srv/logs \
    --name=luna-streams-retranslator \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-streams-retranslator:v.0.2.6

Service uses the following ports:

- Port 8554 - used to process RTSP streams. This port is required so that the container can receive RTSP video streams from various sources (cameras, video files, etc.).
- Port 8888 - used to output an HLS stream for the GUI. This port is required to provide HLS streams to clients that can display video via HTTP.

Make sure the above ports are not occupied or redefine them when running with the custom network interface.

Note: The port for outputting the HLS stream can also be replaced in the "EXTERNAL_LUNA_STREAMS_HLS_RETRANSMISSION_ADDRESS" setting for convenience.

## Video analytics services

Note: The Video Manager and Video Agent video services are disabled by default. To avoid an error when running, enable them. See "Select services".

### Video Manager launch

Use the following command to launch the service:

> The following command is an example of starting the Video Manager service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Video Manager image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5230 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/video-manager:/srv/logs \
    --name=luna-video-manager \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-video-manager:v.1.14.3

### Change the neural network model for extracting descriptors

Some builds of LUNA PLATFORM remove the neural network models for extracting descriptors of faces and bodies, and also change the default settings for using models.

If you are upgrading from a version where neural networks were removed, and in the previous build one of the deleted models was specified in the "DEFAULT_FACE_DESCRIPTOR_VERSION" or "DEFAULT_HUMAN_DESCRIPTOR_VERSION" settings, then the service will not start unless you do one of the following actions:

- request old neural network model from VisionLabs specialists and transfer it to new container
- switch to new version of the neural network, having previously completed the Additional extraction task to re-extract existing descriptors using the new version of the neural network for their further use
- switch to new version of the neural network with cessation of the use of old descriptors

See "Prepare to change the neural network version" for details.

### Video Agent container launch

You can run the Video Agent service utilizing CPU (set by default) or GPU.

> By default, the Video Agent service is launched with all estimators and detectors enabled. If necessary, you can disable the use of some estimators or detectors when launching the Video Agent container. Disabling unnecessary estimators enables you to save RAM or GPU memory, since when the Video Agent service launches, the possibility of performing these estimates is checked and neural networks are loaded into memory. If you disable the estimator or detector, you can also remove its neural network from the Video Agent container. See the "Enable/disable several estimators and detectors" section of the administrator manual for more information.

Run the Video Agent service using one of the following commands according to the utilized processing unit.

#### Run Video Agent utilizing CPU

Use the following command to launch the Video Agent service using CPU:

> The following command is an example of starting the Video Agent service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Video Agent image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5240 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/video-agent:/srv/logs \
    --name=luna-video-agent \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-video-agent:v.1.18.1

#### Run Video Agent utilizing GPU

The Video Agent service does not utilize GPU by default. If you are going to use the GPU, then you should enable its use for the Video Agent service in the Configurator service.

If you need to use the GPU for all estimators and detectors at once, then you need to use the "global_device_class" parameter in the "LUNA_VIDEO_AGENT_RUNTIME_SETTINGS" section. All estimators and detectors will use the value of this parameter if the "device_class" parameter of their settings like "LUNA_VIDEO_AGENT_estimator-or-detector-name_SETTINGS.runtime_settings" is set to "global" (by default for all estimators and detectors).

If you need to use the GPU for a specific estimator or detector, then you need to use the "device_class" parameter in sections like "LUNA_VIDEO_AGENT_estimator-or-detector-name_SETTINGS.runtime_settings".

See section "Calculations using GPU" for additional requirements for GPU utilization.

Use the following command to launch the Video Agent service using GPU:

> The following command is an example of starting the Video Agent service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Video Agent image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5240 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    --gpus device=0 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/video-agent:/srv/logs \
    --name=luna-video-agent \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-video-agent:v.1.18.1

Here `--gpus device=0` is the parameter specifies the used GPU device and enables GPU utilization. A single GPU can be utilized per Video Agent instance. Multiple GPU utilization per instance is not available.

## API

### API container launch

Use the following command to launch the service:

> The following command is an example of starting the API service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the API image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5000 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    --name=luna-api \
    --restart=always \
    --detach=true \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/api:/srv/logs \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-api:v.6.70.0

> See the example command for creating a new account in the "Account creation" section.

> It is recommended that you create a schedule for the garbage collection task if you have not already created one. See "Create GC task schedule" for an example command.

## Admin

### Admin container launch

Note: If you are not going to use the Admin service, do not launch this container.

Use the following command to launch the service:

> The following command is an example of starting the Admin service for the LUNA PLATFORM v.5.130.0 version. If you are migrating to a LUNA PLATFORM version other than v.5.130.0, replace the Admin image tag with the one corresponding to the target version for which you previously prepared the environment.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5010 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/admin:/srv/logs \
    --name=luna-admin \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-admin:v.5.21.0

# Additional information

This section provides the following additional information:

- Using ClickHouse as an Alternative to InfluxDB.
- Migrating InfluxDB to ClickHouse.
- Account creation.
- Creating a schedule for a garbage collection task.
- Manage descriptor encryption.
- Monitoring and logs visualization using Grafana.
- Useful commands for working with Docker.
- Description of the parameters for launching LUNA PLATFORM services and creating databases.
- Actions to enable saving LP service logs to files.
- Configuring Docker log rotation.
- Setting custom InfluxDB settings.
- Using Python Matcher service with Python Matcher Proxy service.

## Using ClickHouse as an Alternative to InfluxDB

For more information, see the "Monitoring" section of the administrator manual.

Note: You can use an external ClickHouse database if needed. In this case, you can skip the command below, but you will need to configure custom settings for each LUNA PLATFORM service.

Use the `docker run` command with the following parameters:

    docker run \
    -e CLICKHOUSE_USER=luna \
    -e CLICKHOUSE_PASSWORD=password \
    -v /var/lib/luna/clickhouse/data:/var/lib/clickhouse \
    -v /var/lib/luna/clickhouse/logs:/var/log/clickhouse-server \
    -v /var/lib/luna/current/extras/conf/clickhouse_config.xml:/etc/clickhouse-server/config.xml \
    --name=clickhouse \
    --network=host \
    --restart=always \
    --detach=true \
    --health-cmd="wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1" \
    dockerhub.visionlabs.ru/luna/clickhouse-server:v.25.4.0

> Note that ClickHouse logs are saved to files by default. The directory /var/lib/luna/clickhouse/logs is mounted for this purpose.

## Migrating InfluxDB to ClickHouse

To migrate from InfluxDB to ClickHouse on an already deployed LUNA PLATFORM and properly prepare the environment, follow the steps below.

> Important: The migration does not include transferring accumulated data from InfluxDB to ClickHouse.

1․ Start the ClickHouse container using the command above. 2․ Open the Storages configuration file:

    vi /var/lib/luna/current/extras/conf/storages_config.conf

and set the necessary settings for ClickHouse in the `LUNA_MONITORING` section. Example:

    STORAGE_TYPE = clickhouse
    SEND_DATA_FOR_MONITORING = 1
    HOST = 127.0.0.1
    PORT = 9000
    HTTP_PORT = 8123
    DB_USER = luna
    DB_PASSWORD = password
    DB_NAME = luna_monitoring
    USE_SSL = 0
    FLUSHING_PERIOD = 1

3․ Edit the "LUNA_MONITORING" section in the LUNA PLATFORM settings to tell the system which monitoring database to use for all services (except the Configurator service - see step 4).

You can load the configuration in one of the following ways:

- using a dump file before starting LUNA PLATFORM:

    vi /var/lib/luna/current/extras/conf/platform_settings.json

- Using the Configurator service interface after launching it. To do this, go to `http://<your_server_ip_adress>:5070/`, enter "LUNA_MONITORING" in the "Setting name" field, apply filters, and enter values ​​in the Value field:

    {
        "storage_type": "clickhouse",
        "send_data_for_monitoring": 1,
        "use_ssl": 0,
        "flushing_period": 1,
        "host": "127.0.0.1",
        "port": 9000,
        "http_port": 8123,
        "db_user": "luna",
        "db_password": "password",
        "db_name": "luna_monitoring"
    }

4․ Since the Configurator service settings are stored in its configuration file, to configure monitoring of this service, you need to edit the monitored file before starting the container:

    /var/lib/luna/current/example-docker/luna_configurator/configs/luna_configurator_postgres.conf

In the file, find the "LUNA_MONITORING" section and set the necessary connection parameters to ClickHouse.

5․ Run the command to prepare the entire environment (including monitoring) in the "Migrate environment command" section.

## Account creation

The account is created using an HTTP request to the "create account" resource of the API service.

> You can also create an account using the Admin service. This method requires an existing login and password (or the default login and password) and enables you to create an "admin" account. See the "Admin service" section of the administrator manual for details.

To create the account using a request to the API service, you need to provide the following mandatory data:

- "login" — Email address.
- "password" — Password.
- "account_type" — Account type ("user" or "advanced_user").

Create the account using your authentication details.

Example of CURL-request to the "create account" resource:

    curl --location --request POST 'http://127.0.0.1:5000/6/accounts' \
    --header 'Content-Type: application/json' \
    --data '{
      "login": "user@mail.com",
      "password": "password",
      "account_type": "user",
      "description": "description"
    }'

It is necessary to replace the authentication data from the example with your own.

> To work with tokens, you must have an account.

## GC task schedule creation

Before you start working with the LUNA PLATFORM, you can create a schedule for the Garbage collection task.

To do this, make a "create tasks schedule" request to the API service, specifying the necessary rules for the schedule.

An example of a schedule creation command for an account created in section "Account creation" is given below.

The example sets a schedule for the Garbage collection task for events older than 30 days with the removal of the samples and the source images. The task will be repeated once a day at 05:30 am.

    curl --location --request POST 'http://127.0.0.1:5000/6/tasks/schedules' \
    --header 'Authorization: Basic dXNlckBtYWlsLmNvbTpwYXNzd29yZA==' \
    --header 'Content-Type: application/json' \
    --data '{
        "task": {
            "task_type": 4,
            "content": {
                "target": "events",
                "filters": {
                    "create_time__lt": "now-30d"
                },
                "remove_samples": true,
                "remove_image_origins": true
            }
        },
        "trigger": {"cron": "30 5 * * *", "cron_timezone": "utc"},
        "behaviour": {"start_immediately": false, "create_stopped": false}
    }'

If necessary, you can create a schedule without automatically activating it. To do this, specify the parameter "create_stopped": "true". In this case, after creating the schedule, it must be activated manually using the "action" = "start" parameter of the "patch tasks schedule" request.

For more information, see the "Running scheduled tasks" section of the administrator manual.

## Manage descriptor encryption

Note: See the "Descriptor encryption" section in the administrator manual for detailed information.

To update existing descriptors in the Faces/Attributes/Events database, run the `descriptors_encryption.py` script. This script offers three operational options:

- Encrypting original descriptors.
- Switching to a new encryption key.
- Decrypting encrypted descriptors.

The script requires setting three environment variables regardless of the chosen option:

- `OLD_ENCRYPTION_KEY` (can be empty)
- `NEW_ENCRYPTION_KEY` (can be empty)
- `ENCRYPTION_ALGORITHM` (mandatory and cannot be empty)

Encrypting original descriptors

This option allows encrypting all descriptors in the database if they were not previously encrypted. Already encrypted descriptors will be ignored, allowing the script to be run multiple times. For this option, fill the `NEW_ENCRYPTION_KEY` variable and leave `OLD_ENCRYPTION_KEY` empty.

Switching to a new encryption key

This option assumes encryption has already been performed, and you have the current encryption key that needs refreshing. Already encrypted descriptors will be ignored, allowing the script to be run multiple times. Specify both `OLD_ENCRYPTION_KEY` and `NEW_ENCRYPTION_KEY`.

Decrypting encrypted descriptors

This option restores descriptors to their original state. The script processes only encrypted descriptors, leaving original ones unchanged. To execute this option of the script, specify `OLD_ENCRYPTION_KEY` and leave `NEW_ENCRYPTION_KEY` empty.

#### Launch descriptor migration script

Important: The script must be executed when the service is stopped, after migrating the database and before starting the service again.

To perform the migration, execute the `descriptors_encryption.py` script with the appropriate arguments. Below is the list of available arguments:

- `--config` — Path to the configuration file.
- `--luna-config` — Address and API version of the Configurator service for fetching settings (e.g., "http://127.0.0.1:5070/1").
- `--chunk-size` — Batch size for updates.
- `--LUNA_FACES_DB` — Tag to set `LUNA_FACES_DB` for fetching settings from Configurator (for Faces DB migration only).
- `--DATABASE_NUMBER` — Tag to set `DATABASE_NUMBER` for fetching settings from Configurator.
- `--LUNA_ATTRIBUTES_DB` — Tag to set `LUNA_ATTRIBUTES_DB` for fetching settings from Configurator (for Faces DB migration only).
- `--LUNA_EVENTS_DB` — Tag to set `LUNA_EVENTS_DB` for fetching settings from Configurator (for Events DB migration only).
- `-v, --verbose` — Enable debug mode.

Ensure to pass the corresponding environment variables when executing the container command (as mentioned above).

Important: Run the script after the DB migration and before starting the service.

Example command to execute the descriptors migration in the Faces DB:

    docker run \
    --env=OLD_ENCRYPTION_KEY=<your_old_encryption_key> \
    --env=NEW_ENCRYPTION_KEY=<your_new_encryption_key> \
    --env=ENCRYPTION_ALGORITHM=aes256-gcm \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/faces:/srv/logs \
    --rm \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-faces:v.4.16.26 \
    python3 ./base_scripts/descriptors_encryption.py --luna-config=http://127.0.0.1:5070/1

## Monitoring and logs visualization using Grafana

Monitoring visualization is performed by the LUNA Dashboards service, which contains the Grafana monitoring data visualization platform with configured LUNA PLATFORM dashboards.

> If necessary, you can install customized dashboards for Grafana separately. See the "LUNA Dashboards" section in the administrator manual for more information.

Together with Grafana, you can use the Grafana Loki log aggregation system, which enables you to flexibly work with LUNA PLATFORM logs. The Promtail agent is used to deliver LUNA PLATFORM logs to Grafana Loki (for more information, see the "Grafana Loki" section in the administrator manual).

### LUNA Dashboards

Note: To work with Grafana you need to use InfluxDB version 2.

Note: Before updating, make sure that the old LUNA Dashboards container is deleted.

#### Run LUNA Dashboards container

Use the `docker run` command with these parameters to run Grafana:

    docker run \
    --restart=always \
    --detach=true \
    --network=host \
    --name=grafana \
    -v /etc/localtime:/etc/localtime:ro \
    dockerhub.visionlabs.ru/luna/luna-dashboards:v.0.1.7

Use "http://IP_ADDRESS:3000" to go to the Grafana web interface when the LUNA Dashboards and InfluxDB containers are running.

### Grafana Loki

Note: Grafana Loki requires LUNA Dashboards to be running.

Note: Before updating, make sure that the old Grafana Loki and Promtail containers are removed.

#### Run Grafana Loki container

Use the `docker run` command with these parameters to run Grafana Loki:

    docker run \
    --name=loki \
    --restart=always \
    --detach=true \
    --network=host \
    -v /etc/localtime:/etc/localtime:ro \
    dockerhub.visionlabs.ru/luna/loki:2.7.1

#### Run Promtail container

Use the `docker run` command with these parameters to run Promtail:

    docker run \
    -v /var/lib/luna/current/example-docker/logging/promtail.yml:/etc/promtail/luna.yml \
    -v /var/lib/docker/containers:/var/lib/docker/containers \
    -v /etc/localtime:/etc/localtime:ro \
    --name=promtail \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/promtail:2.7.1 \
    -config.file=/etc/promtail/luna.yml -client.url=http://127.0.0.1:3100/loki/api/v1/push -client.external-labels=job=containerlogs,pipeline_id=,job_id=,version=

Here:

- `-v /var/lib/luna/current/example-docker/logging/promtail.yml:/etc/promtail/luna.yml` — Mounting the configuration file to the Promtail container.

- `-config.file=/etc/promtail/luna.yml` — Flag with the address of the configuration file.

- `-client.url=http://127.0.0.1:3100/loki/api/v1/push` — Flag with the address of deployed Grafana Loki.

- `-client.external-labels=job=containerlogs,pipeline_id=,job_id=,version=` — Static labels to add to all logs sent to Grafana Loki.

## Docker commands

### Show containers

To show the list of launched Docker containers use the command:

    docker ps

To show all the existing Docker containers use the command:

    docker ps -a

### Copy files to container

You can transfer files into the container. Use the `docker cp` command to copy a file into the container.

    docker cp <file_location> <container_name>:<folder_inside_container>

### Enter container

You can enter individual containers using the following command:

    docker exec -it <container_name> bash

To exit the container, use the command:

    exit

### Images names

You can see all the names of the images using the command:

    docker images

### Delete image

If you need to delete an image:

- Run the `docker images` command.
- Find the required image, for example dockerhub.visionlabs.ru/luna/luna-image-store.
- Copy the corresponding image ID from the IMAGE ID, for example, "61860d036d8c".
- Specify it in the deletion command:

    docker rmi -f 61860d036d8c

Delete all the existing images.

    docker rmi -f $(docker images -q)

### Stop container

You can stop the container using the command:

    docker stop <container_name>

Stop all the containers:

    docker stop $(docker ps -a -q)

### Delete container

If you need to delete a container:

- Run the "docker ps" command.
- Stop the container (see Stop container).
- Find the required image, for example dockerhub.visionlabs.ru/luna/luna-image-store.
- Copy the corresponding container ID from the CONTAINER ID column, for example, "23f555be8f3a".
- Specify it in the deletion command:

    docker container rm -f 23f555be8f3a

Delete all the containers.

    docker container rm -f $(docker container ls -aq)

#### Check service logs

You can use the following command to show logs for the service:

    docker logs <container_name>

## Launching parameters description

When launching a Docker container for a LUNA PLATFORM service you should specify additional parameters required for the service launching.

> The parameters specific for a particular container are described in the section about this container launching.

All the parameters given in the service launching example are required for proper service launching and utilization.

### Launching services parameters

Example command of launching LP services containers:

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=<Port_of_the_launched_service> \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/<service>:/srv/logs/ \
    --name=<service_container_name> \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/<service-name>:<version>

The following parameters are used when launching LP services containers:

- `docker run` — Command for running the selected image as a new container.

- `dockerhub.visionlabs.ru/luna/<service-name>:<version>` — Sets the image required for the container launching.

> Links to download the container images you need are available in the description of the corresponding container launching.

- `--network=host` — Sets that a network is not simulated and the server network is used. If you need to change the port for third-party party containers, you should change this string to `-p 5440:5432`. Where the first port `5440` is the local port and `5432` is the port used inside the container. The example is given for PostgreSQL.

- `--env=` — Sets the environment variables required to run the container (see the "Service arguments" section).

- `--name=<service_container_name>` — Sets the name of the launched container. The name must be unique. If there is a container with the same name, an error will occur.

- `--restart=always` — Sets a restart policy. The daemon will always restart the container regardless of the exit status.

- `--detach=true` — Run the container in the background mode.

- `-v` — Enables you to mount the content of a server folder into a volume in the container. Thus their contents will synchronize. The following general data is mounted:

- `/etc/localtime:/etc/localtime:ro` — Sets the current time zone used by the system in the container.

- `/tmp/logs/<service>:/srv/logs/` — Enables copying of the folder with service logs to your server `/tmp/logs/<service>` directory. You can change the directory where the logs will be saved according to your needs.

#### Service arguments

Each service in LUNA PLATFORM has its own launch arguments. These arguments can be passed through:

- Setting a flag for the launch script (`run.py`) of the corresponding service.
- Setting environment variables (`--env`) on the Docker command line.

For example, using the `--help` flag you can get a list of all available arguments. An example of passing an argument to an API service:

    docker run --rm dockerhub.visionlabs.ru/luna/luna-api:v.6.70.0 python3 /srv/luna_api/run.py --help

List of main arguments:

Launch flag | Environment variable | Description
`--port` | `PORT` | Port on which the service will listen for connections.
`--workers` | `WORKER_COUNT` | Number of workers for the service.
`--log_suffix` `--log_suffix` | `LOG_SUFFIX` `LOG_SUFFIX` | Suffix added to log file names (with the option to write logs to a file enabled).
`--config-reload` | `RELOAD_CONFIG` | Enable automatic configuration reload. See "Automatic configurations reload" in the LUNA PLATFORM 5 administrator manual.
`--pulling-time` | `RELOAD_CONFIG_INTERVAL` | Configuration checking period (default 10 seconds). See "Automatic configurations reload" in the LUNA PLATFORM 5 administrator manual.
`--luna-config` `--luna-config` | `CONFIGURATOR_HOST`, `CONFIGURATOR_PORT` | Address of the Configurator service for downloading settings. For `--luna-config` it is sent in the format `http://localhost:5070/1`. For environment variables, the host and port are set explicitly. If the argument is not given, the default configuration file will be used.
`--config` | None | Path to the file with service configurations.
`--<config_name>` | `--EXTEND_CMD=<config_name>` | Tag of the specified configuration in the Configurator. When setting this configuration, the value of the tagged configuration will be used. Example: `--LUNA_MONITORING TAG_1` | Note: You must pre-tag the appropriate configuration in. Configurator. Note: Only works with the `--luna-config` flag.
`--tls_cert` | None | Path to the SSL certificate for launching the service using the HTTPS protocol.
`--tls_key` | None | Path to the SSL private key for launching the service using the HTTPS protocol.
`--tls_key_pass` | None | Password for the SSL private key for launching the service using the HTTPS protocol.

> The list of arguments may vary depending on the service.

It is also possible to override the settings of services at their start using environment variables.

The `VL_SETTINGS` prefix is used to redefine the settings. Examples:

- `--env=VL_SETTINGS.LUNA_MONITORING.SEND_DATA_FOR_MONITORING=0`. Using the environment variable from this example will set the "SEND_DATA_FOR_MONITORING" setting for the `LUNA_MONITORING` section to "0".
- `--env=VL_SETTINGS.OTHER.STORAGE_TIME=LOCAL`. For non-compound settings (settings that are located in the "OTHER" section in the configuration file), you must specify the "OTHER" prefix. Using the environment variable from this example will set the value of the "STORAGE_TIME" setting (if the service uses this setting) to "LOCAL".

Passing flags using environment variable

Flags for which an environment variable is not explicitly allocated can be passed using the environment variable `EXTEND_CMD`.

For example, you can pass the configurations tag in the following way:

    --env=EXTEND_CMD="--LUNA_MONITORING=TAG_1 --LUNA_EVENTS_DB=TAG_2"

## Logging to server

To enable saving logs to the server, you should:

- Create directories for logs on the server.
- Activate log recording and set the location of log storage inside LP service containers.
- Configure synchronization of log directories in the container with logs on the server using the `volume` argument at the start of each container.

### Create logs directory

Below are examples of commands for creating directories for saving logs and assigning rights to them for all LUNA PLATFORM services.

    mkdir -p /tmp/logs/configurator /tmp/logs/image-store /tmp/logs/accounts /tmp/logs/faces /tmp/logs/licenses /tmp/logs/events /tmp/logs/python-matcher /tmp/logs/handlers /tmp/logs/remote-sdk /tmp/logs/tasks /tmp/logs/tasks-worker /tmp/logs/sender /tmp/logs/api /tmp/logs/admin /tmp/logs/luna-video-agent /tmp/logs/luna-video-manager /tmp/logs/luna-streams-retranslator

    chown -R 1001:0 /tmp/logs/configurator /tmp/logs/image-store /tmp/logs/accounts /tmp/logs/faces /tmp/logs/licenses /tmp/logs/events /tmp/logs/python-matcher /tmp/logs/handlers /tmp/logs/remote-sdk /tmp/logs/tasks /tmp/logs/tasks-worker /tmp/logs/sender /tmp/logs/api /tmp/logs/admin /tmp/logs/luna-video-agent /tmp/logs/luna-video-manager /tmp/logs/luna-streams-retranslator

If you need to use the Python Matcher Proxy service, then you need to additionally create the `/tmp/logs/python-matcher-proxy` directory and set its permissions.

### Logging activation

#### LP services logging activation

To enable logging to file, you need to set the `log_to_file` and `folder_with_logs` settings in the `<SERVICE_NAME>_LOGGER` section of the settings for each service.

Automatic method (before/after starting Configurator)

To update logging settings, you can use the `logging.json` settings file provided with the distribution package.

Run the following command after starting the Configurator service:

    docker cp /var/lib/luna/current/extras/conf/logging.json luna-configurator:/srv/luna_configurator/used_dumps/logging.json

Update the logging settings with the copied file using the Storages `load_dump` command with the `--dump-file` argument: `--dump-file=/srv/logging.json`, where "logging.json" is the name of the dump file. See the "Load_dump command" section of the Storages utility manual for details.

Manual method (after starting Configurator)

Go to the Configurator service interface (`127.0.0.1:5070`) and set the logs path in the container in the `folder_with_logs` parameter for all services whose logs need to be saved. For example, you can use the path `/srv/logs`.

Set the `log_to_file` option to `true` to enable logging to a file.

#### Configurator service logging activation (before/after Configurator start)

The Configurator service settings are not located in the Configurator user interface, they are located in the following file:

    /var/lib/luna/current/example-docker/luna_configurator/configs/luna_configurator_postgres.conf

You should change the logging parameters in this file before starting the Configurator service or restart it after making changes.

Set the path to the logs location in the container in the `FOLDER_WITH_LOGS = ./` parameter of the file. For example, `FOLDER_WITH_LOGS = /srv/logs`.

Set the `log_to_file` option to `true` to enable logging to a file.

### Mounting directories with logs when starting services

The log directory is mounted with the following argument when starting the container:

    -v <server_logs_folder>:<container_logs_folder> \

where `<server_logs_folder>` is the directory created in the create logs directory step, and `<container_logs_folder>` is the directory created in the activate logging step.

Example of command to launch the API service with mounting a directory with logs:

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5000 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    --name=luna-api \
    --restart=always \
    --detach=true \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/api:/srv/logs \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-api:v.6.70.0

The example container launch commands in this documentation contain these arguments.

## Docker log rotation

To limit the size of logs generated by Docker, you can set up automatic log rotation. To do this, add the following data to the `/etc/docker/daemon.json` file:

    {
        "log-driver": "json-file",
        "log-opts": {
            "max-size": "100m",
            "max-file": "5"
        }
    }

This will allow Docker to store up to 5 log files per container, with each file being limited to 100MB.

After changing the file, you need to restart Docker:

    systemctl reload docker

The above changes are the default for any newly created container, they do not apply to already created containers.

## Set custom InfluxDB settings

If you are going to use InfluxDB OSS 2, then you need to update the monitoring settings in Configurator service.

There are the following settings for InfluxDB OSS 2:

    "send_data_for_monitoring": 1,
    "use_ssl": 0,
    "flushing_period": 1,
    "host": "127.0.0.1",
    "port": 8086,
    "organization": "<ORGANIZATION_NAME>",
    "token": "<TOKEN>",
    "bucket": "<BUCKET_NAME>",
    "version": <DB_VERSION>

You can update InfluxDB settings in the Configurator service by following these steps:

- Open the following file:

    vi /var/lib/luna/current/extras/conf/influx2.json

- Set required data.
- Save changes.
- Copy the file to the influxDB container:

    docker cp /var/lib/luna/current/extras/conf/influx2.json luna-configurator:/srv/

- Update the settings in the Configurator service using the Storages command to load a dump (`load_dump`) with the `--dump-file` argument: `--dump-file=/srv/influx2.json`, where "influx2.json" is the name of the dump file. See the "Load_dump command" section of the Storages utility manual for details.

> You can also manually update settings in the Configurator service user interface.

The Configurator service configurations are set separately.

- Open the file with the Configurator configurations:

    vi /var/lib/luna/current/example-docker/luna_configurator/configs/luna_configurator_postgres.conf

- Set required data.
- Save changes.
- Restart Configurator:

    docker restart luna-configurator

## Use Python Matcher with Python Matcher Proxy

As mentioned earlier, along with the Python Matcher service, you can additionally use the Python Matcher Proxy service, which will redirect matching requests either to the Python Matcher service or to the matching plugins. Plugins may significantly improve matching processing performance. For example, it is possible to organize the storage of the data required for matching operations and additional objects fields in separate storage using plugins, which will speed up access to the data compared to the use of the standard LUNA PLATFORM database.

To use the Python Matcher service with Python Matcher Proxy, you should additionally launch the appropriate container, and then set a certain setting in the Configurator service. Follow the steps below only if you are going to use matching plugins.

> See the description and usage of matching plugins in the administrator manual.

### Python Matcher proxy container launch

Use the following command to launch the service:

> After starting the container, you need to set the `"luna_matcher_proxy":true` parameter in the "ADDITIONAL_SERVICES_USAGE" section in the Configurator service.

    docker run \
    --env=CONFIGURATOR_HOST=127.0.0.1 \
    --env=CONFIGURATOR_PORT=5070 \
    --env=PORT=5110 \
    --env=WORKER_COUNT=1 \
    --env=RELOAD_CONFIG=1 \
    --env=RELOAD_CONFIG_INTERVAL=10 \
    --env=SERVICE_TYPE="proxy" \
    -v /etc/localtime:/etc/localtime:ro \
    -v /tmp/logs/python-matcher-proxy:/srv/logs \
    --name=luna-python-matcher-proxy \
    --restart=always \
    --detach=true \
    --network=host \
    dockerhub.visionlabs.ru/luna/luna-python-matcher:v.1.20.10

After launching the container, you need to set the following value in the Configurator service.

    ADDITIONAL_SERVICES_USAGE = "luna_matcher_proxy":true