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

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

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

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

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

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

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

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

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

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

   Объект	Пример значения	Как получить значение
   Endpoint зеркала реестра Docker	artifacts.example.com	См. Получение артефактов установки
   Секрет Kubernetes для доступа к зеркалу реестра Docker	onpremise-registry-creds	См. Получение артефактов установки
   Домен S3-хранилища с артефактами установки	artifacts.example.com	См. Получение артефактов установки
   Название бакета с артефактами установки	onpremise-artifacts	См. Получение артефактов установки
   Идентификатор ключа для доступа к артефактам установки	AKIAIOSFODNN7EXAMPLE	См. Получение артефактов установки
   Секрет ключа для доступа к артефактам установки	wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY	См. Получение артефактов установки
   Путь к файлу манифеста	manifests/citylens/1640661259.json	См. Получение артефактов установки
   Endpoint сервиса лицензий	https://license.svc	См. Установка сервиса лицензий
   Endpoint MapGL JS API	mapgl.example.local	См. Установка API для работы с картами
   Endpoint Catalog APIs	catalog-api.example.local	См. Установка API для работы с поиском
   Endpoint Pro API	https://pro-api.host	См. Установка 2ГИС Про

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

   • CityLens API и CityLens Routes API,
   • CityLens Routes UI.

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

   Примечание

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

5. Определите доменные имена:

   Пример:

   • Доменное имя для сервиса 2ГИС Ситискан (UI для просмотра загруженных треков): http://citylens-web.host
   • Доменное имя для CityLens API, куда подключается мобильное приложение и загружает треки: http://citylens-api.host
   • Доменное имя для CityLens Routes API (backend-сервиса для планирования задач и построения маршрутов): http://citylens-routes-api.host

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

Настройте PostgreSQL

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

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

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

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

   create user citylens password 'citylens';

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

   create database citylens owner citylens;
   create database routes owner citylens;
   create database hangfire owner citylens;
   create database realtime_data owner citylens;

4. Установите расширение PostGIS для PostgreSQL.

5. Включите расширение PostGIS:

   create extension postgis;

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

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

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

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

   • accessKey: accessKey
   • secretAccessKey: secretAccessKey

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

2. Определите префиксы названий бакетов (buckets): префикс для кадров и префикс для логов мобильного приложения (bucketPrefix и logsBucketPrefix соответственно в Helm-чарте). Бакеты (buckets) будут сгенерированы «на лету».

   Пример:

   • Бакет для основных данных: onprem-citylens.

Настройте Apache Kafka

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

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

• username: kafka
• password: kafka_password

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

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

   Имя топика	Передаваемые данные	Рекомендуемые настройки
   kafka.topics.frames	Кадры съёмки из мобильного приложения	Максимальный размер сообщения — 10 Мб (max.message.bytes: 10485760); Период хранения файла лога — 2 дня (retention.ms: 172800000).
   kafka.topics.tracks	Мета-информация о треке и GPS-трек	Максимальный размер сообщения — 1 Мб (max.message.bytes: 1048576); Период хранения файла лога — 2 дня (retention.ms: 172800000).
   kafka.topics.logs	Логи трека из мобильного приложения	Максимальный размер сообщения — 5 Мб (max.message.bytes: 5242880); Период хранения файла лога — 2 дня (retention.ms: 172800000); Формат сжатия — Gzip (compression.type: gzip).
   kafka.topics.predictions	Детекции	Максимальный размер сообщения — 1 Мб (max.message.bytes: 1048576)
   kafka.topics.framesLifecycle	Данные кадров	Максимальный размер сообщения — 1 Мб (max.message.bytes: 1048576)
   kafka.topics.tracksLifecycle	Данные треков	Максимальный размер сообщения — 1 Мб (max.message.bytes: 1048576)
   kafka.topics.objectsLifecycle	Данные распознанных объектов	Максимальный размер сообщения — 1 Мб (max.message.bytes: 1048576)
   kafka.topics.pro	Набор данных Кадры	Максимальный размер сообщения — 1 Мб (max.message.bytes: 1048576)
   kafka.topics.proDrivers	Набор данных Водители	Максимальный размер сообщения — 5 Мб (max.message.bytes: 5242880)
   kafka.topics.proObjects	Набор данных Объекты	Максимальный размер сообщения — 1 Мб (max.message.bytes: 1048576)

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

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

