Установка 2ГИС Про

Важное примечание:

Все пароли и ключи в этом разделе приведены в иллюстративных целях.

При реальной установке рекомендуется использовать более сложные и надёжные пароли.

1. Перед установкой

1. Ознакомьтесь с основной информацией:

   • Документация сервисов 2ГИС Про
   • Архитектура программного комплекса 2ГИС
   • Системные требования

2. Выполните предварительные шаги:

   1. Подготовка к установке
   2. Установка сервиса лицензий
   3. Установка сервиса API-ключей
   4. Установка API для работы с картами
   5. Установка API для работы с поиском
   6. Установка API для работы с навигацией

3. Соберите необходимые данные, заданные или полученные на предыдущих шагах:

   Объект	Пример значения	Как получить значение
   Endpoint зеркала реестра Docker	docker.storage.example.local:5000	См. Получение артефактов установки
   Endpoint S3-совместимого хранилища артефактов установки	artifacts.storage.local	См. Получение артефактов установки
   Имя бакета для хранения артефактов	onpremise-artifacts	См. Получение артефактов установки
   Идентификатор ключа для доступа к артефактам установки	AKIAIOSFODNN7EXAMPLE	См. Получение артефактов установки
   Секрет ключа для доступа к артефактам установки	wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY	См. Получение артефактов установки
   Endpoint сервиса лицензий	https://license	См. Установка сервиса лицензий
   Endpoint MapGL JS API	http://mapgl-js-api	См. Установка API для работы с картами
   Endpoint Catalog APIs	http://catalog-api	См. Установка API для работы с поиском
   Endpoint API навигации	http://navi-front	См. Установка API для работы с навигацией
   API-ключи	MAPGL_KEY CATALOG_KEY NAVI_KEY	См. Установка сервиса API-ключей

4. Убедитесь, что удовлетворены требования к ресурсам, приведенные в Helm-чартах:

   • Pro API,
   • Pro UI.

   Подробнее о том, как это сделать, смотрите в документе Системные требования.

   Примечание

   Содержание Helm-чартов, описанное в данном разделе, актуально для последней версии 2ГИС Про (см. Релизы 2ГИС Про). Чтобы изучить параметры для более ранних версий, откройте нужный values.yaml в GitHub и в списке тегов слева выберите тег Pro-<версия>.

5. Определите доменные имена для сервиса 2ГИС Про. Например:

   • Доменное имя для API-бэкенда: pro-api.example.com
   • Доменное имя для фронтенда: pro-ui.example.com

2. Подготовьте инфраструктуру

Настройте PostgreSQL

Разместите кластер PostgreSQL с доменным именем pro-postgresql.storage.example.local в приватной сети. Предполагается, что кластер работает на стандартном порту 5432.

Настройте кластер PostgreSQL для использования в качестве хранилища:

1. Подключитесь к кластеру от имени суперпользователя (обычно это postgres).

2. Создайте пользователя баз данных и установите пароль для него:

   create user dbuser_pro password '';

3. Создайте базы данных, принадлежащие этому пользователю:

   create database onpremise_pro owner dbuser_pro;
   create database onpremise_pro_tasks owner dbuser_pro;

Настройте S3-хранилище

Разместите S3-совместимое хранилище (например, Ceph) с доменным именем pro-s3.storage.example.local в приватной сети. Предполагается, что хранилище работает на стандартном порту 80.

Настройте S3-совместимое хранилище:

1. Создайте пользователя, который будет использоваться для сервиса:

   • Access key: ``
   • Secret key: ``

   Запомните ключи доступа для этого пользователя.

2. Определите названия бакетов (buckets), которые будут использоваться для сервиса. Например:

   • Бакет с наборами данных, агрегатами и фильтрами: assets.
   • Бакет с подготовленными данными слоя: layer_data.
   • Бакет с наборами данных, агрегатами и фильтрами, созданными пользователем: user_assets.

Настройте Elasticsearch

Разместите кластер Elasticsearch с доменным именем pro-elastic.storage.example.local в приватной сети. Предполагается, что кластер работает на порту 9200.

Создайте пользователя, который будет использоваться для сервиса:

• Имя пользователя: ``
• Пароль: ``

Запомните реквизиты для этого пользователя.

Настройте Apache Kafka

1. Разместите кластер Apache Kafka с доменным именем pro-kafka.storage.example.local в приватной сети. Предполагается, что кластер работает на стандартном порту 9092.

2. Создайте пользователя, который будет использоваться для сервиса:

   • username: kafka
   • password: kafka_password

   Запомните реквизиты для этого пользователя.

