2.2 Downloading and Installing Spatial Studio

Spatial Studio must be downloaded and installed before anyone can use it to perform interesting work on spatial data.

See https://www.oracle.com/database/technologies/spatial-studio/get-started.html for more information on downloading and installing Spatial Studio.

The different types of installation options are described in the following sections:

• Installing and Configuring the Spatial Studio Quick Start
  Quick Start is an easy method for getting started, and is well suited for personal and development use.
• Installing Spatial Studio on Oracle WebLogic Server
  Spatial Studio can be deployed to a WebLogic Server domain, the recommended approach if multiple end users will access the same Spatial Studio application.
• Installing Spatial Studio on Apache Tomcat
  Starting with Oracle Spatial Studio patch release 23.1.1, you can deploy and run the Spatial Studio web application on Apache Tomcat version 9.
• Installing Spatial Studio from Oracle Cloud Marketplace
  You can provision Spatial Studio to Oracle Cloud from Oracle Cloud Marketplace.

2.2.1 Installing and Configuring the Spatial Studio Quick Start

Quick Start is an easy method for getting started, and is well suited for personal and development use.

The Quick Start is packaged in a single zip that contains everything you need to start using Spatial Studio, except for Java (64-bit, update 181 or later) and your own database schemas.

Before installing the Quick Start, ensure that you meet the following prerequisite requirements:

• You must have Java installed on your system and the JAVA_HOME environment variable is pointing to the full JDK installation of Java SE Development Kit. Note that the Quick start installation requires Java 8 (64-bit, update 181 or later) or JDK 11 (64-bit).
• Ports 8080 and 4040 on your system are not being used by any other (web) applications. Port 8080 is used with the http:// protocol, while port 4040 is for the https:// protocol. Although you can direct Spatial Studio to use different ports, 8080 and 4040 are the default.

  Note that by default Spatial Studio allows access using https only.

  If you prefer to enable http access, then perform the following steps:

  • Edit the conf/server.json file in the Oracle_Spatial_Studio directory and update the httpEnabled property to true.
  • Edit the sgtech_config.json file and update the https_only property to false (see Changing the Configuration Using the sgtech_config.json File).
  • Restart the Spatial Studio application.
  • Verify that the http port is opened in the host OS firewall.

You can perform the following steps to install and configure the Spatial Studio Quick Start:

1. Download the Quick Start zip archive OracleSpatialStudio_qs.zip.
2. Unzip (extract) the OracleSpatialStudio_qs.zip file.
   This results in the Oracle_Spatial_Studio directory.
3. Navigate to the Oracle_Spatial_Studio directory from a command window (Windows) or terminal (Linux or Mac).
   This directory contains several .bat or .sh files.
4. Start the Spatial Studio application by running start.sh or start.bat.
   On Linux or Mac you may need to ensure that the .sh files are executable by first running the command: chmod u+x *.sh
5. Launch Spatial Studio in your browser using the https://localhost:4040/spatialstudio URL and log into the web application.

   You can login using the default admin user login credentials - admin/welcome1. However, it is strongly recommended that you immediately change the password. See the README file in the Quick Start on how to change the (encrypted) password for the admin user.

   Also, note the following:

   • The default port is 4040. However, you can change the port by editing the conf/server.json file in the Oracle_Spatial_Studio directory. You must restart the application after you make any change to this file. (The same applies if you change the HTTP port value from the default 8080.)
   • The Quick Start provides the following predefined web user login accounts:
     • admin: Administrator user account
     • daustin and bruce: Two regular user accounts

     These predefined users and their login passwords are defined in the conf/jetty-realm.properties configuration file. The passwords are all stored in encrypted form. Before you start the application for the first time, it is strongly recommended that you change the password of the default administrator user admin. See the README file in the Quick Start on how to change the (encrypted) password for the admin user and other regular Spatial Studio users.

     Also, all other passwords, such as those used to log into the Spatial Studio metadata schema or for any user-created connections to database schemas, are strongly encrypted everywhere.

   • If you wish to configure the Spatial Studio server to use a CA-signed certificate, then see Using a CA-Signed SSL Certificate in the Quick Start Installation for more information.
   • The README file also contains information about starting and stopping the web application. To stop the application, the preferred approach is to start a second terminal or command window, then go to the same Oracle_Spatial_Studio folder and run the stop.bat or stop.sh script.

   If your metadata connection detail is already stored in the sgtech_config.json file, then see Using Oracle Spatial Studio to get started with Spatial Studio.

   Otherwise, proceed to step-6.