Установите CityLens API и CityLens Routes API

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

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

   values-citylens-api.yaml

   dgctlDockerRegistry: docker.storage.example.local:5000
   
   api:
     auth:
       enabled: true
       authServerUrl: https://keycloak.host
       realm: CityLens_app
       storeOIDCUserinfoFields: []
       predictorsTokens:
         camcom: token
   
     licensing:
       url: 'https://license.svc'
   
     ingress:
       className: nginx
       enabled: false
       hosts:
       - host: citylens-api.host
         paths:
         - path: /
           pathType: Prefix
       tls:
       - hosts:
         - citylens-api.host
   
   web:
     auth:
       enabled: true
       realm: Inspection_Portal_backend
       authServerUrl: https://keycloak.host
       clientId: citylens-web-client
       clientSecret: secret
       pkce: false
   
     ingress:
       className: nginx
       enabled: true
       hosts:
       - host: citylens-web.host
         paths:
         - path: /
           pathType: Prefix
       tls: []
       - hosts:
         - citylens-web.host
   
   worker:
     camcomSender:
       enabled: true
       apiKey: key
       endpointUrl: http://camcom-mock-service/user_upload
       sourceEnv: test
     reporterPro:
       enabled: true
       predictors: [camcom]
       replicas: 1
   
   kafka:
     bootstrapServer: kafka1.host:9092,kafka2.host:9092,kafka3.host:9092
     username: kafka
     password: kafka_password
     topics:
       frames: frames
       tracks: tracks
       pro: pro
       proObjects: objects
       proDrivers: drivers
       logs: logs
       uploader: uploader
       framesLifecycle: flifecycle
       tracksLifecycle: tlifecycle
       objectsLifecycle: olifecycle
       predictions: predictions
     consumerGroups:
       prefix: citylens_
   
   s3:
     endpoint: https://s3.host
     accessKey: accessKey
     secretAccessKey: secretAccessKey
     bucketPrefix: citylens # приложение само создаст бакет вида bucketPrefix + %Y%m
     logsBucketPrefix: citylens-logs
     verifySsl: true
     setPublicReadACL: false
   
   dgctlStorage:
     host: artifacts.example.com
     secure: false
     bucket: onpremise-artifacts
     accessKey: AKIAIOSFODNN7EXAMPLE
     secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
     manifest: manifests/citylens/1640661259.json
   
   postgres:
     host: postgres.host
     port: 5432
     database: citylens
     username: citylens
     password: citylens
   
   routes:
     imagePullSecrets: [onpremise-registry-creds]
     worker:
       busConfig:
         consumers:
           appEvents:
             groupId: ''
     postgres:
       api:
         database: routes
       hangfire:
         database: hangfire
       realtimeDataApi:
         database: realtime_data
     navi:
       url: http://navi-front
       key: key
     pro:
       authorizationToken: ''
     realtimeData:
       url: https://realtimedata-api.host
   
   dashboardDomain: https://citylens-web.host
   
   locale: en
   
   map:
     tileserverUrl: https://tiles-api-raster.host
     mapgl:
       host:  mapgl-js-api.host
       key: key
   
   pro:
     baseUrl: https://pro-api.host
     key: key
     verifySsl: true
     framesAssetId: ''
     objectsAssetId: ''
   
   customCAs:
     bundle: ''
     # bundle: |
     #   -----BEGIN CERTIFICATE-----
     #   ...
     #   -----END CERTIFICATE-----
     certsPath: ''

   Где:

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

   • api: настройки CityLens API.

     • auth: настройки аутентификации.

       • enabled: включена аутентификация или нет.
       • authServerUrl: URL API службы аутентификации.
       • realm: realm для аутентификации.
       • storeOIDCUserinfoFields: список полей из ответа провайдера OIDC для хранения информации о водителях, загружающих треки.
       • predictorsTokens.camcom: случайно сгенерированная строка длиной 64 символа (ASCII + цифры). Передается в Camcom для доступа к CityLens API.

     • licensing: настройки сервиса лицензий.

       • url: URL-адрес сервиса лицензий. Пример: https://license.svc.

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

   • web: настройки веб-сервиса 2ГИС Ситискан.

     • auth: настройки аутентификации.

       • enabled: включена аутентификация или нет.
       • realm: realm для аутентификации.
       • authServerUrl: URL API службы аутентификации.
       • clientId: ID клиента поставщика OpenID Connect.
       • clientSecret: секрет клиента поставщика OpenID Connect.
       • pkce: включена ли проверка ключа PKCE.

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

   • worker: настройки рабочих процессов 2ГИС Ситискан.

     • camcomSender: настройки рабочих процессов CamcomSender.

       • enabled: включен ли Camcom Sender.
       • apiKey: ключ доступа к API Camcom Sender.
       • endpointUrl: endpoint для Camcom Sender.
       • sourceEnv: имя окружения в Camcom, предоставляемое Camcom'ом.

     • reporterPro: настройки для выгрузки данных в 2ГИС Про.

       • enabled: включена ли интеграция с 2ГИС Про.
       • predictors: предиктор, используемый отгрузчиком данных.
       • replicas: количество реплик пода.

   • kafka: настройки доступа к брокеру Apache Kafka.

     • bootstrapServer: endpoint брокера Kafka. Пример: HOST:PORT.

     • username: имя пользователя.

     • password: пароль пользователя.

     • topics: настройки топиков.

       • frames: список топиков для Frames Saver.
       • tracks: список топиков для Track Metadata.
       • pro: топик для синхронизации фреймов с 2ГИС Про через Reporter Pro.
       • proObjects: топик для синхронизации локализованных детекций (распознанных объектов) с 2ГИС Про через Reporter Pro.
       • proDrivers: топик для синхронизации треков водителей с 2ГИС Про через Reporter Pro.
       • logs: топик для логов мобильного приложения (загружаются через CityLens API).
       • uploader: топик для Uploader.
       • framesLifecycle: топик для событий жизненного цикла фреймов.
       • tracksLifecycle: топик для событий жизненного цикла треков.
       • objectsLifecycle: топик для событий жизненного цикла объектов.
       • predictions: топик для событий прогнозов от детекторов.

     • consumerGroups: настройка группы потребителей.

       • prefix: префикс для топиков группы потребителей.

   • s3: настройки S3-совместимого хранилища.

     • endpoint: endpoint S3 хранилища. Пример: HOST:PORT или URL.
     • accessKey: идентификатор ключа для доступа к бакету S3.
     • secretAccessKey: секретный ключ для доступа к бакету S3.
     • bucketPrefix: префикс имени бакета в S3 для бакетов фреймов.
     • logsBucketPrefix: префикс имени бакета в S3 для бакетов логов мобильных приложений.
     • verifySsl: включена проверка SSL-сертификатов или нет.
     • setPublicReadACL: сделать ли S3-бакет публичным (просмотр кадров будет доступен без авторизации).

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

     • host: адрес или IP S3-хранилища артефактов развертывания.
     • secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
     • bucket: имя бакета S3.
     • accessKey: идентификатор ключа для доступа к бакету S3.
     • secretKey: секретный ключ для доступа к бакету S3.
     • manifest: путь до файла с манифестом в формате manifests/citylens/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.

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

   • host: адрес или IP PostgreSQL read-write (rw) хоста.

   • port: номер порта.

   • database: имя БД.

   • username: имя пользователя БД c rw-доступом.

   • password: пароль пользователя БД.

   • routes: настройки CityLens Routes API.

     • imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
     • worker.busConfig.consumers.appEvents.groupId: ID потребительской группы Kafka для передачи событий.
     • postgres: настройки доступа к PostgreSQL.
       • api.database: имя базы данных для доступа API.
       • hangfire.database: имя базы данных для доступа hangfire (Планировщика задач).
       • realtimeDataApi.database: имя базы данных для доступа RealtimeData API (для получения текущей геопозиции водителя).
     • navi: настройки для интеграции с API навигации.
       • url: URL для доступа к Navi-Front.
       • key: ключ для доступа к API навигации. Убедитесь, что выполнены следующие условия:
         • Этот ключ содержит права доступа к Routes Planner API.
         • Соответствующий сервисный токен из сервиса API-ключей добавлен в конфигурационный файл Navi-Router (параметр keys.apis.route-planner-api).
     • pro: настройки для интеграции с 2ГИС Про.
       • authorizationToken: Bearer-токен для отправки данных в Про. Подробнее см. в инструкции по загрузке данных по API.
     • realtimeData: настройки для интеграции с RealtimeData API.
       • url: URL для доступа к RealtimeData API.

   • dashboardDomain: ссылка на веб-версию 2ГИС Ситискан.

   • locale: используемый язык.

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

     • tileserverUrl: URL сервера для получения растровых тайлов.

     • mapgl: настройки доступа к MapGL JS API.

       • host: имя хоста MapGL.
       • key: ключ сервера MapGL.

   • pro: группа настроек для интеграции 2ГИС Ситискан с 2ГИС Про.

     • baseUrl: URL Pro API для актуализации фильтров.
     • key: токен аутентификации Pro API
     • verifySsl: включена проверка SSL-сертификатов или нет.
     • framesAssetId: ID набора данных для загрузки фреймов.
     • objectsAssetId: ID набора данных для загрузки объектов.

   • customCAs: настройки пользовательских сертификатов.

     • bundle: текстовое представление сертификата в формате X.509 PEM public-key.
     • certsPath: директория для монтирования сертификата внутри контейнера.

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

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

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

