Installing Platform Manager

1. Before installing

1. Consider getting familiar with:

   • Platform Manager service documentation
   • On-Premise solution architecture
   • System requirements

2. Make sure the necessary preparation steps are completed:

   1. Preparation for installation
   2. Installing API Keys service
   3. Installing maps API
   4. Installing search API
   5. Installing navigation API

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
   MapGL JS API endpoint	http://mapgl-js-api	See Installing maps API
   Catalog APIs endpoint	http://catalog-api	See Installing search API
   Navigation API endpoint	http://navi-front	See Installing navigation API
   API Keys	MAPGL_KEY CATALOG_KEY NAVI_KEY	See Installing API Keys service

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

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

   Note

   Contents of the Helm chart described in this chapter are relevant for the latest API Platform version (see API Platform releases). To find parameters for earlier versions, open values.yaml on GitHub and select a Platform-<version> tag in the tag switcher on the left.

5. Choose the domain name for the service. For example, platform.example.com.

2. Install Platform Manager

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-platform.yaml

   dgctlDockerRegistry: ''
   
   imagePullSecrets: [onpremise-registry-creds]
   
   ui:
       brand: ''
       defaultLocale: en
       pages: ''
       playgrounds: ''
   
       status:
           mapgl: "MapGL JS=http://mapgl-js-api,Tiles API=http://tiles-api/healthcheck"
           search: "Catalog API=http://catalog-api,Search API=http://search-api/v2/status"
           navi: "Castle=http://navi-castle/cities.conf,Back=http://navi-back-directions-car/about,Routing=http://navi-front/healthcheck"
           pro: "PRO UI=http://pro-ui:3000/api/healthcheck/app,PRO API=http://pro-api/health/live,PRO Permissions API=http://pro-api-permissions"
           gisPlatform: "http://gis-platform-portal"
           keys: "Keys UI=http://keys-admin,Keys API=http://keys-api/healthcheck"
           mapStyles: "http://styles-api/healthcheck"
   
       platform:
           api:
               url: 'https://keys-api.example.com'
   
       mapgl:
           url: 'https://mapgl-js-api.example.com'
           scriptPath: /api.js
           key: 'MAPGL_KEY'
           initCenter: ''
   
       catalog:
           url: 'https://catalog.example.com'
           key: 'CATALOG_KEY'
   
       navi:
           url: 'https://navi.example.com'
           key: 'NAVI_KEY'
   
       resources:
           requests:
               cpu: 300m
               memory: 384M
           limits:
               cpu: 1100m
               memory: 512M
   
       ingress:
           enabled: true
           className: nginx
           hosts:
               - host: platform.example.com
                 paths:
                     - path: /
                       pathType: Prefix
           tls: []
           #- hosts:
           #  - platform.example.com
           #  secretName: secret.tls

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services in the HOST:PORT format.

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

   • ui: common application settings:

     • brand: branding inside the application. Possible values: 2gis, urbi.

     • defaultLocale: default application language. Possible values: en.

     • pages: list of available pages in the application. Possible values: profile, signup, status, playground, map_styles. Values are separated by commas and written in one string, for example: 'status, playground'. First value in the list is the default page.

     • playgrounds: list of available playgrounds in the application. Possible values: mapgl (you additionally need to specify the ui.mapgl.url parameter), geocoder (you additionally need to specify the ui.catalog.url parameter), directions (you additionally need to specify the ui.navi.url parameter). Values are separated by commas and written in one string, for example: 'mapgl, geocoder'.

     • status: list of statuses of On-Premise services.

       Each entry in a string containing pairs of the service name and its healthcheck URL. Pairs are separated by commas. Values inside a pair are joined by the "=" symbol. For example, mapgl: 'MapGL JS=https://example.com/healthcheck'. URL must be absolute. You can specify only the URL, for example: mapgl: 'https://example.com/healthcheck'.

       • mapgl: status of the MapGL JS API service.
       • search: statues of the Search services.
       • navi: status of the Navigation services.
       • pro: status of Urbi Pro.
       • gisPlatform: status of the GIS Platform.
       • keys: status of the API Keys service.
       • mapStyles: status of the Styles API service.

     • platform: access settings for the API Keys service service:

       • api.url: address of the service host in the HTTP(S)://HOST format.

     • mapgl: access settings for the MapGL JS API service:

       • url: address of the service host in the HTTP(S)://HOST format.
       • scriptPath: path to the service initialization script. The path is built relatively to ui.mapgl.url. Possible values: /api.js.
       • key: access key for the service.
       • initCenter: default map coordinates presented as two numbers in an array: [lng, lat]. For example: [55.27, 25.2] for Dubai, [37.64, 55.74] for Moscow.

     • catalog: access settings for the Catalog APIs service:

       • url: address of the service host in the HTTP(S)://HOST format.
       • key: access key for the service.

     • navi: access settings for the navigation API service:

       • url: address of the service host in the HTTP(S)://HOST format.
       • key: access key for the service.

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

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

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

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

   In the --version parameter, specify the required API Platform version. For a list of versions, see the API Platform releases section.

3. Test deployment

Go to https://platform.example.com in a browser. You should be successfully logged into the web interface.

In the Platform Manager, you can check the status of installed services, upload custom styles, and test key APIs: for more details, see the Working with the Platform Manager instruction.

4. Set up user authentication

To work with the Platform Manager, end users must pass the authentication. The On-Premise solution does not provide an authentication service to be installed in a private environment. Therefore, you need to use your own OpenID Connect (OIDC) provider to authorize users via Single Sign-On (SSO) technology.

Only users registered in the external OIDC provider database can authenticate and be authorized in the Platform Manager. User management is also handled on the provider side.

Configure your OIDC provider by meeting the following requirements:

1. Define the mandatory claims. The following user data must always be filled in the user-info response:

   • sub - user identifier.
   • email - user email.
   • email_verified - flag indicating if the email is verified by the user.
   • name - user full name.
   • phone_number - user phone number.

2. Configure the scopes that can be used to request the defined claims. The standard set of scopes includes the following values:

   • openid - mandatory parameter indicating that OIDC is used for user authentication.
   • email - user email.
   • profile - link to the user profile.
   • phone - user phone number.

3. Create a client in your OIDC provider:

   1. Configure the client ID (client_id) and secret (client_secret).

   2. Specify the Callback URL and the Logout URL for the service:

      • Callback URL: https://{application_host}/api/auth/code
      • Logout URL: https://{application_host}/api/auth/post_sign_out

   3. Configure the client to work with previously defined scopes.

What's next?

• Find out how to update the Platform Manager service.

• Install other On-Premise products:

  • Urbi Pro,
  • CityLens
  • GIS Platform
  • Traffic API proxy

• Learn recommendations on maintaining the installation.