Search API | On‑Premise | 2GIS Documentation
Maps
Search
Navigation
Urbi Pro
CityLens
Account
On‑Premise

Installing search API

Important note:

All passwords and keys in this section are given for illustration purposes.

During a real installation, it is recommended to use more complex and reliable passwords.

1. Before installing

  1. Consider getting familiar with:

  2. Make sure the necessary preparation steps are completed:

    1. Preparation for installation
    2. Fetching installation artifacts
    3. Installing License service
    4. Installing API Keys service

  3. Collect the necessary information that was set or retrieved on previous steps:

    Object Example value How to get value
    Docker Registry mirror endpoint docker.storage.example.local:5000 See Fetching installation artifacts
    Kubernetes secret for accessing Docker Registry onpremise-registry-creds See Fetching installation artifacts
    Installation artifacts S3 storage domain name artifacts.example.com See Fetching installation artifacts
    Bucket name for installation artifacts onpremise-artifacts See Fetching installation artifacts
    Installation artifacts access key AKIAIOSFODNN7EXAMPLE See Fetching installation artifacts
    Installation artifacts secret key wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY See Fetching installation artifacts
    Path to the manifest file manifests/1640661259.json See Fetching installation artifacts
    License service endpoint http://license See Installing License service
    API Keys service endpoint http://keys-api See Installing API Keys service
    Service token CATALOG_APIS_TOKEN See Installing API Keys service

  4. Make sure that the resource requirements specified in the Helm charts are met:

    For more information on how to do this, refer to the System requirements document.

    Note

    Contents of Helm charts described in this chapter are relevant for the latest On-Premise version (see Release notes). To find parameters for earlier versions, open the required values.yaml on GitHub and enter the required version number (for example, 1.18.0) in the tag switcher on the left.

  5. Choose domain names for the services.

    Example:

    • Domain name for Search API: search-api.example.com
    • Domain name for Catalog APIs: catalog-api.example.com

2. Prepare infrastructure required for the service

Configure PostgreSQL

Place a PostgreSQL cluster with the domain name catalog-postgresql.storage.example.local in the private network. This instruction assumes that the cluster works on the standard port 5432.

Configure the PostgreSQL cluster for usage as a storage:

  1. Connect to the cluster a superuser (usually postgres).

  2. Create a database user that will be used for the service. Set a password for the user.

    create user dbuser_catalog password '650D7AmZjSR1dkNa';

  3. Create a database owned by this user.

    create database onpremise_catalog owner dbuser_catalog;

  4. Install necessary database extensions:

    \c onpremise_catalog

create schema extensions;
grant usage on schema extensions to public;
grant execute on all functions in schema extensions to public;
alter default privileges in schema extensions grant execute on functions to public;
alter default privileges in schema extensions grant usage on types to public;
create extension if not exists plpgsql with schema pg_catalog;
create extension if not exists jsquery with schema extensions;
create extension if not exists postgis with schema extensions;

3. Install search API services

Install Search API service

  1. Create a Helm configuration file. See here for more details on the available settings.

    The example is prefilled with the necessary data collected on previous steps.

    values-search.yaml 
    dgctlDockerRegistry: docker.storage.example.local:5000

imagePullSecrets:
    - name: onpremise-registry-creds

imagePullPolicy: IfNotPresent

dgctlStorage:
    host: artifacts.storage.example.local:443
    bucket: onpremise-artifacts
    accessKey: AKIAIOSFODNN7EXAMPLE
    secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
    manifest: manifests/1640661259.json
    secure: false
    region: ''

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:
    enabled: true
    className: nginx
    hosts:
        - host: search-api.example.com
          paths:
              - path: /
                pathType: Prefix
    tls: []
    #- hosts:
    #  - search-api.example.com
    #  secretName: secret.tls

customCAs:
    bundle: ''
    # bundle: |
    #   -----BEGIN CERTIFICATE-----
    #   ...
    #   -----END CERTIFICATE-----
    certsPath: ''

    Where:

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

    • dgctlStorage: Installation Artifacts Storage settings.

      • Fill in the common settings to access the storage: endpoint, bucket, and access credentials.
      • 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. See Installation artifacts lifecycle.
      • secure: whether to use HTTPS for interacting with the S3 compatible storage. Default value: false.
      • region: S3 storage region.

    • api.resources: computational resources settings for the API backend service. To find out recommended resource values, see Computational resources.

    • nginx.resources: computational resources settings for the NGINX backend service. To find out recommended resource values, see Computational resources.

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

    • customCAs: custom certificates settings.

      • bundle: text representation of a certificate in the X.509 PEM public-key format.
      • certsPath: bundle mount directory in the container.

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

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