3. (Рекомендуется) Настройте топики Apache Kafka следующим образом:

   Имя топика	Передаваемые данные	Рекомендуемые настройки
   kafka.importTasksTopic.name	Задачи на импорт пользовательских наборов данных	Максимальный размер сообщения — 5 Мб (max.message.bytes: 5242880); Период хранения файла лога — 3 дня (retention.ms: 259200000); Формат сжатия — Gzip (compression.type: gzip).
   kafka.assetDataTopic.name	Объекты пользовательских наборов данных	Максимальный размер сообщения — 5 Мб (max.message.bytes: 5242880); Период хранения файла лога — 5 дней (retention.ms: 432000000); Формат сжатия — Gzip (compression.type: gzip).
   kafka.permissionsTopic.name	Сообщения об изменении прав доступа	Максимальный размер сообщения — 5 Мб (max.message.bytes: 5242880); Период хранения файла лога — 1 день (retention.ms: 86400000); Формат сжатия — Gzip (compression.type: gzip).
   kafka.eventsTopic.name	Различные события	Максимальный размер сообщения — 20 Мб (max.message.bytes: 20000000); Период хранения файла лога — 1 день (retention.ms: 86400000); Максимальный размер данных для хранения — 500 Мб (retention.bytes: 524288000); Формат сжатия — Gzip (compression.type: gzip).

   Полное описание настроек см. в документации Apache Kafka.

3. Установите 2ГИС Про

Установите Pro API

