BiZZdesign. InSite Server Installation Guide

Transcription

1 BiZZdesign InSite Server Installation Guide

2 2

3 Table of contents 1. Introduction 4 2. System requirements 5 3. Contents of the installation bundle 6 4. InSite Server installation Installing the database Installing InSite Server 7 5. Log files 11 Contact information 12 3

4 1. Introduction InSite Server is a product created for server-based data reporting. InSite Server has an API (Application Programming Interface) which can be used to read information from model packages exported from the BiZZdesign modeling tools, and display this information in other places, such as a website or mobile application. Before working with it, InSite Server needs to be installed. Once installed InSite Server must be defined in the modeling tool (see the modeling tool documentation). After that model packages can be exported from the modeling tool to InSite Server. 4

5 2. System requirements InSite Server is a Java-based server. There are two options for installing InSite Server: install as a service using the built-in server, or deploy into a J2EE 5 compatible servlet container For best performance InSite Server should be installed as a service using the built-in server. If you choose to deploy into a J2EE 5 compatible servlet container, you can only install one InSite Server application. The following tables detail the minimum software requirements along with a set of recommended software products and their versions. Server software Operating system Requirements Any operating system supported by Java Run-time environment Java Platform, Standard Edition - Java Runtime Environment (JRE) 1.7 Servlet container Any servlet container supporting Servlet Api 3.0 (Java EE 5) Note: Not needed if InSite Server is installed as a service Relational database JDBC driver Microsoft SQL Server (2008, 2012), MySQL 5.1 or later JDBC 4.0 database driver for your database Microsoft JDBC 4.0 Driver The Microsoft JDBC 4.0 Driver is not distributed with the release bundle. For information about the Microsoft SQL Server Driver and downloading the driver, please refer to: The downloaded file is a self-extracting zip file. After unzipping you need the sqljdbc4.jar library (sqljdbc_4.0\enu folder). 5

6 3. Contents of the installation bundle The InSite Server installation bundle contains the following files: File 3rdparty\ conf\ database\ service\ war\insiteserver.war license.txt Explanation Legal documents of third party libraries (licenses etc.) Example configurations Scripts for creating the database tables (*.SQL) and JDBC libraries for connecting to the database (*.JAR) Files needed to install InSite Server as a service Web application archive (to be deployed in your servlet container) BiZZdesign software license readme.txt - 6

7 4. InSite Server installation This section describes how to install InSite Server. It is meant for application administrators who are familiar with installing and configuring software and databases. 4.1 Installing the database 1. Create a new empty database and use the SQL script found in the database folder for creating the tables needed for InSite Server. The script create_database_ mysql.sql is dedicated for MySQL and create_database_sqlserver.sql is dedicated for Microsoft SQL Server. 2. Create a database user having at least read and write rights for the created database. For Microsoft SQL Server the user needs the "db_ datareader" and "db_ datawriter" roles. For MySQL the user needs rights for SELECT, INSERT, UPDATE, DELETE, CREATE TEMPORARY TABLES and LOCK TABLES. 4.2 Installing InSite Server After installing the database, follow the steps of one of the following procedures to install InSite Server. There are two options: installing as a service or deploying into a J2EE 5 compatible servlet container. Installing as a service is preferred; deploying in a servlet container has certain limitations. Only one InSite Server application can be deployed into the servlet container. Installing InSite Server as a server Follow the steps below to install InSite Server as a Windows service. 1. Choose a location on the hard drive where InSite Server must be installed. This location will be further on called InSiteServerHome. 2. Copy the contents of the \service folder (not the folder itself) in the release bundle to the InSiteServerHome folder. 3. If you are using a Microsoft SQL Server database, copy the downloaded Microsoft JDBC 4.0 Driver file sqljdbc4.jar to the InSiteServerHome\lib folder. 4. Edit the wrapper.conf file (InSiteServerHome\conf folder) in a text editor and check the following settings: o Update the HTTP port under which the server must be running. For example HTTP port 9000: wrapper.java.additional.2 = -Dhttp.port=9000 o Set the correct JDBC library by removing the # in front of one of the lines starting with: #wrapper.java.classpath.xx 7

