Scoreboard 2.16 Installation Guide For Apache Tomcat 8.0 On Windows 2003 (or later) Server, 64-bit Updated November 10, 2016 1
Scoreboard and Connect By Spider Strategies Minimum Server Requirements The following minimum server requirements are current as of November 10, 2016. 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. 6 GB is recommended. More is always better. Disk Space: 50 GB of free Disk Space minimum, not accounting for database. 100 GB is recommended. 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 7.0 and Apache Tomcat 8.0 are supported. Databases Supported: - MySQL 5.0.4(+), 5.1, 5.5, and 5.6 - MS SQL Server 2008 / 2008 R2 / 2012 / 2014 2
Scoreboard and Connect By Spider Strategies Installing Java and Tomcat Required Programs for this Installation: 1. Java SE 8 latest update, Download JRE ; Windows x64, jre-8u???-windows-x64.exe. URL: http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads- 2133155.html 2. Apache Tomcat 8.0.x Binary Distribution, Core, 32-bit/64-bit Windows Service Installer. (Note that Tomcat 8.5.x is not supported at this time) URL: http://tomcat.apache.org/download-80.cgi Steps: 1. Download the JRE 8 installation executable from the above listed URL. 2. Install the JRE 8. 3. Download the Apache Tomcat 8.0.x (not 8.5.x) executable from the above listed URL. 4. Install Apache Tomcat 8.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 8 version that you just installed. (Ex: C:\Program Files\Java\jre8 ) 8. Tomcat Installation: The default installation path for Apache Tomcat is C:\Program Files\Apache Software Foundation\Tomcat 8.0 but you can change this. We will simply refer to the installation location as %TOMCAT_HOME% in our communications with you. 3
9. Tomcat Installation: Select Run Tomcat and click Finish. 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 8.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\tomcat8w.exe). 12a. On the Java tab set the Maximum Memory Pool value, using a value of 2500 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. 4
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 ) 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-errorreport@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. Password See username. 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.) 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). 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. 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. 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. 14
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 15
Working with Databases SQL Server 2008+ These steps will serve as a guide in setting up a Scoreboard database for use in SQL Server 2008+. You can create a new blank database or you can restore existing database backups from other SQL Server 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. 16
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 2008. 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. 18
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. 20