1. Создайте конфигурационный файл для Helm. Подробное описание доступных параметров см. здесь.

   Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.

   values-pro-api.yaml

   dgctlDockerRegistry: ''
   
   dgctlStorage:
       host: artifacts.storage.example.local:443
       secure: false
       bucket: onpremise-artifacts
       accessKey: AKIAIOSFODNN7EXAMPLE
       secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
       manifest: manifests/pro/1640661259.json
       region: ''
       disablePayloadSigning: false
   
   api:
       ingress:
           enabled: true
           className: nginx
           hosts:
               - host: pro-api.example.com
                 paths:
                     - path: /
                       pathType: Prefix
           tls: []
           #  secretName: secret.tls
   
       pod:
           imagePullSecrets: [onpremise-registry-creds]
           resources:
               requests:
                   cpu: 400m
                   memory: 256M
               limits:
                   cpu: 1
                   memory: 1024M
       service:
           serviceAccount: ''
       settings:
           licenseKey: ''
           tempPath: /tmp
           corsOrigins: ''
           logging:
               format: simple
   
   permissions:
       settings:
           auth:
               apiKey: ''
   
   license:
       url: 'https://license.svc'
   
   s3:
       assetsDataBucket: ''
       userAssetsDataBucket: ''
       layerDataBucket: ''
       snapshotBucket: ''
       resourcesBucket: ''
   
   postgres:
       api:
           rw:
               host: 'pro-postgresql.storage.example.local'
               port: 5432
               name: 'onpremise_pro'
               username: 'dbuser_pro'
               password: ''
           ro: {}
       tasks:
           rw:
               host: 'pro-postgresql.storage.example.local'
               port: 5432
               name: 'onpremise_pro_tasks'
               username: 'dbuser_pro'
               password: ''
           ro: {}
       permissions:
           rw:
               host: 'pro-postgresql.storage.example.local'
               port: 5432
               name: 'onpremise_pro'
               username: 'dbuser_pro'
               password: ''
           ro: {}
   
   kafka:
       bootstrapServers: ''
       securityProtocol: SaslPlaintext
       createTopics: true
       sasl:
           mechanism: ScramSha512
           username: ''
           password: ''
       assetTopicsReaderGroupId: ''
       importTasksTopic:
           name: ''
           readerGroupId: ''
       assetDataTopic:
           name: ''
       eventsTopic:
           name: ''
           readerGroupId: ''
   
   elastic:
       secure: false
       nodes:
           - port: 9200
             host: pro-elastic.storage.example.local
   
   redis:
       host: ''
       port: ''
   
   catalog:
       url: ''
       key: ''
   
   navi:
       url: ''
       key: ''
   
   search:
       url: ''
   
   assetImporter:
       appName: asset-importer
       repository: 2gis-on-premise/pro-importer
       schedule: 0 18 * * *
       backoffLimit: 2
       successfulJobsHistoryLimit: 3
       failedJobsHistoryLimit: 3
       nodeSelector: {}
       settings:
           maxParallelJobs: 4
       startOnDeploy: true

   Где:

   • dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов On-Premise. Пример: HOST:PORT.

   • dgctlStorage: настройки хранилища артефактов развертывания.

     • Укажите общие настройки для доступа к хранилищу: endpoint, имя бакета, реквизиты для доступа.
     • secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
     • manifest: укажите путь до файла с манифестом в формате manifests/pro/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.
     • region: регион S3-хранилища.
     • disablePayloadSigning: отключить ли проверку целостности данных. Если S3-совместимое хранилище не поддерживает AWS Signature Version 4 streaming, значение должно быть true. Значение по умолчанию: false.

   • api: переменные окружения.

     • ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре api.ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.
     • pod.imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
     • pod.resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
     • service.serviceAccount: учётная запись службы Kubernetes.
     • settings.licenseKey: ключ лицензии On-Premise.
     • settings.tempPath: путь к директории, используемой для временных данных.
     • settings.corsOrigins: политика CORS. Если значение пустое, любому источнику разрешается выполнять запросы к сервису Pro API.
     • settings.logging.format: формат ведения журнала логирования. Возможные значения: default — компактный JSON, renderedCompactJson — отображаемый JSON, simple — простой текст.

   • permissions.settings.auth.apiKey: ключ доступа к Permissions API для выполнения авторизованных действий.

   • license.url: URL сервиса лицензий.

   • s3: настройки хранилища S3.

     • assetsDataBucket: имя бакета S3 с подготовленными наборами данных, агрегатами и фильтрами.
     • userAssetsDataBucket: имя бакета S3 с наборами данных, агрегатами и фильтрами, созданными пользователем.
     • layerDataBucket: имя бакета S3 с подготовленными данными слоя.
     • snapshotBucket: имя бакета S3 для хранения моментальных снимков (snapshots) пошагового обновления данных.
     • resourcesBucket: имя бакета S3 для хранения статичных ресурсов.

   • postgres: настройки PostgreSQL.

     • api: настройки доступа к базе данных onpremise_pro для чтения и записи (postgres.api.rw) или только для чтения (postgres.api.ro).

       • host: имя или IP-адрес хоста.
       • port: номер порта.
       • name: имя базы данных.
       • username: имя пользователя базы данных.
       • password: пароль пользователя базы данных.

     • tasks: настройки доступа к базе данных onpremise_pro_tasks микросервиса для управления фоновыми задачами для чтения и записи (postgres.tasks.rw) или только для чтения (postgres.tasks.ro). Набор параметров аналогичен группе postgres.api, но используется отдельная база данных.

     • permissions: настройки доступа к базе данных onpremise_pro микросервиса для управления правами доступа (Permissions API) для чтения и записи (postgres.permissions.rw) или только для чтения (postgres.permissions.ro). Набор параметров аналогичен группе postgres.api, и используется та же база данных.

   • kafka: настройки Apache Kafka.

     • bootstrapServers: endpoints брокера Kafka. Пример: HOST1:PORT1,HOST2:PORT2.

     • securityProtocol: протокол безопасности Kafka.

     • createTopics: включить автоматическое создание топиков или нет.

     • sasl: настройки SASL.

       • mechanism: механизм SASL.
       • username: имя пользователя SASL.
       • password: пароль пользователя SASL.

     • assetTopicsReaderGroupId: ID потребительской группы Kafka для чтения данных из стриминговых ассетов.

     • importTasksTopic: настройки топика Kafka для задач импорта пользовательских наборов данных.

       • name: название топика.
       • readerGroupId: ID потребительской группы Kafka для чтения задач импорта.

     • assetDataTopic: настройки топика Kafka для объектов в пользовательских наборах данных.

       • name: название топика.

     • eventsTopic: настройки топика Kafka для событий.

       • name: название топика.
       • readerGroupId: ID потребительской группы Kafka для чтения событий.

   • elastic: настройки Elasticsearch.

     • secure: использовать ли HTTPS для работы с Elasticsearch. Значение по умолчанию: false.
     • nodes[0].host: адрес хоста Elasticsearch.
     • nodes[0].port: номер порта.

   • redis: настройки Redis.

     • host: адрес хоста Redis. Пример: HTTP(S)://HOST.
     • port: номер порта.

   • catalog: настройки доступа к Catalog APIs.

     • url: URL-адрес Catalog APIs. Пример: HTTP(S)://HOST.
     • key: ключ доступа к Catalog APIs.

   • navi: настройки доступа к Isochrone API.

     • url: URL-адрес Isochrone API. Пример: HTTP(S)://HOST.
     • key: ключ доступа к Isochrone API.

   • search: настройки доступа к Search API.

     • url: URL-адрес Search API. Пример: HTTP(S)://HOST.

   • assetImporter: настройки cron-задания для импорта данных.

     • appName: имя cron-задания для импорта данных.
     • repository: адрес репозитория с Docker-образом.
     • schedule: расписание выполнения задания в cron-формате. Например: */10 * * * *.
     • backoffLimit: количество повторных попыток, после которых задание будет считаться неуспешным.
     • successfulJobsHistoryLimit: ограничение на размер истории выполненных заданий.
     • failedJobsHistoryLimit: ограничение на размер истории невыполненных заданий.
     • nodeSelector: селектор узлов Kubernetes.
     • settings.maxParallelJobs: количество заданий импорта, которые могут быть запущены одновременно.
     • startOnDeploy: импорт данных должен начинаться при установке или обновлении сервиса.

2. Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-pro-api.yaml:

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

   В параметре --version укажите нужную версию 2ГИС Про. Список версий см. в разделе Релизы 2ГИС Про.

Установите Pro UI

1. Создайте конфигурационный файл для Helm. Подробное описание доступных параметров см. здесь.

   Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.

   values-pro-ui.yaml

   dgctlDockerRegistry: ''
   
   imagePullSecrets: [onpremise-registry-creds]
   
   dgctlStorage:
       host: artifacts.storage.example.local:443
       bucket: onpremise-artifacts
       accessKey: AKIAIOSFODNN7EXAMPLE
       secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
       manifest: manifests/pro/1640661259.json
       secure: false
       region: ''
       disablePayloadSigning: false
   
   ui:
       appLocale: en_AE
   
       appInitialMapCenter: '[37.64, 55.74]'
   
       api:
           url: 'https://pro-api.example.com/'
   
       mapgl:
           host: 'mapgl-js-api.example.com'
           key: ''
           styleUrl: ''
           stylePreview: ''
   
   resources:
       requests:
           cpu: 300m
           memory: 256Mi
       limits:
           cpu: 1
           memory: 384Mi
   
   ingress:
       enabled: true
       className: nginx
       hosts:
           - host: pro-ui.example.com
               paths:
                   - path: /
                   pathType: Prefix
       tls: []
       #- hosts:
       #  - pro-ui.example.com
       #  secretName: secret.tls

   Где:

   • dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов On-Premise. Пример: HOST:PORT.

   • imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.

   • dgctlStorage: настройки хранилища артефактов развертывания.

     • Укажите общие настройки для доступа к хранилищу: endpoint, имя бакета, реквизиты для доступа.
     • manifest: укажите путь до файла с манифестом в формате manifests/pro/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.
     • secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
     • region: регион S3-хранилища.
     • disablePayloadSigning: отключить ли проверку целостности данных. Если S3-совместимое хранилище не поддерживает AWS Signature Version 4 streaming, значение должно быть true. Значение по умолчанию: false.

   • ui.appLocale: язык приложения. Возможные значения: en_AE, ru_RU.

   • ui.appInitialMapCenter: координаты карты по умолчанию. Состоят из двух чисел в массиве: [lng, lat]. Например: [55.27, 25.2] для Дубая, [37.64, 55.74] для Москвы.

   • ui.api.url: базовый URL для Pro API со слешем в конце. Пример: HTTP(S)://HOST/.

   • ui.mapgl.host: хост сервиса MapGL JS API без протокола и без слеша в конце. Пример: HOST.

   • ui.mapgl.key: API-ключ для сервиса MapGL JS API.

   • ui.mapgl.styleUrl: путь к директории с конфигурационным файлом (styles.json) для управления стилями карты. Пример: //mapgl.ingress.host/style.

   • ui.mapgl.stylePreview: URL для миниатюры изображения, которая будет отображаться в менеджере стилей карты для стиля по умолчанию.

   • resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.

   • ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.

2. Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-pro-ui.yaml:

   helm upgrade --install --version=VERSION --atomic --values ./values-pro-ui.yaml pro-ui 2gis-on-premise/pro-ui

   В параметре --version укажите нужную версию 2ГИС Про. Список версий см. в разделе Релизы 2ГИС Про.

4. Проверьте работоспособность установленных сервисов

Выполните запрос с использованием cURL или аналогичного инструмента:

curl -X 'GET' \
  'https://PRO-API/items/1,14,164' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer TOKEN' # Или см. settings.auth.apiKey

Для авторизации используйте Bearer-токен или см. установленное значение параметра settings.auth.apiKey в конфигурационном файле Pro API.

Ответ должен иметь код состояния HTTP 200 и содержать список элементов в формате JSON.

5. Настройте аутентификацию пользователей

Настройте внешнего поставщика OpenID Connect для аутентификации конечных пользователей в 2ГИС Про.

Что дальше?

• Узнайте, как обновить 2ГИС Про.

• Установите другие продукты программного комплекса 2ГИС:

  • 2ГИС Ситискан,
  • мобильный SDK,
  • GIS-платформа,
  • прокси для API пробок,
  • Менеджер Платформы.

• Изучите рекомендации по обслуживанию системы.