GIS Platform | Urbi On-Prem | 2GIS Documentation

Installing GIS Platform

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. Consider getting familiar with:

  2. Make sure the necessary preparation steps are completed:

    1. Preparation for installation
    2. Fetching installation artifacts
    3. Installing API Keys service
    4. Installing Traffic API Proxy
    5. Installing maps API
    6. Installing search 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
    API Keys service endpoint keys.example.local See Installing API Keys service
    Tiles API endpoint tiles.example.local See Installing maps API
    Catalog API endpoint catalog.example.local See Installing search API
    Traffic API Proxy endpoint traffic-proxy.example.local See Installing Traffic API Proxy
    API Keys CATALOG_KEY See Installing API Keys service
  4. Make sure that the following system requirements are met (the requirements are given for the minimal amount of replicas):

    • For testing environment:

      Service vCPU RAM Storage
      For Portal service 4 2 GB
      For SPCore service 16 8 GB
      For PostgreSQL storage 12 6 GB 100 GB
      For S3-compatible storage 4 TB*
      For ZooKeeper message queue 4 4 GB
      Total amount: 36 20 GB 4.1 TB
    • For production environment:

      Service vCPU RAM Storage
      For Portal service 4 2 GB
      For SPCore service 16 8 GB
      For PostgreSQL storage 32 64 GB 100 GB
      For S3-compatible storage 4 TB*
      For ZooKeeper message queue 8 16 GB
      Total amount: 60 90 GB 4.1 TB

    * These storage requirements are calculated for the use case of storing huge volume of high-resolution tiled images, for example, satellite imagery. If you do not plan to store such type of data, then storage requirements may be lowered.

    Note:

    Detailed requirements for each service are listed in the System requirements document.

  5. Choose the domain name for the service.

    Example: gis-platform.example.com

Place a PostgreSQL cluster with the domain name gis-platform-postgresql.storage.example.local in the private network. This instruction assumes that the cluster works on the standard port 5432.

Configure the PostgreSQL cluster for usage as a storage:

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

  2. Create a database user that will be used for the service. Set a password for the user.

    create user gisplatform_superuser password 'GISPLATFORM_Db_Owner_Password_1234';
    
  3. Create a database owned by this user.

    create database onpremise_gisplatform owner gisplatform_superuser;
    
  4. Install the PostGIS extension.

    \c onpremise_gisplatform
    
    CREATE EXTENSION postgis WITH SCHEMA public;
    

Place an S3-compatible storage (e.g., Ceph) with the domain name gis-platform-s3.storage.example.local in the private network. This instruction assumes that the storage works on the standard port 80.

