DataSpeeder - Setup Guide

Document 200726

www.dataspeeder.com/support


Summary

This guide describes how to set up DataSpeeder on a Windows 10 computer.

Specifically, we will do the following ...

1.0 Setting up DataSpeeder

1.1 Dependencies

DataSpeeder requires that Java 8 JDK is installed, Tomcat 8 is installed and running, and there is a MySQL database to connect to.

If you need assistance setting up these dependent components, please see the "Dependencies Guide" before proceeding with this document.

1.2 Downloading DataSpeeder

Have you downloaded DataSpeeder and obtained a License?

If you have not downloaded DataSpeeder yet, go to www.dataspeeder.com and click "Download".

You will be provided a link to download the DataSpeeder ZIP file, and you will be emailed a Trial License file "dataspeeder.license".

Download the DataSpeeder ZIP file and extract its contents to a convenient location.

1.3 Create the "DataSpeederDB" database schema in MySQL

We need to create a new "DataSpeederDB" schema in your MySQL database. We will do that with the MySQL Workbench tool we installed in the "Dependencies Guide".

From the Windows Start Menu locate and launch MySQL Workbench.

Double-click on "Local instance MySQL80" to establish the connection.

In the "Connect To MySQL Server" dialog box, enter the password for the root user that you specified during the installation, and click "OK".

When successfully connected you will see the MySQL Workbench application as shown.

Click on the "Schemas" tab to see the database schemas.

A default MySQL installation will only have the "sys" database schema.

On the main menu choose "File > Open SQL Script ..." and select the "create-dataspeeder-db.sql" file that was included in the DataSpeeder ZIP file.

WARNING: When we execute this SQL script, it will delete any existing "DataSpeederDB" schema to install the new one.

In the toolbar, click the "Execute" (Lightning Bolt) button to execute the SQL script.

In the "Output" pane at the bottom, check for confirmation of success by verifying there are no red error mesages (all green checkmarks and some yellow warnings are normal indication of success).

In the "Schemas" pane, click the small "Refresh" button to refresh the tree.

Expand the nodes and notice the "dataspeederdb" schema with Tables, Views, and Stored Procedures.

This confirms that we have created a clean, new, "DataSpeederDB" schema.

You can now quit the MySQL Workbench tool.

1.4 Setup the CATALINA_HOME environment variable

We need to create a CATALINA_HOME environment variable so DataSpeeder will be able to locate the required configuration and license files.

NOTE: Setting up a CATALINA_HOME environment variable is a common practice with Tomcat deployments, so systems running Tomcat may already have this environment variable created.

On the Windows Start Menu, search for "environment" and click the "Edit the system environment variables" launcher.

In the "System Properties" window, on the "Advanced" tab, click the "Environment Variables..." button.

In the "Environment Variables" window, scroll through the "System Variables" list to determine if there is already a "CATALINA_HOME" variable.

If it exists, select it and click the "Edit" button.

If if does not exist, click the "New ..." button.

For "Variable name", enter: CATALINA_HOME

For "Variable value", use the "Browse Directory..." button to locate the home folder of your Tomcat installation; on our machine, this location is: C:\Program Files\Apache Software Foundation\Tomcat 8.5

Click "OK" to save the environment variable.

Click "OK" to close the "Environment Variables" window, and click "OK" to close the "System Properties" window.

We have completed the steps to create the CATALINA_HOME environment variable.

1.5 Copy and edit the "dataspeeder.properties" file

We need to put the "dataspeeder.properties" file in the correct place, and edit it so it contains the correct database connection properties.

Locate the "dataspeeder.properties" file which is included in the downloaded DataSpeeder ZIP file.

Copy the "dataspeeder.properties" file to your Tomcat configuration folder: CATALINA_HOME\conf

Note: On our machine this location is: C:\Program Files\Apache Software Foundation\Tomcat 8.5\conf

Edit the "dataspeeder.properties" file and specify the correct values for connecting to the DataSpeederDB database schema.

The following details each property:

1.5.1 jdbcDriver

This indentifies the full class name of the JDBC Driver class file that DataSpeeder uses to connect to the MySQL database.

The default value is: jdbcDriver=com.mysql.cj.jdbc.Driver

1.5.2 jdbcDriver

This identifies the name of the MySQL database schema that DataSpeeder will connect to.

The default value is: jdbcSchema=DataSpeederDB

1.5.3 jdbcUrl

This identifies the full JDBC URL that DataSpeeder will use to establish the database connection.

This URL can vary greatly depending on your system needs. It contains the server name, optionally the port number, the database schema, and other properties. The default value assumes MySQL is running on the same "localhost" as the Tomcat server.

The default value is is: jdbcUrl=jdbc:mysql://localhost/DataSpeederDB?allowPublicKeyRetrieval=true&useSSL=false&useUnicode=true&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC

1.5.4 jdbcUsername

This identifies the username DataSpeeder will use to connect to the database.

The default value is: jdbcUsername=root

1.5.5 jdbcPassword

This indentifies the password DataSpeeder will use to connect to the database.

The default value is: jdbcPassword=password

1.6 Copy the "dataspeeder.license" file

We need to put the "dataspeeder.license" file in the correct place so DataSpeeder can run properly in a licensed state.

When you downloaded DataSpeeder, a trial license file "dataspeeder.license" was emailed to you. If you did not receive this file, contact DataSpeeder Support and we will get you a free trial license file.

Copy the "dataspeeder.license" file to your Tomcat configuration folder: CATALINA_HOME\conf

Note: On our machine this location is: C:\Program Files\Apache Software Foundation\Tomcat 8.5\conf

1.7 Copy the "dataspeeder.war" file

We need to put the "dataspeeder.war" file in the correct place so the Tomcat server will run the DataSpeeder web application.

Locate the "dataspeeder.war" file which was in the DataSpeeder ZIP file you downloaded.

Copy the "dataspeeder.war" file to your Tomcat webapps folder: CATALINA_HOME\webapps

Note: On our machine this location is: C:\Program Files\Apache Software Foundation\Tomcat 8.5\webapps

1.8 Start DataSpeeder and confirm it is running

1.8.1 Verify Tomcat Is Running

First, we'll confirm that Tomcat is running

Open your prefered web browser and visit:

http://localhost:8080/

You should see the standard Tomcat web page, this confirms that Tomcat is running.

Note: If you don't see the Tomcat web page, you need to ensure Tomcat is installed and running correctly; please see section "2.3.1 Verifying Tomcat is running as a Windows Service" in the Dependencies Guide

1.8.2 Verify DataSpeeder Is Running

After confirming that Tomcat is running, next we'll confirm that DataSpeeder is running.

Open your prefered web browser and visit:

http://localhost:8080/dataspeeder

You should see the DataSpeeder web page and the "Demo Movie Application".

Click on the "Demo Movie Application", and you should see the demo categories of "Actors", "Directors", and "Movies".

This confirms that DataSpeeder is installed and running correctly!

CONGRATULATIONS!

2.0 NEXT STEPS

To see video demos of DataSpeeder in use, for end-users and administrators, please visit the DataSpeeder Support web page to see the list of demo videos and tutorials for creating and using DataSpeeder applications.