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.

The Quick Start is packaged in a single zip that contains everything you need to start using Spatial Studio, except for Java (JDK 11 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 JDK 11 (64-bit) or later.
• 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.properties 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.properties 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 jetty-home/security/jetty-realm-mt.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 AI 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 AI Database

        
        

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

        
        
     3. Enter the Autonomous AI 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.

Installing Spatial Studio on Oracle WebLogic Server

Spatial Studio can be deployed to an Oracle WebLogic Server 15c (15.x) domain. This is the recommended approach when 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.
• For WebLogic Server 15c, use the WebLogic Remote Console desktop application to deploy and manage Spatial Studio. The built-in WebLogic Server Administration Console at host:7001/console is no longer used for WebLogic Server 15c.

The general approach for deploying Spatial Studio to WebLogic Server is no different from deploying any other Java EE EAR application. However, for a WebLogic Server 15c instance, deployment and life cycle operations are performed from WebLogic Remote Console.

1. Download and install WebLogic Remote Console, if it is not already installed.
2. Download the Studio EAR archive from Oracle Technical Resources or eDelivery, and save it to your local system.
3. Create a connection to the target WebLogic Server 15c domain in WebLogic Remote Console.

   If you do not already have a target domain, install WebLogic Server 15c, create a domain such as base_domain, and then connect to it from WebLogic Remote Console.

   Figure 2-4 Creating a WebLogic Server Connection

   
   

   
   Description of "Figure 2-4 Creating a WebLogic Server Connection"

   
   
4. Create an application deployment using the Spatial Studio EAR file.
   1. Select the connection for the target domain in WebLogic Remote Console.
   2. Go to Edit Tree > Deployments > App Deployments.

      Figure 2-5 Navigating to App Deployments

      
      

      
      Description of "Figure 2-5 Navigating to App Deployments"

      
      
   3. Select or upload the EAR file, choose the appropriate target server, and complete the deployment form as shown in the following figure.

      Figure 2-6 Creating a Spatial Studio Deployment

      
      

      
      Description of "Figure 2-6 Creating a Spatial Studio Deployment"

      
      
   4. Click Create.

      The deployment gets added as an item in the shopping cart displayed on the top right of the page.

   5. Open the shopping cart and click Commit Changes to deploy the Spatial Studio application.

      If On Deployment is set to Start Application, as shown in the preceding figure, then WebLogic Server automatically starts Spatial Studio after the deployment is complete. Otherwise, follow step-5 to manually start the application.

5. Perform this step only if you need to manually start Spatial Studio.
   1. Navigate to Monitoring Tree > Deployments > Application Deployment.
   2. Select the deployed Spatial Studio application and click Start.
6. Access Spatial Studio using the WebLogic Server's URL followed by the /spatialstudio context path, such as http://localhost:7001/spatialstudio.

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.

Installing Spatial Studio on Apache Tomcat

You can deploy and run the Spatial Studio web application on Apache Tomcat version 11.x.

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

1. Download and install the latest Apache Tomcat version 11.x release.

   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.

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.

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.

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.