Skip to content

# Introduction

This document describes the installation and usage of Docker Compose for LUNA Index Module (LIM) deployment.

LIM is an substantive module, so it should be integrated into LUNA PLATFORM 5 of a similar version already deployed. It is necessary to update the LP if the versions differ.

Docker Compose is used for automated containers deployment. The Docker Compose scenario from this distribution is used for deploying the LIM services on a single server.

It is considered that installation is performed on the server with Almalinux 9 OS, where LIM was not installed.

Firewall and SELinux should be manually configured on the server by the administrator. Their configuration is not described in this document.

No data backup is implemented for LIM data in this installation.

LIM is deployed using the minimum power operating for demonstration purposes and cannot be used for the production system.

For a successful launch, you need to perform the actions from the sections "Before launch" and "Services launch". The section "Additional information" provides useful information on the description of Docker commands, further steps for performing descriptor matching, etc.

See the "docker-compose.yml" file and other files in the "example-docker" directory for the information about launched services and performed actions.

Additional notes about Docker Compose script. The script:

- Is tested using the default services configurations.

- Is not intended to be used for LIM scaling:

  - It is not used for the deployment of LIM services on several servers.

  - It is not used for deployment and balancing of several LIM services on a single service.

- Does not provide the possibility to use external databases already installed on the server.

You can write your scenario that deploys and configures all the required services. This document does not include information about scenario creation or tutorial for Docker usage. Please refer to the Docker documentation to find more information about Docker and Docker Compose:

https://docs.docker.com

> All the provided commands should be executed using the Bash shell (when you launch commands directly on the server) or Putty (when you remotely connect to the server). The provided commands were tested with these utilities only. The use of other shells or emulators can lead to errors when executing commands.

# Before launch

Make sure that you are the root user before launch!

Before launching the LUNA Index Module, you must perform the following actions:

- Unpack the LIM distribution.
- Create symbolic link.
- Create directory to store indexes.
- Configure SELinux and Firewall.
- Choose logging method.
- Install Docker and Docker Compose.
- Login to VisionLabs registry.

## Distribution unpacking

The distribution package is an archive lim_v.5.139.0, where v.5.139.0 is a numerical identifier, describing the current LUNA Index Module 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 `/var/lib/luna/` directory.

    mv /root/lim_v.5.139.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 lim_v.5.139.0.zip

## Symbolic link creation

Create a symbolic link. The link indicates that the current version of the distribution file is used to run LIM.

    ln -s lim_v.5.139.0 lim-current

## Create directory to store indexes

To store indexes and interact with them on the server, you need to create an appropriate directory. This directory will be mounted when the LIM services are launched.

Create folder to store indexes.

    mkdir -p /var/lib/luna/lim_storage

Set appropriate permissions to read/write this folder.

    chown -R 1001:0 /var/lib/luna/lim_storage

## SELinux and Firewall

You must configure SELinux and Firewall so that they do not block LUNA PLATFORM services.

> SELinux and Firewall configurations are not described in this guide.

If SELinux and Firewall are not configured, the installation cannot be performed.

## Choose logging method

There are two methods to output logs in LUNA PLATFORM:

- Standard log output (stdout).
- Log output to a file.

Log output settings are set in the settings of each service in the `<SERVICE_NAME>_LOGGER` section.

If necessary, you can use both methods of displaying logs.

> For more information about the LUNA PLATFORM logging system, see the "Logging" section in the administrator manual.

### Logging to stdout

This method is used by default and requires no further action.

### Logging to file

Note: When you enable saving logs to a file, you should remember that logs occupy a certain place in the storage, and the process of logging to a file negatively affects system performance.

To use this method, you need to perform the following additional actions:

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

> Synchronization of log directories is already configured in the Docker Compose script, you only need to create directories and activate logging.

See the instructions for enabling logging to files in the "Logging to server" section.

## Docker and Docker Compose installation

The Docker installation is described in the official documentation.

Note: Docker version 25.0.3 was used when testing this instruction. It is not guaranteed to work with higher versions of Docker.

Quick installation commands are listed below.

> Check the official documentation for updates if you have any problems with the installation.

Add Docker repository:

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

Install Docker and Docker Compose plugin:

    dnf -y install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Launch Docker:

    systemctl start docker

    systemctl enable docker

Check Docker status:

    systemctl status docker

## Login to registry

When launching containers, you should specify a link to the image required for the container launching. This image will be downloaded from the VisionLabs registry. Before that, you should login to the registry.

> Login and password can be requested from the VisionLabs representative.

Enter login .

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

After running the command, you will be prompted for a password. Enter password.

> In the `docker login` command, you can enter the login and password at the same time, but this does not guarantee security because the password can be seen in the command history.

# Services launch

Go to the Docker Compose folder.

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

> Make sure that all required LP containers are launched (see LIM system requirements).

Launch Docker Compose:

> You must be logged in the VisionLabs registry (see section "Login to registry")

    ./start_lim.sh

> The script loads the LIM settings into the Configurator container with the standard name `luna-configurator`. If the name of the Configurator container for some reason has a different name, then it must be changed in the `LUNA_CONFIGURATOR_NAME` variable in the .env file.

Deploying containers takes some time. You have to wait until all the services are running before working with LUNA Index Module.

Check the state of launched Docker containers.

    docker ps

# Additional information

This section provides the following additional information:

- Steps to perform descriptors matching.
- Useful commands for working with Docker.
- Actions to enable saving LIM service logs to files.

## Steps to perform descriptors matching

To start the descriptors matching procedure using LIM services, you should perform the following steps:

- select the preferred mode that will be used for the descriptors matching — one-time or automatic.
- One-time mode: Specify the required "list_id" in the request body to the "create task" resource of the Index Manager service and perform the request.
- Automatic mode for working with specific lists: Specify the required "list_id" in the "indexing_lists" setting of the "LIM_MANAGER_INDEXING" of the Configurator service.
- Automatic mode for working with all existing lists:
  - Specify the "dynamic" value in the "indexing_lists" setting of the "LIM_MANAGER_INDEXING" of the Configurator service.
  - Specify the minimum number of faces in the list in the "min_indexing_list_size" setting of the "LIM_MANAGER_INDEXING" of the Configurator service to index all existing descriptors in the lists.
- Send a request for matching descriptors from the API service.

> For details on LIM service interaction, see the "Service interaction" section of the LIM administrator manual.

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

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

> Docker Compose script is already configured to synchronize directories with the folders created in the section below.

### Create logs directory

You need to create the following directories for storing logs and assign them the appropriate rights.

    mkdir -p /tmp/logs/lim-manager /tmp/logs/lim-indexer /tmp/logs/lim-matcher /tmp/logs/python-matcher-proxy

    chown -R 1001:0 /tmp/logs/lim-manager /tmp/logs/lim-indexer /tmp/logs/lim-matcher /tmp/logs/python-matcher-proxy

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

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

Update your logging settings using Storages utility:

    docker run \
    --rm \
    --network=host \
    -v /var/lib/luna/lim-current/example-docker/configs/logging.json:/srv/logging.json \
    dockerhub.visionlabs.ru/luna/storages:v.0.145.0 \
    bash -c "luna_prepare load_dump \
        --dump-file=/srv/logging.json"

Manual method

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