6. Optionally, select the metadata connection type.

   Perform this step only if you are starting a new instance of Spatial Studio on your system. This step is required to set the metadata repository in the database where Spatial Studio stores and manages the metadata for all its objects (such as the connections, dataset, and so on). See Setting Up the Spatial Studio Metadata Schema for more information on the metadata schema and the privileges required for the schema user.

   Figure 2-1 Metadata Connection Type

   
   

   
   Description of "Figure 2-1 Metadata Connection Type"

   
   

   Perform the following steps depending on your choice of Metadata connection type:

   • Oracle Database

     The Specify metadata schema details dialog opens as shown:

     Figure 2-2 Metadata Schema Connection to Oracle Database

     
     

     
     Description of "Figure 2-2 Metadata Schema Connection to Oracle Database "

     
     
     1. Select the database Connection.

        Supported values are:

        • Service
        • SID
     2. Enter the Service/SID value depending on the connection value selected in the earlier step.
     3. Enter the database User name and the Password for the user.
     4. Enter the Host and Port details.
     5. Click OK.
   • Oracle Autonomous Database

     The Upload wallet dialog opens.

     1. Drag and drop the wallet file (for your Autonomous Database instance) or click to upload the wallet from your system.
     2. Click OK.

        The Specify metadata schema details dialog opens as shown:

        Figure 2-3 Metadata Schema Connection to Autonomous Database

        
        

        
        Description of "Figure 2-3 Metadata Schema Connection to Autonomous Database "

        
        
     3. Enter the Autonomous database User name and the Password for the user.
     4. Select the appropriate Service from the drop-down list.
     5. Optionally, enter the Proxy Host and Proxy Port details.
     6. Click OK.

   The provided metadata schema details get stored in the sgtech_config.json file. The Getting Started page opens in the web application. See Using Oracle Spatial Studio to get started with Spatial Studio.

2.2.2 Installing Spatial Studio on Oracle WebLogic Server

Spatial Studio can be deployed to a WebLogic Server domain, the recommended approach if multiple end users will access the same Spatial Studio application.

Note:

A WebLogic Server license is required in order to host Spatial Studio in WebLogic Server for multiple end users.

The general approach for deploying Spatial Studio to WebLogic Server is no different from deploying any other Java EE EAR application. The easiest way to do so is by using the WebLogic Server’s Admin console with the following steps. Note that in all or most steps you can accept the default values provided by the WLS Installation Application Wizard.

1. Download the Studio EAR archive from Oracle Technical Resources or eDelivery, and save it to your local system.
2. Log into the target WLS domain’s Admin console.
3. Click the Deployments link on the left side.
4. Click Install button under the Deployments section, as shown in the following figure (note that the exact contents may be different for your instance of WLS).

   Figure 2-4 WLS Admin Console for Deploying Spatial Studio

   
   Description of "Figure 2-4 WLS Admin Console for Deploying Spatial Studio"
5. On the next page, select the Spatial Studio EAR file downloaded previously, and install it as an application (not as a library).
6. Click through the remaining steps, including selecting the proper target server. You should accept the default options in all cases unless you know exactly what you are doing. Finally, click Save to complete the deployment.
7. If your WLS runs in production mode, you may need to activate the changes to ensure the deployment is activated.
8. Make sure the newly deployed Spatial Studio application is marked Active; otherwise, you may need to explicitly start it from the WLS administrative console.
9. Access the Studio application using your managed server’s URL with the /spatialstudio context root. For example: http://mycompany.com:7002/spatialstudio

• Preventing a Spatial Studio Admin User from General WLS Administration
  

2.2.2.1 Preventing a Spatial Studio Admin User from General WLS Administration

If you want to prevent a Spatial Studio administrative user from performing other general WebLogic Server administrative operations, follow the instructions in this topic.

The Spatial Studio application by default allows all WebLogic managed admin users (those who are in WebLogic’s Administrators group) to log into the Spatial Studio application and assume Admin role inside the Spatial Studio application as well.

However, in some scenarios, your organization may not want to provide the WebLogic Server admin account information to the user(s) that will be administering only the Spatial Studio application. In such cases, the WLS system administrator can create a new WLS group with the id value of “SGTech_SystemAdmin” in the default WLS security realm. Then, either create a new user or assign an existing non-WLS-admin user to this group. From then on, this user will assume the admin role of the Spatial Studio whenever logged in, but will not be able to administrate the WLS server in general.

Also, note the following:

• All WLS managed users will be able to log into Spatial Studio by default, but they will be limited to accessing only their own Spatial Studio objects such as connections, datasets, and projects.
• Administrative users of Spatial Studio will have full access to every Spatial Studio object created by everyone.
• When using WebLogic's default embedded LDAP security realm as identity provider, if the user name and the assigned application role name differ only by casing (for example, admin and Admin respectively), then it is recommended that you adjust both the names to lowercase. This is to avoid case sensitivity issues in Spatial Studio between user, group, and security policies.

2.2.3 Installing Spatial Studio on Apache Tomcat

