1

Scoreboard 2.5 Installation Guide

For Apache Tomcat 7.0

On Windows 2003/2008 Server, 64-bit

Updated April 23, 2013

2

Scoreboard and Connect By Spider Strategies

Minimum Server Requirements

The following minimum server requirements are current as of April 8, 2013.

CPU:

Quad Core Processor (or better). Scoreboard and Connect have been designed to utilize

four CPU cores, no more and no less. A dual core CPU is insufficient and will introduce

performance degradation.

Memory:

4 GB of RAM minimum. More is always better.

Disk Space:

30 GB of Free Disk Space, not accounting for database. More is always better.

Operating System: Windows OS: Windows 2003 or later. The operating system MUST be 64-bit. On 32-

bit systems there is an OS-imposed JVM memory limit that prevents Apache Tomcat

from allocating more than 1.3 GB of RAM to Java – too low for Scoreboard. On 64-bit

systems, there is no such limit.

Java Web Application Server:

Apache Tomcat 6.0 and 7.0 are supported.

Databases Supported:

- MySQL 5.0.4(+), 5.1 and 5.5

- SQL Server 2005/2008

3

Scoreboard and Connect By Spider Strategies

Installing Java and Tomcat

Required Programs for this Installation:

1. Java SE 6 Latest Update, Download JRE; Windows x64

URL: http://www.oracle.com/technetwork/java/javase/downloads/

2. Apache Tomcat 7.0.x (latest release) – Binary Distribution, Core, 32-bit/64-bit

Windows Service Installer

URL: http://tomcat.apache.org/download-70.cgi

Steps:

1. Download the JRE 6 installation executable from the above listed URL.

2. Install the JRE 6.

3. Download the Apache Tomcat 7.0.x (latest release) executable from the above

listed URL.

4. Install Apache Tomcat 7.0, taking into account the following steps listed below.

5. Tomcat Installation: On the “Choose Components” screen, select the “Custom”

install type. Under “Tomcat”, select “Core” and “Service Startup”, but not

“Native”. Select “Start Menu Items”. Unselect “Documentation”, “Manager”,

“Host Manager”, and “Examples”.

6. Tomcat Installation: Change the HTTP/1.1 Connector port to 80. (The default

installation port is 8080).

7. Tomcat Installation: If you have more than one JRE installed, please select the

JRE 6 version that you just installed. (Ex: C:\Program Files\Java\jre6 )

8. Tomcat Installation: The default installation path for Apache Tomcat is

“C:\Program Files\Apache Software Foundation\Tomcat 7.0” but you can change

this. We will simply refer to the installation location as %TOMCAT_HOME% in

our communications with you.

9. Tomcat Installation: Select “Run Tomcat” and click “Finish”.

4

10. After Tomcat is installed, set the Apache Tomcat service to start automatically.

Go to: Start -> Settings -> Control Panel -> Administrative Tools -> Component

Services (or just “Services”). Click on “Services”. Right-click on the “Apache

Tomcat” service, set the startup type to “Automatic”, and click OK.

11. Start the Apache Tomcat service, if it is not already running.

When the installer has finished, go to http://localhost/. You should see:

12. Launch “Apache Tomcat Properties” to set critical configurations. Go to Start -> All

Programs -> Apache Tomcat 7.0 -> Configure Tomcat. (Note that on some servers, you

must instead right-click on an Apache Tomcat system tray icon in the lower-right corner

of your screen. Or, launch manually at %TOMCAT_HOME%\bin\tomcat7w.exe).

12a. On the “Java” tab set the “Maximum Memory Pool” value, using a value of 2250

MB or greater. This value should not exceed 75% of the server RAM – especially if you

are running MySQL on the same server. Leave the “Initial Memory Pool” value empty.

Click “Apply” to save the value.

12b. On the “Java” tab, add a configuration to increase the PermGen memory:

In the large "Java Options" box, scroll down to the bottom and add the

following two lines of text on new lines: -XX:MaxPermSize=256m

-Dorg.apache.el.parser.SKIP_IDENTIFIER_CHECK=true

Click “Apply” to save the value.

12c. On this same “Java” tab, if desired, you can add a setting to change the Scoreboard

installation location from the default (C:\Spider_Home). As an example, if you wish to

install to the D drive instead, enter the following text on a new line: -Dspider.home=D:\Spider_Home

Click “Apply” to save the value.

5

