There are times when having multiple Spatial Studio deployments, each pointing to a different repository, can be very helpful. You may want to manage different customer environments, have multiple versions of Spatial Studio running side-by-side, or split production and test environments.

We can create multiple Spatial Studio deployments by combining two hidden gems in Spatial Studio:

  • oracle.sgtech.config JVM property
  • work_dir property from the sgtech_config.json file

Let’s review what each one does.

oracle.sgtech.config

This optional property is passed as a parameter to the JVM. It defines a custom location path for the Spatial Studio configuration file. If the file does not yet exist, it will be automatically generated by Spatial Studio after startup, along with its folder-tree structure.

  • The path can contain environment variables such as ~ or %UserProfile%, for example ~/spatialstudio/workdir/sgtech_config_prod.json
  • If not specified, it defaults to ~/.sgtech/sgtech_config.json

work_dir

This optional property is located inside the specified configuration file. It defines the relative or absolute path where the working directory is located.

  • For example, you might set it to /protected/spatialstudio/workdir/ or ../../studio_wdir
  • If set to a relative path, it is resolved using the containing path of the configuration file as base.
    • For instance, if the configuration file path is located at /spatialstudio/securefiles/sgtech_config.json and work_dir is defined as relative path ../myworkdir, then the working directory will be resolved to /spatialstudio/myworkdir/
  • If the work_dir is set to an absolute path, then it’s used as is regardless of the location of the configuration file.
  • If not specified, the work_dir defaults to the containing path of the configuration file, typically ~/.sgtech/

Preparing Deployments

In this example, we will use the Spatial Studio Quick Start. For WebLogic and other JEE servers, please refer to their manuals on how to pass JVM parameters to a WAR/EAR deployment.

Let’s say we want a single server running three deployments, each pointing to a different database repository, as shown below:

multiple-envs-diagram

As you can see, users can access a particular deployment via specific URL. Here are the steps:

  1. Download Spatial Studio Quick Start into the deployment server. You can download a single version or multiple versions.
  2. Extract the ZIP files using a unique folder name for each deployment, such as:



    Each folder should look like the following:
  3. For the SpatialStudio_QS_20_1 folder, open conf/server.json in edit mode.
    1. Find the serverConfig property, and identify httpsPort and jvmArgs sub-properties.
    2. Assign a value from 1024 through 65535 to httpsPort property, such that each value is unique for each deployment folder.
      1. For example, we will set it to:
        "httpsPort": 4201
      2. If httpEnabled is set to true, then you must also make sure httpPort property is set to a unique port number across all deployment folders.
    3. Under the jvmArgs array property, add the oracle.sgtech.config entry, along with the path location for the configuration file.
      1. We can even include the working directory as part of the file path, for instance:
        -Doracle.sgtech.config=/home/spatialserver01/SpatialStudio_QS_20_1/workdir/sgtech_config.json
      2. Note that custom JVM arguments must be prefixed with -D
      3. You can point to a preexistent file. Otherwise, Spatial Studio will create it automatically upon startup.
    4. The file should resemble this example:

      Example 1. /home/spatialserver01/SpatialStudio_QS_20_1/conf/server.json 
      {
...
    "serverConfig": {
        "host": "0.0.0.0",
        "httpPort": 8080,
        "httpsEnabled": true,
        "httpEnabled": false,
        "httpsPort": 4201,
        "sslKeyStorePath": "conf/keystore",
        "sslKeyStorePassword": "Q29tZSBvbiEgeW91IHdlcmUgbm90IHRoaW5raW5nIHdlIHdvdWxkIHVzZSBhIHJlYWwgcGFzc3dvcmQgaGVyZSwgcmlnaHQ/",
        "sslKeyManagerPassword": "UmVhbGx5PyBBcmUgeW91IHN0aWxsIHRyeWluZyB0byBzZWUgd2hhdCB5b3UgY291bGQgZmluZCBoZXJlPw==",
        "realm": "myrealm",
        "realmConfigFile": "conf/jetty-realm.properties",
        "jvmArgs": [
            "-Xms256M",
            "-Xmx1500M",
            "-Djava.io.tmpdir=.",
            "-Djava.awt.headless=true",
            "-Duse.test.repo=false",
            "-Doracle.sgtech.feplugin.rootfolder=.",
            "-Doracle.sgtech.fileresources=false",
            "-Doracle.sgtech.config=/home/spatialserver01/SpatialStudio_QS_20_1/workdir/sgtech_config.json"
        ]
    },
...
}
    5. Save the changes and repeat similar steps on the other deployment folders. Make sure the oracle.sgtech.config and httpsPort properties have unique values.
  4. Because we set the configuration file path to /home/spatialserver01/SpatialStudio_QS_20_1/workdir/sgtech_config.json, the working directory will default to /home/spatialserver01/SpatialStudio_QS_20_1/workdir/, which makes our deployment ready to use.
    1. You can still manually override the working directory path by setting the work_dir property value to a different location.
    2. To do this, you must first stop Spatial Studio, then open the configuration file in edit mode and set the work_dir property value, as shown in this example:

      Example 2. /home/spatialserver01/SpatialStudio_QS_20_1/workdir/sgtech_config.json 
      {
  ...
  "work_dir" : "/mnt/fastdrive/spatial_server_01/wdir_QS_20_1"
  ...
}
      Keep in mind that the working directory must be unique for each deployment.

Running Deployments

Now that each deployment is ready, it’s time to run them.

  1. Open a command-line console and go to one of the deployment folders, such as cd /home/spatialserver01/SpatialStudio_QS_20_1
  2. Run Spatial Studio by executing start.sh (Linux) or start.cmd (Windows).
  3. Verify Spatial Studio is running correctly:
    1. Using your browser, open Spatial Studio’s URL, for instance https://spatialserver01:4201/spatialstudio
      1. Login to Spatial Studio using an admin account.
      2. If prompted, enter the database repository details to connect.
      3. Check the home page to see if it shows all expected data.
    2. Ensure the working directory was created and that it’s not empty.
      1. For example, execute ls /home/spatialserver01/SpatialStudio_QS_20_1/workdir (Linux) or dir c:\home\spatialserver01\SpatialStudio_QS_20_1\workdir (Windows) and check that some files are listed.
  4. Repeat the same steps for all other deployments.
    1. If you get an error when starting Spatial Studio, check that the httpsPort and oracle.sgtech.config properties are properly set in conf/server.json. If you explicitly set the work_dir property in the configuration file, verify the path is valid.
  5. All three deployments should now be running independently from each another.
    1. You can decide whether you want to run them all concurrently, or whether you want to manually start/stop instances on-demand, based on business needs or server capacity.