Integration

Luna-Vinder is a separate family of services, so it needs to be integrated into an already deployed Luna platform. Luna-Vinder services depend on the following Luna platform components:

• Luna Configurator - for storing and managing service configurations

• Luna Events - as the primary data source for projections

• Luna Faces - for face-related data and operations

Prerequisites

Before integrating Luna-Vinder, ensure that the following components are properly deployed and running:

1. Luna Configurator with accessible database

2. Luna Events service with populated event data

   Important: Luna Events must be started with the option EVENT_DELETION_LOG=1 to enable logging of deleted events. This is required for Matcher to synchronize deleted data.

3. Network connectivity between Luna-Vinder services and Luna platform components

4. Luna-Vinder database initialization — you must run the database creation script from inside the Luna-Vinder Projector Docker container before starting Vinder services. Execute the following command to create the database:

   docker run --rm --network host ${DOCKER_REGISTRY}/luna-vinder-projector:${LUNA_VINDER_TAG} \
     bash -c "python3 -m base_scripts.db_create && python3 -m luna_vinder_projector.run --port=${PORT_LUNA_VINDER_PROJECTOR} --luna-config=http://${HOST}:${PORT_CONFIGURATOR}/1 --config-reload 1"
   

   Without this step, Vinder services will not function properly.

Integration with Configurator

To integrate Luna-Vinder into the Luna platform, you must first load its settings into Luna Configurator using the configuration migration mechanism. This step is essential as it registers all necessary schemas, default settings, and service configurations that Luna-Vinder components will use during runtime.

A special entrypoint is provided in the Docker container for migration purposes.

Basic Migration

To migrate configurations to the latest version, execute the following command:

docker run --rm --network host ${DOCKER_REGISTRY}/luna-vinder-configs:${LUNA_VINDER_TAG}

This command uses default connection parameters and migrates the configuration to the latest available version.

Advanced Migration

For more control over the migration process, use the advanced command with additional parameters:

docker run --rm --entrypoint='' --network host \
    ${DOCKER_REGISTRY}/luna-vinder-configs:${LUNA_VINDER_TAG} \
    python -m configs.migrate head \
    --config_db_url postgres://luna:luna@127.0.0.1:5432/luna_configurator

Parameters explanation:

• --entrypoint='' - overrides the default entrypoint to use custom parameters

• --network host - uses host network for database connectivity

• head - migrates to the latest version

• --config_db_url - PostgreSQL connection string for Luna Configurator database

Migration Downgrade

If you need to downgrade to a previous configuration version, specify the target revision. The revision can be absolute or relative:

# Downgrade by one version
docker run --rm --entrypoint='' --network host \
    ${DOCKER_REGISTRY}/luna-vinder-configs:${LUNA_VINDER_TAG} \
    python -m configs.migrate -1

# Downgrade to specific revision
docker run --rm --entrypoint='' --network host \
    ${DOCKER_REGISTRY}/luna-vinder-configs:${LUNA_VINDER_TAG} \
    python -m configs.migrate <revision_id> \
    --config_db_url postgres://luna:luna@127.0.0.1:5432/luna_configurator

Warning

Downgrading configurations may result in loss of settings specific to newer versions. Always backup your configuration database before performing downgrades.

Verification

After migration, you can verify that configurations were loaded successfully by checking the Luna Configurator database or API. The Luna-Vinder service configurations should be visible and accessible through the Configurator interface.

Note

Configuration migration is idempotent - running it multiple times with the same target version will not cause issues.

Monitoring integration

To integrate Vinder services in Luna Platform monitoring, you need to run monitoring database migration.

To migrate monitoring to the latest revision just run following command:

docker run --rm --network host ${DOCKER_REGISTRY}/luna-vinder-configs:${LUNA_VINDER_TAG}

Or use a more advanced command with additional parameters:

docker run --rm --entrypoint='' --network host ${DOCKER_REGISTRY}/luna-vinder-configs:${LUNA_VINDER_TAG} python -m monitoring.migrate -x luna-config=http://127.0.0.1:5070/1 upgrade head

docker run --rm --entrypoint='' --network host ${DOCKER_REGISTRY}/luna-vinder-configs:${LUNA_VINDER_TAG} python -m monitoring.migrate -x config=./my-custom-config.conf upgrade head

For downgrade, specify the target revision that can also be relative:

docker run --rm --entrypoint='' --network host ${DOCKER_REGISTRY}/luna-vinder-configs:${LUNA_VINDER_TAG} python -m monitoring.migrate downgrade -1

Starting Luna-Vinder Services

After successfully migrating configurations to Luna Configurator, you can start Luna-Vinder services. The services will automatically retrieve their configurations from Luna Configurator on startup.

The services include:

• Projector - manages projections and data synchronization

• Matcher - performs descriptor matching and search operations

Deployment Options

Luna-Vinder can be deployed in two ways:

1. Docker-based deployment (recommended) - using Docker Compose or Kubernetes

2. Manual deployment - running services directly on the host system

Detailed instructions for each deployment method:

• Run in docker
• Run with no docker

Python Matcher Proxy Integration

Once Luna-Vinder is running, you can integrate vector search capabilities into Luna Python Matcher Proxy through the plugin system. This integration allows seamless routing of matching requests to Luna-Vinder while maintaining compatibility with existing Luna API clients.

The matching plugin acts as an intelligent dispatcher that:

• Analyzes incoming matching requests

• Determines if the request can be handled by Luna-Vinder based on available projections and indexes

• Routes compatible requests to appropriate Matcher instances

• Falls back to standard Luna matching if Luna-Vinder cannot handle the request

• Enriches match results with additional metadata if needed

For detailed configuration instructions and examples, see the matching plugin documentation.

Tip

For optimal performance, design your projections and indexes to match your most common query patterns. This ensures maximum request compatibility with Luna-Vinder.

Benefits of Integration

Integrating Luna-Vinder with Python Matcher Proxy provides several advantages:

• Transparent performance boost - existing API clients automatically benefit from faster searches

• Backward compatibility - requests that can’t be handled by Luna-Vinder fall back to standard matching

• Gradual migration - you can migrate search workloads incrementally by creating projections for specific use cases

• Centralized endpoint - clients continue using a single API endpoint

• Load distribution - offloads intensive search operations from the main database