13. Edit the %TOMCAT_HOME%\conf\server.xml file in “Notepad”. Locate the “non-

SSL HTTP/1.1 Connector” and inside the associated opening “<Connector … >” tag add

(or modify) these attributes (and then save and close): maxThreads="450"

enableLookups="true"

Example:

14. Edit the %TOMCAT_HOME%\conf\context.xml file in “Notepad”. Locate the

opening <Context> tag and change it to this: <Context useHttpOnly="false">

(and then save the file and close).

15. Stop the “Apache Tomcat” Windows service. (These Tomcat configurations will not

take effect until the service is restarted in Step 16).

16. Obtain a copy of the cms.war file from Spider Strategies and put it in the directory:

%TOMCAT_HOME%/webapps/.

17. Start Tomcat (in services) and the WAR file will self extract and a “cms” folder will

appear.

6

Configuring Scoreboard

18. Open your web browser and go to: http://localhost/cms/

19. The following screen will appear. Login as the system administrator account

(username: admin). The default password is “password”.

20. Accept the Software License Agreement.

21. Accept the Scoreboard Home Path (This creates the “Spider_Home” folder).

Note that Scoreboard will place all of the application configuration information

(about 100 KB) and Scoreboard log files in a folder that it creates:

“C:\Spider_Home”, unless configured for a different location. If Spider Connect

is also installed, all Connect uploads (MS Excel files) are stored within this

folder.

7

At this point, the Scoreboard diagnostics page will indicate that errors and warnings exist.

You will now enter configurations for each of these sections, which will eliminate the

errors:

a. Application Server Information

b. Database

c. License

d. SMTP Email Server

8

22. Configuring the “Application Server Information” screen

(From the Diagnostics screen, click “Resolve Problem”)

19a. “Application Admin” section:

Password – Use this field to set the password for the built-in system

administrator account (username is “admin”). Keep this password safe.

Email – Any technical issues experienced by the Scoreboard software will

send to this address an “error report” containing a copy of the Scoreboard log

file. We recommend using the default address, such as: scoreboard-error-

report@spiderstrategies.com. Spider Strategies staff closely monitor the log

files sent to this address and can help troubleshoot any issues.

19b. “This Server” section:

Protocol – This field is typically “http”. If you are using SSL-encryption,

then use “https”.

Host – This field is the web host (ex: www.mycompany.com) name that your

users will type into their web browser to access the application.

Port – This is typically “80”. This is the TCP/IP port on which Apache

Tomcat is running.

Context – This is almost always “cms”. This is the web context that the user

types into the web browser following the web host (ex: www.abc.com/cms)

SSO Header Variable – Leave this field blank.

19c. “Email Server” section:

Host – This is an SMTP server to which your Scoreboard instance can send

system notification emails. (If you do not have this information available, or

do not wish to setup email notifications, it is not necessary to configure the

SMTP information at this time.)

Port – Typically “25”. This is your SMTP server port.

Username – This can be left blank, unless your SMTP server requires user

authentication.

Password – See username.

9

19d. “Miscellaneous” section:

Log Level – Set the logging to “INFO”.

Interval – Leave this field blank

Show Database Dropdown – Leave this as “Yes”.

19e. Click “Save”.

23. Resolving the “License Management” warning:

(From the Diagnostics screen, click “Resolve Problem”)

20a. You should have received a Scoreboard license file (spider.lic) from

Spider Strategies. Browse to this file on your computer and click “Upload

License”.

20b. This license now requires activation.

Click the “Activate” button. The application will display an alpha-numeric

code called a “Question Key”. Please email this code to the Spider Strategies

support staff at helpdesk@spiderstrategies.com.

Spider Strategies staff will promptly respond to your email with an “answer

key” code. Please enter this answer key into the text field and click “Save”.

The “License Files” screen should now appear as blue (valid) with a message

indicating that the “License is Active”.

(The above generated “Question Key” code is based on the license file and the

server’s NIC card address. Should you need to reinstall later on a different

machine, the license will need to be reactivated for the new server.)

10

24. Adding “Database Connections”:

(Note: Before adding databases, see important “Database Tuning” comments

in “Working with Databases” section towards the end of this document).

21a. Click the “Create a New Database Connection” button.

21b. Select the Database Type: SQL Server or MySQL

21c. Enter the Database Connection information:

Description – This is the descriptive label that users will see in the database

dropdown list on the Scoreboard login page.

Host or IP Address – This is the address of the database server. If the

