Scoreboard 2.5/2.7 Installation Guide. For Apache Tomcat 7.0 On Windows 2003/2008 Server, 64-bit

1

Scoreboard 2.5/2.7 Installation Guide

For Apache Tomcat 7.0

On Windows 2003/2008 Server, 64-bit

Scoreboard and Connect

Minimum Server Requirements

The following minimum server requirements are current as of September 3, 2013.

Server:

The server hosting the web component (Apache Tomcat) should be STANDALONE and not hosting applications for other systems. The server can be a virtual server if desired.

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 - MS SQL Server 2005/2008

3

Scoreboard and Connect

Installing Java and Tomcat

Required Programs for this Installation:

1. Java SE 7 latest update, Download “JRE”; Windows x64, jre-7u??-windows-x64.exe. 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 7 installation executable from the above listed URL. 2. Install the JRE 7.

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 7 version that you just installed. (Ex: C:\Program Files\Java\jre7 )

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.

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.

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

22. Configuring the “Application Server Information” screen

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

22a. “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.

22b. “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.

22c. “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.

9 22d. “Miscellaneous” section:

Log Level – Set the logging to “INFO”. Interval – Leave this field blank

Show Database Dropdown – Leave this as “Yes”.

22e. Click “Save”.

23. Resolving the “License Management” warning:

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

23a. You should have received a Scoreboard license file (spider.lic) from Spider Strategies. Browse to this file on your computer and click “Upload License”.

23b. 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.)

24. Adding “Database Connections”:

(Note: Before adding databases, see important “Database Tuning” comments in “Working with Databases” section towards the end of this document).

24a. Click the “Create a New Database Connection” button. 24b. Select the Database Type: SQL Server or MySQL 24c. 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.

24d. 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.

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. 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.

2. Restart the Apache Tomcat service.

Install Spider Connect

3. Download connect.war file. (Spider Strategies will provide this file.) 4. Place connect.war at %TOMCAT_HOME%/webapps.

5. Within a few seconds, you should see a "./connect" folder appear. If not, then restart the Apache Tomcat service.

6. Go to http://YOURSERVERNAME/connect

7. 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).

8. Finally, go to http://localhost/connect and login once to any database in the list. This last quick step will complete the installation.

Troubleshooting:

9. If this last step does not save or cannot find a database, then the JAR files are likely not in the right place.

10. 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.

13

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.

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

15

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.

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;

17

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.

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.

19

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.