Configure the S3-compatible storage:

  1. Create a user that will be used for the service. Remember the credentials for the user.

    Example:

    • Access key: PHEI4AHTHEETHAHXEEGE
    • Secret key: aiw6ahlaeshahngaiJaebie6aeth0aiV2pucuey1
  2. Create a zone group (region) that will be used for the service.

    Example: US

  3. Choose bucket names that will be used for the service.

    Example:

    • Bucket for the main data: spstatic
    • Bucket for the session data: spsession
  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-gis-platform.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000
    
    external_hostname: gis-platform.example.com
    
    spcore:
        admin:
            email: admin@example.com
            password: Oi3ha5eiL9OquooZ
    
        catalog:
            url: https://catalog.example.local
            key: CATALOG_KEY
    
        jwt:
            token_admin: xeep2nahjooGhaa3ke8ahy2moogh7ieB
            token_key: aihu6YaiM7owaequohpheizahvoh4go5
    
        pg:
            host: gis-platform-postgresql.storage.example.local
            port: 5432
            user: gisplatform_superuser
            password: GISPLATFORM_Db_Owner_Password_1234
            dbname: onpremise_gisplatform
    
        replicaCount: 16
    
        resources:
            requests:
                cpu: 800m
                memory: 4096Mi
            limits:
                cpu: 800m
                memory: 4096Mi
    
        s3:
            host: gis-platform-s3.storage.example.local
            access_key: PHEI4AHTHEETHAHXEEGE
            secret_key: aiw6ahlaeshahngaiJaebie6aeth0aiV2pucuey1
            region: US
            bucket: spstatic
            session_bucket: spsession
    
    zookeeper:
        replicaCount: 2
    
        resources:
            requests:
                cpu: 300m
                memory: 1024Mi
            limits:
                cpu: 500m
                memory: 2048Mi
    
    portal:
        replicaCount: 2
    
        max_body_size: 100m
    
        resources:
            requests:
                cpu: 100m
                memory: 512Mi
            limits:
                cpu: 100m
                memory: 512Mi
    
    ingress:
        hosts:
            - host: gis-platform.example.com
    

    Where:

    • dgctlDockerRegistry: your Docker Registry endpoint where On-Premise services' images reside.

    • external_hostname: FQDN of the GIS Platform service. Web interfaces will be available on this FQDN via HTTPS.

    • spcore: settings for the SPCore backend service.

      • admin: administrator's credentials.

        • email: email of the administrator user.
        • password: password for the administrator user.
      • catalog: access settings for the Catalog API service. This service interacts with Geocoder API and Suggest API.

        • url: FQDN of Catalog API endpoint. It must be specified in the http(s)://catalog.example.local form, without trailing slash /. This URL should be accessible from all the pods within your Kubernetes cluster.
        • key: a dedicated service token to access the Search services. See the API Keys service documentation for details.
      • jwt: JSON Web Tokens (JWT) generation settings.

        • token_admin: Token for the administrator user, so they can log in with it. Must be a string of 32 or more random characters.
        • token_key: Token for JWT cookies generation. Must be a string of 32 or more random characters.
      • pg: access settings for the PostgreSQL server.

        • host: hostname or IP address of the PostgreSQL server.
        • port: listening port of the PostgreSQL server.
        • user and password: credentials for accessing the database specified in the dbname setting. The user must be the owner of this database or a superuser.
        • dbname: database name.
      • replicaCount: number of the SPCore service replicas.

      • resources: computational resources settings for service. See the minimal requirements table for the actual information about recommended values.

      • s3: S3 storage settings (for storing GIS Platform tiles data).

        • access_key: S3 access key.
        • secret_key: S3 secret key.
        • host: FQDN of S3-compatible storage endpoint.
        • region: S3 region.
        • bucket: bucket for storing raster images.
        • session_bucket: bucket for storing previews.
    • zookeeper: settings for the ZooKeeper backend service.

      • replicaCount: number of the ZooKeeper service replicas. Value of this setting can vary from 1 to 3.
      • resources: computational resources settings for service. See the minimal requirements table for the actual information about recommended values.
    • portal: settings for the Portal frontend service.

      • replicaCount: number of the Portal service replicas.
      • max_body_size: maximum size of a file that can be uploaded via Portal web UI.
      • resources: computational resources settings for service. See the minimal requirements table for the actual information about recommended values.
    • 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. Do the initial deployment of the GIS Platform service.

    During this operation the following will happen:

    1. The spcore.replicaCount setting value will be forced to 1.
    2. The services will be reset to their initial states.
    3. Necessary data structures will be initialized, databases will be migrated.

    Do the initial deployment with Helm using created values-gis-platform.yaml configuration file.

    helm upgrade --install --version=1.4.5 --atomic --wait-for-jobs --values ./values-gis-platform.yaml gis-platform 2gis-on-premise/gis-platform --set spcore.reset_cluster=true
    

    Then wait for the process to complete. When initial deployment is complete, you will see the similar message in the spcore pod's logs:

    Now listening on: http://[::]:5051
    Application started. Press Ctrl+C to shut down.
    
  3. Do the initial configuration of the GIS Platform service:

    1. Set the environment variables:

      export GIS_PLATFORM_URL=https://gis-platform.example.com  # value of external_hostname
      export GIS_PLATFORM_PASS=Oi3ha5eiL9OquooZ                 # value of spcore.admin.password
      export GIS_PLATFORM_TILES_API=https://tiles.example.local
      export GIS_PLATFORM_TRAFFIC_API=https://traffic-proxy.example.local
      
    2. Run the configuration script:

      helm pull --untar 2gis-on-premise/gis-platform
      cd gis-platform/gis-platform-config
      ./configure.sh
      

      Note:

      Starting with the version 1.1.0, it is possible to specify the -k argument when running the configure.sh script.

      This argument allows skipping the connection security verification when connecting to a server via HTTPS. Any errors that may occur if untrusted SSL certificate (for example, a self-signed one) is used by GIS Platform services will be ignored.

  4. Perform the basic health check of the GIS Platform service:

    1. Open the https://gis-platform.example.com address in a browser (the value of the external_hostname setting).

    2. Log in using the following credentials:

      1. User name: admin.
      2. Password: the value of the spcore.admin.password setting.

    You should be successfully logged into the Web UI.

  5. After the successful log in attempt, do the second phase of the deployment with Helm using created values-gis-platform.yaml configuration file.

    helm upgrade --install --version=1.4.5 --atomic --wait-for-jobs --values ./values-gis-platform.yaml gis-platform 2gis-on-premise/gis-platform
    

    Important note:

    This command differs from the similar command above: it lacks the --set spcore.reset_cluster=true argument, because now the services shouldn't be resetted. Do not use the command from the step 2 (initial deployment).

What's next?