database is located on the same server, then “localhost” should suffice.

Port- This is the database connection port, which is pre-populated for the

specified database type.

Other Fields – The remaining fields concern database connection information

– username, password, and database name necessary to connect to the

database.

Associated Domain Names – Leave this blank.

Custom Language File – Leave this blank.

21d. Click “OK”. This action will cause Scoreboard to connect to the

database and create all of the necessary tables.

25. Logout of Scoreboard.

26. Restart the “Apache Tomcat” service. This is recommended whenever you finish

adding database connections.

27. You may now login to your newly created database connection.

28. Note – if working with a new blank database, it is recommended that your

Scoreboard manager create these items first:

– One Calendar

– One Organization

– One Group

– One User

11

Terminology Files

29. Whether you are using Scoreboard or a branded version of Scoreboard, such as

QuickScore, Spider Strategies will provide you with terminology file(s) relevant

to your installation. These files may be delivered via a Zip file and will be

named in a format similar to: “CustomMessageResources*.properties”. Place

these files in your C:\Spider_Home\conf\ directory, overwriting any existing files

of the same name. Then restart the “Apache Tomcat” windows service for these

new terminology files to take effect.

12

Installing Connect

Do not perform these steps until AFTER Scoreboard is installed and connected to at

least ONE database.

Prepare Apache Tomcat for Spider Connect software

1. Download zip file containing JAR files. (Spider Strategies will provide this file.)

2. Open "Apache Tomcat Properties", either by right-clicking on Apache Tomcat in

lower-right system tray OR going to Start -> Apache Software -> Apache Tomcat ->

Configure Tomcat. (Or, run manually via %TOMCAT_HOME%\bin\tomcat6w.exe).

3. In the large "Java Options" box, scroll down and locate the line that begins with "-

Djava.endorsed.dirs=". Note the directory specified here - it is likely either

%TOMCAT_HOME%\endorsed or %TOMCAT_HOME\common\endorsed.

4. On the file system, go to %TOMCAT_HOME% and manually create this folder

structure - it will either be ./endorsed or ./common/endorsed.

Example: C:\Program Files\Apache Software Foundation\Tomcat 7.0\endorsed

5. Unzip the downloaded file and place the two JAR files in this "endorsed" folder.

6. Open this XML file in Notepad: %TOMCAT_HOME%/conf/tomcat-users.xml.

Note the first line of the file. It should contain the attribute: encoding='utf-8'. If the

encoding is set to anything else (such as 'cp1252') then change it to 'utf-8' and save

the file.

7. Restart the Apache Tomcat service.

13

Install Spider Connect

8. Download connect.war file. (Spider Strategies will provide this file.)

9. Place connect.war at %TOMCAT_HOME%/webapps.

10. Within a few seconds, you should see a "./connect" folder appear. If not, then

restart the Apache Tomcat service.

11. Go to http://YOURSERVERNAME/connect

12. The web page will ask you to enter a web address in the box. Enter:

http://YOURSERVERNAME/cms (where YOURSERVER name is your web

server's hostname that a user would enter into their web browser. This would be

http://localhost/cms" on a laptop).

13. Finally, go to http://localhost/connect and login once to any database in the list.

This last quick step will complete the installation.

Troubleshooting:

14. If this last step does not save or cannot find a database, then the JAR files are

likely not in the right place.

15. If the ./cms and ./connect applications become sluggish and non-responsive, this

means the %TOMCAT_HOME%/conf/tomcat-users.xml file has the incorrect

encoding.

14

Working with Databases – MySQL 5.0.4(+)

Important Database Tuning (MySQL Only)

1. In “MySQL Administrator” set the “Buffer Pool Size” parameter to 400 M –

higher if the server has a lot of extra memory. (In MySQL Administrator, go to

“Startup Variables” -> “InnoDB Parameters” tab -> “Buffer Pool Size” field.

Enter the value, click “Apply Changes”. If the field is disabled, click the gray

square box to the left to enable.)

2. In “MySQL Administrator” set “Max. Packet Size” to 64 M. (In MySQL

Administrator, go to “Startup Variables” -> “Advanced Networking” tab ->

“Max. Packet Size” field. Enter the value 64 and click “Apply Changes”. If the

field is disabled, click the gray square box to the left to enable.)

3. In “MySQL Administrator” set the default character set to utf8. (In MySQL

Administrator, go to “Startup Variables” -> “Advanced” tab -> “Def. Char Set”

field. Change the value from “latin1” to “utf8” and click “Apply Changes”. If

the field is disabled, click the gray square box to the left to enable.)