8 5. Copy the appropriate example configuration file (insiteserver-<database_ name>.conf) from the \conf folder in the release bundle to the InSiteServerHome\conf folder and rename the file to insiteserver.conf. 6. Edit the insiteserver.conf file in a text editor and set the correct values for the configuration options found in this file. The base URL (application.baseurl) is needed as InSite Server could be served behind a proxy and InSite has no way to know this URL. It needs to be the URL where InSite Server will be accessed by the users of the InSite Server API. 7. Verify that InSite Server is correctly configured: a. Execute the runconsole.bat file in the InSiteServerHome\bat folder b. Point the browser locally to localhost:<http.port>/v1/modelpackages or from another computer to <application.baseurl>/v1/modelpackages A JSON response like the following is expected: {"_items":[],"_offset":0,"_limit":10,"_links": {"self":"<application.baseurl>/v1/modelpackages"}} Important: Check if the URL of "self" in the "_links" collection in the JSON is valid by clicking this URL, or copy/paste this URL in the browser. If everything is running correctly, press Ctrl+C in the console to stop InSite Server. If an error occurs, check if a file RUNNING_ PID exists ( InSiteServerHome\ folder). This file must be deleted before trying to run a second time. 8. Install the service by running the installservice.bat file as administrator in the InSiteServerHome\bat folder. 9. Start the service by running the startservice.bat file as administrator in the InSiteServerHome\bat folder, or go to Control Panel > Administrative Tools > Services and start the service there. The service is called InSite Server <version>. Deploying InSite Server in a servlet container Follow the steps below to install InSite Server in an Apache Tomcat servlet container. 8

9 Note: For the installation, the location of the configuration file needs to be configured by adding the Java system property -Dconfig.file=<path-to-configuration-file> to the Java options of Tomcat. Please check first if the Java system property "config.file" is not already used for another application in Tomcat. If this is the case, InSite Server cannot be configured in this Tomcat instance. 1. Copy the appropriate example configuration file (insiteserver-<database name>.conf) from the \conf folder in the release bundle to a location accessible by Tomcat and rename the file to insiteserver.conf. 2. Edit the insiteserver.conf file in a text editor and set the correct values for the configuration options found in this file. The base URL (application.baseurl) is needed as InSite Server could be served behind a proxy and InSite has no way to know this URL. It needs to be the URL where InSite Server will be accessed by the users of the InSite Server API. 3. Copy the driver file to the \lib folder of your Tomcat installation. If you are using a Microsoft SQL Server database, copy the downloaded Microsoft JDBC 4.0 Driver file sqljdbc4.jar. The MySQL driver file mysql.mysql-connector-java jar is available in the \database folder of the release bundle. Note: If you already have installed the JTDS JDBC database driver for Microsoft SQL Server, which was recommended for the BiZZdesignEMS, the Microsoft JDBC 4.0 database driver must be added to the \lib folder of your Tomcat installation. 4. Add the location of the configuration to the Java options of Tomcat: a. Right click the Tomcat icon in the task bar and click Configure, or open the Tomcat monitor via the Start menu. b. On the General tab, click Stop and wait until the service has stopped. c. Click the Java tab, scroll all the way down in the Java Options box, and add the following line: -Dconfig.file=<path-to-configuration-file> Example: -Dconfig.file=C:\deploy\insiteserver-1.0\insiteserver.conf 5. Do not start Tomcat yet. You must first deploy InSite Server: a. Copy the file insiteserver.war to the \webapps folder of Tomcat. b. On the General tab, click Start. c. Point the browser to or 9

10 <application.baseurl>/v1/modelpackages A JSON response like the following is expected: {"_items":[],"_offset":0,"_limit":10,"_links": {"self":"<application.baseurl>/v1/modelpackages"}} Important: Check if the URL of "self" in the "_links" collection in the JSON is valid by clicking this URL, or copy/paste this URL in the browser. 10

11 5. Log files InSite Server keeps log files with detailed information on all activities in InSite Server. These files can be useful for problems or bugs in InSite Server. When InSite Server is installed as a service, the log files can be found in the InSiteServerHome\logs folder. When deployed in Tomcat, the log files can be found in the logs folder of Tomcat in the application.log file. If InSite Server does not start correctly, the cause can be found in the standard Tomcat log files. 11

12 Contact information BiZZdesign Service desk For questions and information regarding service and support. Telephone: servicedesk@bizzdesign.com BiZZdesign Academy For questions and information regarding training and education. Telephone: academy@bizzdesign.com BiZZdesign Inside Sales For questions and information regarding commercial conditions, new modules and prices for use. sales@bizzdesign.com BiZZdesign For general questions and information. Telephone: info@bizzdesign.com BiZZdesign website BiZZdesign customer portal htttp://support.bizzdesign.com 12

13