Skip to main content

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:

    ObjectExample valueHow to get value
    Docker Registry mirror endpointdocker.storage.example.local:5000See Fetching installation artifacts
    Kubernetes secret for accessing Docker Registryonpremise-registry-credsSee Fetching installation artifacts
    Installation artifacts S3 storage domain nameartifacts.example.comSee Fetching installation artifacts
    Bucket name for installation artifactsonpremise-artifactsSee Fetching installation artifacts
    Installation artifacts access keyAKIAIOSFODNN7EXAMPLESee Fetching installation artifacts
    Installation artifacts secret keywJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEYSee Fetching installation artifacts
    Path to the manifest filemanifests/1640661259.jsonSee Fetching installation artifacts
    License service endpointhttps://licenseSee Installing License service
    API Keys service endpointhttp://keys-apiSee Installing API Keys service
    Service tokenCATALOG_APIS_TOKENSee 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​

Configure PostgreSQL​

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

Configure the PostgreSQL cluster for usage as a storage:

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

  2. Create a database user and 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 the required external extensions JsQuery and PostGIS for PostgreSQL.

    You can get the extensions from repositories where they are available as ready-made packages. For example, for Debian/Ubuntu-based distributions, the installation is performed by the commands:

    sudo apt install postgresql-15-jsquery
    sudo apt install postgresql-15-postgis-3
    sudo apt install postgis

  5. Enable 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;

For installing Catalog APIs​

If you plan to install Catalog APIs, add your first partner and create an API key for the partner. See the Managing API keys instruction.

The key is checked before installing Catalog APIs. The list of available services for the key must include the search APIs.

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

    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: endpoint of your Docker Registry with the images of the On-Premise services.

    • 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.32.0 --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: [onpremise-registry-creds]

    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.

    • imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.

    • 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.32.0 --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, send 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, from the example.com host in the private network:

  1. Using the API keys management web interface, create an API key that has access to Places API and Regions API.

  2. Send 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?​