Search | On-Premise | Urbi Documentation

On-Premise Search services

Search services allow searching and retrieving information on various objects such as organizations, buildings, public places, etc.

This article describes how to deploy and configure the Search services in your environment. To learn how to use the RESTful API provided by the Search services, see the documentation for the individual APIs (found in the top menu under "Search").

On-premise Search services architecture

Search services architecture consists of two services: Catalog API and Search API.

Catalog API provides a RESTful API for applications.

Search API is a search engine that processes requests made by Catalog API.

Detailed requirements for each service are listed in the Overview document. Additional information can be found in the Deployment considerations section of this document.

Shared infrastructure:

  • S3-compatible storage for storing the search indexes (Deployment Artifacts Storage)

Services:

  • Search API service

Shared infrastructure:

  • PostgreSQL data storage for storing object data. These extensions should be installed: PostGIS 2.5, JsQuery.

Note:

The Ingress configuration in configuration files is sample and for reference only. Adapt this configuration to your needs and Ingress installation.

Do the following:

  1. Do the common deployment steps.

    Note:

    Do not forget to write down the path to a manifest file, it will be required to deploy the services.

  2. Deploy the Search API service.

  3. Deploy the Catalog API service.

  1. Create the values-search.yaml configuration file:

    values-search.yaml

    dgctlDockerRegistry: <Docker Registry hostname and port>/2gis-on-premise
    
    dgctlStorage:
        host: <Deployment Artifacts Storage endpoint>
        bucket: <Deployment Artifacts Storage bucket>
        accessKey: <The bucket access key>
        secretKey: <The bucket secret key>
        manifest: <Path to the manifest file>
    
    api:
        resources:
            limits:
                cpu: 1
                memory: 3G
            requests:
                cpu: 100m
                memory: 1G
    nginx:
        resources:
            limits:
                cpu: 1
                memory: 1G
            requests:
                cpu: 100m
                memory: 200Mi
    
    ingress:
        hosts:
            - host: search-api.host
    

    Where:

    1. dgctlDockerRegistry: your Docker Registry endpoint where On-Premise services' images reside.

    2. dgctlStorage: Deployment Artifacts Storage settings.

      1. Fill in the common settings to access the storage: endpoint, bucket, and access credentials.
      2. manifest: fill in the path to the manifest file in the manifests/1640661259.json format. This file contains the description of pieces of data that the service requires to operate.
    3. api.resources: computational resources settings for the API backend service. See the minimal requirements table for the actual information about recommended values.

    4. nginx.resources: computational resources settings for the NGINX backend service. See the minimal requirements table for the actual information about recommended values.

    5. ingress: configuration of the Ingress resource. Adapt it to your Ingress installation. This URL should be accessible from the outside of your Kubernetes cluster, so that users in the private network can browse the URL.

  2. Deploy the service with Helm using the created values-search.yaml configuration file.

    helm upgrade --install --version=1.0.3 --atomic --values ./values-search.yaml search-api 2gis-on-premise/search-api
    
  1. Configure the PostgreSQL data storage:

    1. Log in to the PostgreSQL as a superuser.

    2. Create the catalog user for this database:

      create user catalog password '<password for the user>';
      
    3. Create the catalog database for use with Catalog API service:

      create database catalog owner catalog;
      
      \c catalog
      
      CREATE EXTENSION postgis WITH SCHEMA public;
      CREATE EXTENSION jsquery WITH SCHEMA public;
      
  2. Create the values-catalog.yaml configuration file:

    values-catalog.yaml

    dgctlDockerRegistry: <Docker Registry hostname and port>/2gis-on-premise
    
    db:
        host: localhost
        port: 5432
        name: catalog
        username: catalog
        password: secret
    
    search:
        url: http://localhost:80
    
    keys:
        endpoint: https://keys-api.host
        serviceKeys:
            places: ''
            geocoder: ''
            suggest: ''
            categories: ''
            regions: ''
    

    Where:

    1. dgctlDockerRegistry: your Docker Registry endpoint where On-Premise services' images reside.

    2. db: the PostgreSQL database access settings. Use the values you configured in the PostgreSQL on the previous step.

      1. host: host name of the server
      2. port: port of the server
      3. name: database name
      4. username: user name
      5. password: user password
    3. search: the Search API service access settings.

      1. url: URL of the service. This URL should be accessible from all the pods within your Kubernetes cluster.
    4. keys: the API Keys service settings.

      1. endpoint: URL of the service. This URL should be accessible from all the pods within your Kubernetes cluster.
      2. serviceKeys: service API keys for sharing usage statistics with the API Keys service (see Fetching the service API keys).
  3. Deploy the service with Helm using the created values-catalog.yaml configuration file.

    helm upgrade --install --version=1.0.3 --atomic --values ./values-catalog.yaml catalog-api 2gis-on-premise/catalog-api
    

To update the Search API service, execute the following command:

helm upgrade --version=1.0.3 --atomic --values ./values-search.yaml search-api 2gis-on-premise/search-api

To update the Catalog API service, execute the following command:

helm upgrade --version=1.0.3 --atomic --values ./values-catalog.yaml catalog-api 2gis-on-premise/catalog-api

To test that the Search API service is working, you can make a GET request to the status endpoint:

curl SEARCH_API_HOST/v2/status?f=common

To test that the Catalog API service is working, you can do the following:

  1. Using API Keys Admin, create an API key that has access to Places API and Regions API.

  2. Make the following GET request, replacing:

    1. API_KEY with the created key.
    2. City with any city name you want to search the information for.
    curl CATALOG_API_HOST/3.0/items/geocode?key=API_KEY&q=City
    

    This request will test the operability of Catalog API, Search API, and the PostgreSQL database.