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

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

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

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

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

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

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

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

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

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

   Объект	Пример значения	Как получить значение
   Endpoint зеркала реестра Docker	artifacts.example.com	См. Получение артефактов установки
   Секрет Kubernetes для доступа к зеркалу реестра Docker	onpremise-registry-creds	См. Получение артефактов установки
   Домен S3-хранилища с артефактами установки	artifacts.example.com	См. Получение артефактов установки
   Название бакета с артефактами установки	onpremise-artifacts	См. Получение артефактов установки
   Идентификатор ключа для доступа к артефактам установки	AKIAIOSFODNN7EXAMPLE	См. Получение артефактов установки
   Секрет ключа для доступа к артефактам установки	wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY	См. Получение артефактов установки
   Путь к файлу манифеста	manifests/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-чарте. Подробнее о том, как это сделать, смотрите в документе Системные требования.

   Примечание

   Содержание Helm-чарта, описанное в данном разделе, актуально для последней версии On-Premise (см. Релизы). Чтобы изучить параметры для более ранних версий, откройте values.yaml в GitHub и введите номер нужной версии комплекса (например, 1.18.0) в переключателе тегов слева.

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

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

1. (Рекомендуется) Настройте топики 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/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:
       database: routes
     hangfire:
       postgres:
         database: hangfire
     navi:
       url: http://navi-front
       key: key
     pro:
       authorizationToken: ''
     realtimeDataApi:
       postgres:
         database: realtime_data
     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/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.database: имя БД PostgreSQL.
     • hangfire.postgres.database: имя БД PostgreSQL для доступа hangfire (Планировщика задач).
     • navi: настройки для интеграции с API навигации.
       • url: URL для доступа к Navi-Front.
       • key: ключ для доступа к API навигации. Убедитесь, что выполнены следующие условия:
         • Этот ключ содержит права доступа к Routes Planner API.
         • Соответствующий сервисный токен из сервиса API-ключей добавлен в конфигурационный файл Navi-Router (параметр keys.apis.route-planner-api).
     • pro: настройки для интеграции с 2ГИС Про.
       • authorizationToken: Bearer-токен для отправки данных в Про. Подробнее см. в инструкции по загрузке данных по API.
     • realtimeDataApi.postgres.database: имя БД PostgreSQL для доступа к RealtimeData 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=1.32.0 --atomic --values ./values-citylens-api.yaml citylens 2gis-on-premise/citylens

Установите 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_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_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=1.32.0 --atomic --values ./values-citylens-ui.yaml citylens 2gis-on-premise/citylens

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

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

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

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

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

Что дальше?

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

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

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

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

  • резервное копирование инфраструктурных баз данных,
  • мониторинг состояния сервисов,
  • сбор и отправка логов.