Starting with Oracle Spatial Studio patch release 23.1.1, you can deploy and run the Spatial Studio web application on Apache Tomcat version 9.

The following are the general steps for deploying and running Spatial Studio on Tomcat:

1. Download and install the latest Apache Tomcat version 9.

   See the Apache Tomcat Documentation for setting up Tomcat.

2. Unzip the Tomcat zip file and configure it as required, such as removing all default web applications found in the <TOMCAT_HOME>/webapps directory.
3. Download the Spatial Studio Tomcat specific WAR archive from Oracle Software Delivery Cloud.
4. Copy the downloaded WAR archive into the <TOMCAT_HOME>/webapps/ directory.
5. Ensure to rename the WAR file to just spatialstudio.war.

   Note that there is no version or build string in the file name. See About the Spatial Studio WAR Archive for Tomcat for more information.

6. Configure Tomcat users and roles.

   Ensure to configure the ADMIN user for Spatial Studio. See Configuring Tomcat Users for Spatial Studio for more information.

7. Start the Tomcat server using the startup script in the <TOMCAT_HOME>/bin directory.

   Note that you may need to wait a few seconds for Tomcat and Spatial Studio to fully initialize before attempting to access the Spatial Studio web application.

8. Launch Spatial Studio in your browser by opening the URL - https://localhost:8443/spatialstudio.

   Note that in the preceding URL, port 8443 is the default https port for Apache Tomcat. If you wish to enable http access (default port 8080), then see Allow HTTPS-ONLY Access for more information.

   You can then log in using one of the users you defined on step-6.

   Note that the Spatial Studio access URL uses the default host name and port. If you change the default Tomcat network and port configurations, then you need to adjust the URL accordingly.

   If for some reason you cannot access the URL, then you can always check the following log files:

   • Tomcat’s server logs in the <TOMCAT_HOME>/logs directory.
   • Spatial Studio’s own log files in the <USER_HOME>/.sgtech/logs directory, where <USER_HOME> is the home directory of the operating system user.

• About the Spatial Studio WAR Archive for Tomcat
  You must download the spatialstudio_tomcat.war archive for running Spatial Studio on Tomcat.
• Configuring Tomcat Users for Spatial Studio
  In order to run Spatial Studio on Tomcat, you need to configure at least one Tomcat user who can act as the administrator for Spatial Studio.

2.2.3.1 About the Spatial Studio WAR Archive for Tomcat

You must download the spatialstudio_tomcat.war archive for running Spatial Studio on Tomcat.

This archive file bundles all the required dependencies that enables it to run on a freshly downloaded and installed Tomcat instance.

It is important to note the following:

• You must rename the spatialstudio_tomcat.war file to spatialstudio.war when it is placed in the Tomcat’s webapps directory. This is because Tomcat uses the file name as the web application’s context root, and for Spatial Studio it is typically /spatialstudio.
• If you have an existing Tomcat installation with other web applications running on it or different versions of the dependency libraries are already installed, then there might be issues running Spatial Studio due to library and version conflicts. In such cases, you can raise a service request with My Oracle Support in order to have the issues resolved.

2.2.3.2 Configuring Tomcat Users for Spatial Studio

In order to run Spatial Studio on Tomcat, you need to configure at least one Tomcat user who can act as the administrator for Spatial Studio.

Note that when you access the Spatial Studio web application, the username and password that you enter in the login page are passed to Tomcat for authentication. Once the user is authenticated, Spatial Studio inspects the result principal. If the principal has a role named SGTech_SystemAdmin, then the logged in user will be considered an admin user for Spatial Studio.

If your Tomcat instance has already been configured to provide authentication using an external identity provider, then ensure one or some of the users provided by the external identity provider are assigned the SGTech_SystemAdmin role so they can administrate Spatial Studio.

If your Tomcat installation relies on its simple built-in user management mechanism, then you will likely be adding the role and user to tomcat-user.xml configuration file, which is found in the <TOMCAT_HOME>/conf directory.

The following simple example defines two users and two roles, with one being SGTech_SystemAdmin in tomcat-user.xml configuration file:

<role rolename=”role1”/>
<role rolename="SGTech_SystemAdmin"/>
<user username="admin" password="Welcome1" roles="manager-gui, manager-script, SGTech_SystemAdmin"/>
<user username="scott" password="Welcome1" role="role1"/>

Once the roles are defined, then you can log into Spatial Studio using either the user name scott or admin. Since the admin user has the SGTech_SystemAdmin role, the user will be able to administrate Spatial Studio once logged in, whereas scott user will just be a regular Spatial Studio user.

2.2.4 Installing Spatial Studio from Oracle Cloud Marketplace

You can provision Spatial Studio to Oracle Cloud from Oracle Cloud Marketplace.

See Deploy Spatial Studio from Cloud Marketplace for more information on deploying Spatial Studio from Cloud Marketplace.