Установите CityLens Routes UI

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

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

   values-citylens-ui.yaml

   dgctlDockerRegistry: docker.storage.example.local:5000
   
   imagePullSecrets: [onpremise-registry-creds]
   
   env:
       CATALOG_API_URL: 'https://catalog-api.ingress.host'
       MAPGL_API_URL: 'http://mapgl-js-api.ingress.host'
       MAPGL_DEFAULT_CENTER: ''
       MAPGL_KEY: ''
       SSO_API_URL: ''
       SSO_CLIENT_ID: ''
       SSO_CLIENT_SECRET: ''
       SSO_SCOPE: 'openid email name phone'
       ROUTES_API_URL: 'http://citylens-routes-api.ingress.host'

   Где:

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

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

   • env: настройка окружения.

     • CATALOG_API_URL: базовый URL для Catalog APIs.
     • MAPGL_API_URL: базовый URL для MapGL JS API.
     • MAPGL_DEFAULT_CENTER: координаты центра карты по умолчанию в формате долгота,широта (например, 37.61565,55.76805).
     • MAPGL_KEY: ключ для доступа к MapGL JS API.
     • SSO_API_URL: базовый URL для API авторизации по технологии единого входа (SSO) в формате <origin>/realms/<realm> (например, https://<domain>.com/realms/Inspection_Portal_backend).
     • SSO_CLIENT_ID: идентификатор клиента OpenID для SSO-авторизации.
     • SSO_CLIENT_SECRET: ключ клиента OpenID для SSO-авторизации.
     • SSO_SCOPE: набор пользовательских атрибутов, которые запрашивает клиент OpenID для SSO-авторизации.
     • ROUTES_API_URL: базовый URL для CityLens Routes API.

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

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

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

4. Проверьте работоспособность 2ГИС Ситискан

Воспользуйтесь одним из способов:

• Перейдите по адресу http://citylens-web.host.
• Запустите мобильное приложение 2ГИС Ситискан.

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

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

Что дальше?

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

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

  • мобильный SDK,
  • GIS-платформа,
  • Менеджер Платформы.

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