Install Catalog APIs service

  1. Create a Helm configuration file. See here for more details on the available settings.

    Note:

    You can configure the process of importing new data for Catalog APIs. Use the importer settings group of the configuration file (see below).

    The example is prefilled with the necessary data collected on previous steps.

    values-catalog.yaml 
    dgctlDockerRegistry: docker.storage.example.local:5000

imagePullSecrets:
    - name: onpremise-registry-creds

imagePullPolicy: IfNotPresent

dgctlStorage:
    host: artifacts.storage.example.local:443
    bucket: onpremise-artifacts
    accessKey: AKIAIOSFODNN7EXAMPLE
    secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
    manifest: manifests/1640661259.json
    secure: false
    region: ''
    verifySsl: true

api:
    postgres:
        host: catalog-postgresql.storage.example.local
        port: 5432
        name: onpremise_catalog
        username: dbuser_catalog
        password: 650D7AmZjSR1dkNa
    ingress:
        enabled: true
        className: nginx
        hosts:
            - host: catalog-api.example.com
              paths:
                  - path: /
                    pathType: Prefix
        tls: []
        #- hosts:
        #  - catalog-api.example.com
        #  secretName: secret.tls

search:
    url: http://search-api

keys:
    url: http://keys-api
    token: CATALOG_APIS_TOKEN

importer:
    postgres:
        host: catalog-postgresql.storage.example.local
        port: 5432
        name: onpremise_catalog
        username: dbuser_catalog
        password: 650D7AmZjSR1dkNa
        schemaSwitchEnabled: true
    cleaner:
        enabled: true
        versionLimit: 2

license:
    url: 'https://license'
    requestTimeout: 1s

customCAs:
    bundle: ''
    # bundle: |
    #   -----BEGIN CERTIFICATE-----
    #   ...
    #   -----END CERTIFICATE-----
    certsPath: ''

    Where:

    • dgctlDockerRegistry: your Docker Registry endpoint where images of On-Premise services reside.

    • dgctlStorage: Installation Artifacts Storage settings.

      • Fill in the common settings to access the storage: endpoint, bucket, and access credentials.
      • 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. See Installation artifacts lifecycle.
      • secure: whether to use HTTPS for interacting with the S3 compatible storage. Default value: false.
      • region: S3 storage region.
      • verifySsl: whether to enable validation of SSL certificates when connecting to dgctlStorage.host via HTTP. Default value: true.

    • api.postgres: the PostgreSQL database access settings. Use the values you configured in the PostgreSQL on the previous step.

      • host: host name of the server
      • port: port of the server
      • name: database name
      • username: user name
      • password: user password

    • api.ingress: configuration of the Ingress resource. Adapt it to your Ingress installation. The URL specified in the ingress.hosts.host parameter should be accessible from the outside of your Kubernetes cluster, so that users in the private network can browse the URL.

    • search: the Search API service access settings.

      • url: URL of the service. This URL must be accessible from all the pods within your Kubernetes cluster.

    • keys: the API Keys service settings.

      • url: URL of the service. This URL must be accessible from all the pods within your Kubernetes cluster.
      • token: service token for sharing usage statistics with the API Keys service (see Installing API Keys service).

    • importer: settings of the data import (Kubernetes Importer job). New data sets are imported only if no imports have been done for the given manifest before.

      • postgres: settings of the PostgreSQL server access to import new data for objects.

        • host: host name of the server
        • port: port of the server
        • name: database name
        • username: user name
        • password: user password
        • schemaSwitchEnabled: enable/disable working with schemas.
          • true: data is imported to a new schema every time. Switching to older schemas and cleaning them is available.
          • false: creation of new schemas and cleaning the data base is done manually by the administrator.

        For details, see the Update Catalog APIs service section.

      • cleaner: settings of automatically removing old data sets.

        • enabled: automatic removal of old data sets is enabled. For details, see the Update Catalog APIs service section.
        • versionLimit: number of old data sets to keep.

        For additional information about the import process, see Installation artifacts lifecycle.

    • license: the License service settings.

      • url: License service URL address. Example: https://license.
      • requestTimeout: timeout for requests to the License service.

    • customCAs: custom certificates settings.

      • bundle: text representation of a certificate in the X.509 PEM public-key format.
      • certsPath: bundle mount directory in the container.

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

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

    If the configuration file contains importer settings, the command checks if the data already exists in the database and if needed, imports it into PostgreSQL. After that, Helm installs the service.

4. Test deployment

Test Search API service

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

curl search-api.example.com/v2/status?f=common

Test Catalog APIs service

To test that the Catalog APIs 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:

    • API_KEY with the created key.
    • City with any city name you want to search the information for.
    curl catalog-api.example.com/3.0/items/geocode?key=API_KEY&q=City

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

What's next?