4. Following these MySQL parameter changes, restart the “MySQL” windows

service for the changes to take effect. New database schemas should not be

created until after this service restart so that they are created with the correct

character encoding.

15

Installing MySQL

Scoreboard has been heavily optimized for MySQL and Spider Strategies uses MySQL

exclusively for its hosting program. Also, MySQL is free. So if there is no database

preference, MySQL is the recommended choice.

Download MySQL

- Download this file: http://support-

files.spiderstrategies.com/downloads/temp/misc/mysql/mysql-essential-5.0.91-

winx64.zip

- Unzip the file to retrieve the executable.

Installing MySQL

- Run the downloaded executable.

- Accept the License Agreement

- Pick “Custom Setup”

- Accept the defaults; (Note you can change path here); Click “Next”;

- Click “Install”

- Click “Next” Twice (skipping ads)

- Check "Configure the MySQL Server now” and Finish.

Instance Configuration

- Click Next

- Pick "Standard Configuration"

- Check both "Install as Windows Service" AND "Include Bin Directory in Windows

PATH"

- Set root password. (This will be used with MySQL's "root" user)

- Click Execute

Download MySQL GUI Tools 5.0

(At this time, we recommend MySQL GUI Tools, despite its deprecation. Its

replacement, MySQL Workbench, does not work with the latest .NET Framework

releases.)

- Download this file: http://support-

files.spiderstrategies.com/downloads/temp/misc/mysql/mysql-gui-tools-5.0-r12-

win32.zip

- Unzip the file to retrieve the executable.

Install MySQL GUI Tools 5.0

- Run the downloaded executable

- Accept Licensing

- Accept or Change Path

- Select "Complete" installation

16

Working with Databases – SQL Server 2005/2008

These steps will serve as a guide in setting up a Scoreboard database for use in SQL

Server 2005 and 2008. You can create a new blank database or you can restore

existing database backups from other SQL Server 2005/2008 instances.

The SQL Server instance should utilize mixed mode authentication (Windows and

SQL Server). Scoreboard authenticates using SQL Server authentication and not

Windows authentication.

Note: A common name for the SQL Server user is “cms_user”, but you can use

another existing user.

Note: A common name for the SQL Server database is “spider”, but the name can be

arbitrarily chosen.

The Scoreboard application will assume that it has db_owner rights to this database,

such as creating, altering, and dropping tables. Providing insufficient privileges

WILL cause problems with your system and could corrupt your database.

17

Creating a blank SQL Server database

Here are the steps that to follow in SQL Server Management Studio Express to create

a blank database in SQL Server 2005.

Under security:

- Create a new login

- Specify login name

- Specify SQL Server authentication and provide a password

- Do not specify a default database (leave as master)

- Click OK

Under Databases:

- Create a new database

- Specify the database name

- Leave owner as <default>

In databases tree:

- Expand newly created database

- Expand security; Expand users;

- Right-click on users and select "New User"

- For "User name" enter login account created above.

- For "Login name" enter login account created above.

- For "Default schema" enter "dbo".

- For "Schemas owned by this user", select "db_owner".

- For "Database role membership", select "db_owner".

- Click OK.

You can then go into Scoreboard and create the database connection using the login

account that you created above. The newly created tables should appear as owned by

"dbo" in SQL Server.

In SQL Server 2005, you can see a list of the tables by (first picking the correct

database in the above dropdown and) running the query: exec sp_tables;

18

Restoring a SQL Server database (You do not need to create a blank database)

In databases tree:

- Right Click on “Databases”

- Select “Restore Database”

- Under destination for restore: For “To Database” enter the name you would like

to use for the restored database

- Under source for restore: Select “From Device”, Click Add, and Navigate to the

.bak file on the server; Click OK;

- Click the “Restore” checkbox to select the Backup.

- With that checkbox selected, now you can click Options in the upper left.

- If necessary, you can modify the “Restore As” paths for the data file (*.mdf) and

log file (*.ldf). Note that Windows may limit which directories on the server that

SQL Server can write to. Typically, you can use the default pathnames – these are

the exact pathnames taken from the server where you made the backup. You would

want to change these in instances where there are already data/log files at that path –

in which case SQL Server restore would simply fail.

- Click “OK” to perform restore.

- Your restored database should now appear under the databases tree.

Adding a user to the restored database:

- Under “Databases” tree, expand “Database Name” -> “Security” -> “Users”.

- Note that there is a list of imported users – these users are WORTHLESS! They

have no relationship whatsoever to any logins of the same name that exist in the SQL

Server instance.

- Add a new user in the same manner as described in the “Creating a blank database

section” above. Following these steps will make your new user the “db_owner” of

the “dbo” schema.

- If you wish to remove an imported user so that you can create a new user of the

same name, here are the steps: Add a new arbitrarily named user as a “db_owner” of

the “dbo” schema. (This will remove ownership from the imported user). Delete the

imported user. Now, you will be allowed to add another new user with the desired

name – and make that user the “db_owner” of the “dbo” schema.

To ensure that everything worked, take these steps:

- Go to “File” -> “Disconnect Object Explorer”

- Go to “File” -> “Connect Object Explorer” and now login as your new user.

- Find and expand your database under “Databases”.

- Click “new Query” button.

- Select your database name in the top middle dropdown.

- Run query: “exec sp_tables;” and hit F5 to run.

- This query should show all of the tables viewable by this user. You should see

the Scoreboard tables, ex: dbo.scorecardnodes, dbo.performancecharts, etc.

19

Backing Up Your Scoreboard System

Frequent backups of your Scoreboard system are recommended – at least weekly, if not

nightly. Backups are the most important aspect of a disaster recovery plan. Here are the

various areas that should be considered for regular backup.

Critical Items - These items MUST be backed up for a successful system recovery.

1. Database(s) – All of the Scoreboard data is stored within the database.

2. C:\Spider_Home\Connect\ folder – This folder contains all of the Spider Connect

content. This includes MS-Excel uploads, Connect import definitions, import

mappings, and import scheduling configurations.

Non-Critical Items – Having these items may expedite the system restore process, but

they are not irreplaceable.

1. C:\Spider_Home\conf\ folder – This folder contains server side configuration

settings, database connection information, and custom terminology.

2. C:\Spider_Home\licenses\ folder – This folder contains your license key(s).

Spider Strategies can re-issue such keys to you.

3. C:\Spider_Home\logs\ folder – These are the application log files. They are

typically not useful to backup unless maintaining these logs are a part of your

organization’s security policy.

Items to Ignore – It is not necessary to backup these items.

1. C:\Spider_Home\help\ folder – This folder is regenerated upon reinstallation of

the software.

2. C:\Spider_Home\search_index\ folder – This folder is regenerated upon

reinstallation of the software.

3. Scoreboard (cms.war) and Connect (connect.war) deployments beneath Apache

Tomcat. These files can be re-downloaded from Spider Strategies.

20

Upgrading Your Scoreboard Version

Occasionally, you may wish to upgrade to a new version of Scoreboard containing the

latest bug fixes and functionality enhancements. The upgrade process is very fast and

easy to apply.

Important Preliminary Step!

Always take a backup of your database before performing any upgrade. If any problems

occur during the upgrade process, this database backup will be critical in restoring your

system to its previous state. It is generally recommended to stop the Apache Tomcat

service when backing up the database. This prevents users from using the application

during the backup process.

Upgrade Steps:

1. Receive new WAR files (cms.war and connect.war) from Spider Strategies.

2. Stop Apache Tomcat service. (Go to: Start -> Control Panel -> Administrative

Tools -> Component Services (or just “Services”)).

3. Go to folder: %TOMCAT_HOME%/webapps/

a. Delete files: cms.war and connect.war

b. Delete folders: ./cms/ and ./connect/

4. Go to folder: %TOMCAT_HOME%/work/Catalina/localhost/

c. Delete folders: ./cms/ and ./connect/

5. Place new cms.war file at: %TOMCAT_HOME%/webapps/

6. Start Apache Tomcat service.

7. At this point, the new cms.war file will self-extract (creating a “cms” folder”

under %TOMCAT_HOME%/webapps/) and will connect to your database(s) and

perform the necessary upgrade tasks.

8. The Scoreboard upgrade tasks typically take between 1 to 5 minutes, but could

take longer depending on the particular upgrade. The upgrade is finished when

you can access the Scoreboard login screen in a web browser. You should see the

new Scoreboard version listed at the bottom of the login screen.

9. Stop Apache Tomcat service. Place new “connect.war” file at

%TOMCAT_HOME%/webapps/. Start Apache Tomcat service.