Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


  >  Docs Center  >  Geospatial Services Framework  >  GSF Tutorial: Getting Started

Geospatial Services Framework

GSF Tutorial: Getting Started

GSF - Tutorial - Getting Started

Starting the Server


Option #1: As a Command Line Application

  • Start a terminal and navigate to the installation directory.
  • Issue the following to start the server:
    node server.js
  • To stop the server issue Ctrl+C from the terminal where the server is running.
  • Issue the following to learn the other options available at server startup:
    node server.js --help

Option #2: As a Service

  • Start a terminal and navigate to the installation directory.
  • Issue the following to add the service:
      node service add
  • Issue the following to remove the service:
      node service remove
  • Additionally, you may start and stop the service using the command line with the following commands:
      node service start
      node service stop

Configuring the Server


The server comes with a default configuration file (GSFxx/config.json) which can be updated or replaced with a custom configuration file. All of the available configuration options are defined in gsf-server-core. Restart the server any time this file is changed so it reflects the new configuration.

Modules can accept additional optional configuration values in the same file mentioned above.

GSF comes with a command line utility for updating the config.json file. For example, to change the location of the workspace folder, start a command prompt in the GSFxx directory and execute the following command:

node updateConfig.js config.json --set workspaceManager.root=new/folder/location

This will set the root property of the workspaceManager configuration object to new/folder/location. The updateConfig.js script will automatically back up the original config.json file for you.

Alternatively, you may also manually edit the config.json file. Below is an example of changing the location of the workspace folder:

{
  ...,
  "workspaceManager":{
    "type":"gsf-basic-workspace-manager",
    "root":"new/folder/location"
  }
  ...,
}

Restart the server any time this file is changed so it reflects the new configuration.

More information on module configuration may be acquired by reading the help documentation for each module.

Configuring Multiple Workers

Simultaneous processes may be run on a single machine, or node. This method of forking processes is useful for maximizing available resources.

Option #1: Configuration File

Changing the number of workers on a single machine is simple.

To set the number of workers in the configuration file from a command line, start a command prompt in the GSFxx directory and execute the following command:

node updateConfig.js config.json --set workers=8

You may also manually update the number of workers by editing the config.json file and setting the "workers" JSON key to the desired number of workers. It is recommended that you back up your config file before making any changes manually.

{
  ...,
  "workers": 8
}

Restart the server any time this file is changed so it reflects the new configuration.

Option #2: Command Line Argument

The number of workers may also be specified using a command line argument when starting the server. This will override the "workers" value in the configuration file for this server instance.

node server.js -w 8

To take advantage of the processing capabilities of multiple nodes (machines), see Clustering.

Variable Substitution

When configuring the server, it is possible to substitute specific variables for environment variables or other system properties. This allows you to reference an environment variable by name and have it replaced with the value of that variable upon server startup.

Environment Variables

Environment variables may be referenced using ${env.VAR_NAME} notation where VAR_NAME is the name of the environment variable. To demonstrate, the configuration below uses an environment variable for the job manager's redisHost configuration.

"jobManager": {
    "type": "gsf-kue-job-manager",
    "redisPort": 6379,
    "redisHost": "${env.GSF_REDIS_HOST}"
  },

This will result in the redisHost configuration getting set to the value of the GSF_REDIS_HOST environment variable when the server starts up.

System Properties

By using ${os.cpus} as a configuration value, you can tell the server to use the number of logical cpu cores that are available on the machine when the server starts up.

{
    ...
    "workers": "${os.cpus}",
    ...
}

For more information on variable substitution, please see the gsf-config-loader.

Submit a Job


To submit a job, create a file called submitJob.js in the GSFxx directory. Add the following contents to the file:

var GSF = require('gsf-js-client-sdk/dist/GSF-node.js');
// GSF Server Information
var serverAddress = 'localhost';
var serverPort = 9191;
// Create a Server object.
var server = GSF.server({address: serverAddress, port: serverPort});
// Create a Task object.
var task = server.service('ENVI').task('SpectralIndex');
// Form input parameters to the task.
var inputParameters = {
  INPUT_RASTER: {
    url: 'http://' + serverAddress + ':' + serverPort + '/ese/data/qb_boulder_msi', // This is a reference to data that ships with the server.
    factory: 'URLRaster'
  },
  INDEX: 'Normalized Difference Vegetation Index'
};
// Submit the task and wait for the results.
task.submitAndWait(inputParameters).then((results) => {
  console.log('Job complete!  Results: ', results);
  process.exit(0);
}).catch((err) => {
  console.log('An error occurred: ', err);
  process.exit(1);
});

To run this JavaScript code, perform the following steps:

  • Start a terminal and navigate to the folder that contains submitJob.js
  • Issue the following command to install the SDK from npm:
    • npm install gsf-js-client-sdk
    • Note: This will download the SDK from npmjs.org. Offline users can download the SDK that ships with GSF via the gsf-sdk-request-handler: http://mygsfserver:9191/sdk/js/GSF-node.js.
  • Next, issue the following command to run the script:
    • node submitJob.js
  • After the job completes, the results will print to the console.

This example assumes use of the default configuration, specifically the ese-request-handler, and that ENVI is installed.

For information on setting up a custom endpoint that serves up HTML and runs a job, see Custom Request Handler tutorial.

Enabling HTTPS support


HTTPS allows GSF to encrypt all communications to and from clients accessing the server. It is recommended when following security best practices for all deployed systems.

To turn HTTPS support on, add it to the configuration file.

{
  "port": 9191,
  "https": {
    "key": "key.pem",
    "cert": "cert.pem"
  },
  ...
}

The key and certificate should be generated and signed by your organization. However, a self-signed certificate can also be used.

WARNING: Web browsers and other command line clients will warn you about self-signed certificates and you will have to bypass their security features to use a self-signed certificate.

To generate a self-signed certificate, use openssl:

openssl genrsa -out key.pem
openssl req -new -key key.pem -out csr.pem
openssl x509 -req -days 9999 -in csr.pem -signkey key.pem -out cert.pem

Copy the key.pem and cert.pem files to the GSF installation folder and restart the server.



© 2018 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us