Installation & Configuration - Enterprise, Group and Community Server

Transcription

1 Installation & Configuration - Enterprise, Group and Community Server System Requirements System Requirements for the Server: System Memory: 2 GBytes (3 GB recommended for Windows Vista/7/Server Operation Systems) Hard Drive Space: About 100 MBytes (Onepoint Project base distribution + Application Server) Operating System: Linux, Windows XP/Vista/7, Windows Server 2003 or later, MacOS 10.5 or later Java SE Runtime Environment 5.0 or 6.0 by Oracle/Sun Microsystems (latest JRE or JDK 6.0 recommended) Tomcat 5.5 Application Server or later (latest stable release of Tomcat 6 highly recommended) Databases that can be used for our "Community Server": PostgreSQL 8.3 or 8.4 (Unicode/UTF-8 character set) Databases supported to be used with our "Group-" or "Enterprise Server": PostgreSQL 8.3 or 8.4 (Unicode/UTF-8 character set) Microsoft SQL 2005 or later Oracle 10g or 11g (Unicode/UTF-8 character set) Note: For good performance, please make sure to install the database and the application-server on the same machine System Requirements for Clients: System Memory: 1 GByte Operating System: Linux, Windows XP/Vista/7, Windows Server 2003 or later, MacOS 10.5 or later Windows Browsers: Internet Explorer 7 or later, Firefox, Google Chrome Linux Browsers: Firefox MacOS Browsers: Safari Java SE Runtime Environment 5.0 or 6.0 by Oracle/Sun Microsystems (latest version 6.0 Java Plug-in recommended) Note: Starting with this release, the support for the database MySQL was dropped for our "Community Server". Users of MySQL databases should please move their existing data to a PostgreSQL 8.3 or 8.4 database before starting an upgrade process. For instructions on how to transfer data between different database types, please continue reading at chapter 5.3, "Database Migration" If you system still meets the system requirements and you need to upgrade a previous release of Onepoint Project, then please continue reading at chapter 5.2, "Upgrading Onepoint Project Server".

2 Installing Java If you are not sure which version is installed, please execute the following command in your terminal or command line: java -version This should show something like "Java(TM) SE Runtime Environment" along with the version number. If the command does not work at all, then most likely no Java is installed yet. If this is the case or the version is lower than 5.0 then please install a newer version: Windows users: You can download the newest releases from (JDK and JRE) or (JRE) MacOS users: Java is already installed and comes with the operating system - Please use the Software Update feature in the Apple Menu to install the latest version (Instructions can be found here Linux users: You can download the newest releases from (JDK and JRE) or (JRE only, rpm or binary installer) or use the package manager of your distribution to install a new version. Instructions on how to install Java and the Java Plug-in can be found on the download page. Note: Many Linux distributions come with OpenJDK which cannot be used for Onepoint Project Installing the "Tomcat" Application Server An application server is needed to start Onepoint Project itself - This section describes how to install the 'Apache Tomcat' server. At least version 5.5 is needed but the latest releases of version 6 are known to perform better and are recommended. The examples in this manual, if not other specified, will always refer to Tomcat 6. Please download the "Core" Binary Distribution from Windows users should choose the "Windows Service Installer" distribution while MacOS and Linux users will need the tar.gz archive. Note: MacOS server and most Linux server distributions come with preinstalled versions of Tomcat or allow to install Tomcat by using a package manager. These are in most cases not the newest releases or preconfigured with additional libraries which may lead to problems when trying to start your Onepoint server. Please always install Tomcat using the original binary distributions. Installing Tomcat on Windows: To install, make sure you are logged in as a user with administrator privileges and simply doubleclick the installer (On newer Windows versions, you may need to start the installer by right-clicking it and choosing "Run as Administrator") During installation you will be asked for an optional administrator username and password. Please make sure to create that account to be able to verify Tomcat's settings after configuration. To start or stop Tomcat, please open the "Apache Tomcat 6 Properties" dialog and use the corresponding buttons (If you cannot find it, execute "Monitor Tomcat" from the new Program Group which was created during install and doubleclick the new icon in your taskbar) Installing Tomcat on MacOS There are several ways of installing Tomcat on MacOS, this is the maybe simplest way: Doubleclick the downloaded tar.gz archive to unzip it Move the unzipped folder to where you want to it install Tomcat to (For example usr/local or into your Applications folder for test-installations) Installing Tomcat on Linux You will find lots of tutorials on installing Tomcat using the tar.gz distribution in the forums of your Linux distributions. To start or stop Tomcat on MacOS or Linux, you will find the corresponding scripting files in Tomcat's "bin" folder. They are called "startup.sh" or "shutdown.sh". To execute them, open a Terminal and navigate to Tomcat's "bin" folder. Then type "./startup.sh" or "./shutdown.sh" to start or stop the server. To verify if Tomcat was installed properly, start Tomcat and connect to " with your browser (or replace "localhost" with your server's IP). After that, a welcome page should be shown in your browser.

3 1 Tomcat Configuration To be able to use Tomcat for Onepoint Project, you will need to increase it's memory/javaheap settings: Windows Users: Open the "Apache Tomcat Properties" dialog (Is actually tomcat5w.exe or tomcat6w.exe in your Tomcat installation's "bin" folder) Select the "Java" tab Enter "512" for Initial memory pool and "1024" for Maximum memory pool In the "Java Options" field, add the lines "-XX:PermSize=128m" and "-XX:MaxPermSize=384m" Note: If you have chosen the zip distribution instead of the installer, please open or create the file "setenv.bat" in Tomcat's "bin" folder and add the line: set JAVA_OPTS=-Xms512m -Xmx1024m -XX:PermSize=128m -XX:MaxPermSize=384m The settings in this file will be automatically applied with the next server restart. To verify your changes, please connect to the Tomcat welcome-page with your browser, for example " and click "Status". After singning on, the section "JVM" should show the increased settings. MacOS or Linux users: Please create a file "setenv.sh" in Tomcat's "bin" folder and add the lines #!/bin/sh # export JAVA_OPTS='-Xms512m -Xmx1024m -XX:PermSize=128m -XX:MaxPermSize=384m' The settings in this file will be automatically applied with the next server restart. To verify your changes, please open a command line or terminal and execute the following command: ps aux grep catalina In the result which will be displayed after executing the command, you should now find something like "-Xms512m -Xmx1024m -XX:PermSize=128m -XX:MaxPermSize=384m" To enable SSL for Tomcat, please read the following guide: Onepoint Project itself does not need additional configuration for SSL/https.

4 The Database Onepoint Project stores all it's data in a separate database. Our Community Server needs the database PostgreSQL, version 8.3 or 8.4 to be installed (Compatible JDBC driver is already included in Onepoint Project) while our Group or Enterprise Server allows to choose one of the following supported databases: PostgreSQL 8.3 or 8.4 Microsoft SQL 2005 or later Oracle 10g or 11g For communications between Onepoint Project and the database we use a JDBC driver file, which is different for each database and can usually be downloaded from the database manufacturer's homepage. For PostgreSQL 8.3/8.4 and Microsoft SQL these drivers are already included. Users of Oracle databases will have to download the correct "JDBC Thin" driver according to your database- and Java-version and copy it into Tomcat's "/common/lib" (Tomcat 5.5) or "/lib" (Tomcat 6) folders (Can be found in Oracle's download-area). To finally be able to connect to the database, you will need to create an empty space for our tables and a user-account/login which allows to write data to it. He are examples for these preparations, with an example for each database type: 1 PostgreSQL Before installing Onepoint Project please make sure that the database's default timezone was set to "GMT". The needed steps are described in the chapter "APPENDIX" at section 7.2 near the end of this document. To be able to connect to a PostgreSQL database we will need an empty database and a database user to connect to it. These are the basic steps for the PostgreSQL console, assuming your database's default user is called "postgres": Open a command line or terminal window and type psql -Upostgres Enter the password which you specified when installing PostgreSQL and proceed with the following commands to create a database called "opproject", belonging to the user "opproject" and with password "opproject" postgres=# create user opproject password 'opproject'; postgres=# create database opproject owner opproject encoding 'utf-8'; postgres=#\q 2 Microsoft SQL To be able to connect to a MS SQL database we will need a "login", an empty database and a database user to connect to it. Please make sure that you are logged into the database with permissions to create the needed elements, for example as a local administrator user (Windows Authentication) or as the user "sa" (SQL Authentication). This is an example for the necessary queries for the command line (For example use Management Studio to enter them): CREATE DATABASE opproject; Creates the database "opproject" CREATE LOGIN opproject WITH PASSWORD = 'opproject_secret', DEFAULT_DATABASE = opproject; Creates the login "opproject" USE opproject; CREATE USER op_user FOR LOGIN opproject; Selects the database and creates the database user "op_user", linked to the login "opproject"

5 EXEC sp_addrolemember 'db_owner', 'op_user'; Grants the necessary role "db_owner" to the user "op_user" Note: If you want to use Windows Authentication to connect to your database, you will have to add an additional "ntlmauth.dll" driver in your "WINDOWS\SYSTEM32" folder: This driver file is always included in the jtds binary distribution which can be downloaded from (Please make sure to choose the "dist" archive which includes the binaries and follow the installation instructions like described in the file "README.SSO"). 3 Oracle To be able to connect to an Oracle database server we will need "connect" and "resource" roles for the database user account: CONNECT RESOURCE (Only Standard, not Admin) These are the exact permissions which will be granted by these roles: CONNECT role has only CREATE SESSION RESOURCE has CREATE CLUSTER, CREATE INDEXTYPE, CREATE OPERATOR, CREATE PROCEDURE, CREATE SEQUENCE, CREATE TABLE, CREATE TRIGGER and CREATE TYPE Here is a small example on how to create a database user from the Oracle command line, for this small example we will not specify a tablespace and use the default one (You will have to be logged in as sysdba): create user opproject identified by opproject_secret; Will create a database user 'opproject' with the password 'opproject_secret'. grant connect, resource to opproject; Will grant connect and resource roles to the user 'opproject'. If you receive a 'ORA-28000: the account is locked' error message, you will have to unlock the account like in the following example and repeat the 'grant' statement above: alter user opproject account unlock;

6 5. Installing or Upgrading Onepoint Project Server 5.1 Installing Onepoint Project Server Linux users: Before starting the install procedure, please make sure that the user starting Tomcat is allowed to write in it's home folder (will be most likely '~tomcat', our 'Onepoint Project Home' folder will be created in this directory). Shutdown the Tomcat application server if it's started Copy the file "opproject.war" from the zipped Onepoint distribution into Tomcat's "webapps" folder Start Tomcat Next, open a browser window and enter the following URL to connect to your Onepoint Project installation: or for ssl enabled installations: If your connecting from a different computer to the server, then please replace "localhost" with the correct IP or domain name. If a different port was configured for Tomcat, please replace "8080" or "8443" with that one (ore you could remove ":8080" from the URL if you configured port "80" for the http connector). If everything works fine, the applet should be loaded and now be shown in your browser for the first time. Note: If you are installing a Group or Enterprise Server, you will now be asked to choose your license file (it's called "license.oxl.xml" - you should have received it either attached to the delivery, from a download link inside that mail or downloaded from the Onepoint Store) The last step needed is the configuration of the connection to the database: Choose the database type from the chooser Alter the "Connect String" according to your database's parameters (You can find examples for connection strings in the APPENDIX, chapter 7.1 at the end of this document) For "Database Login", enter the database user's login/name For "Database Password", enter the database user's password To load the included demonstration dataset, you can mark the checkbox "Import demodata" Click "Connect" After some time the login screen will appear - Please login as "administrator" (leave the password field empty) If the login does not appear or the database configuration is not being accepted, please search the logfiles in either Tomcat's "logs" folder (they are called "catalina" or "stdout") or the file "Onepoint Project Home/opproject/logs/opproject.log" for error messages. Note: During the installation, the folder "Onepoint Project Home", containing the directory "opproject" will be created in the home folder of the user who started Tomcat. Windows users will usually start Tomcat as a system service which will create these folders in c:\ ("c:\onepoint Project Home\opproject"). This folder stores the license file, the configuration file, the logfiles and all your backups 5.2 Upgrading Onepoint Project Server Before upgrading your server, please make sure to create a backup in the "Repository" tool (And creating an additional database dump/backup is highly recommended, too) since downgrading the data afterwards will not be possible. 5.1 Upgrading an existing Onepoint Project Server 10.0 or later: If you have already installed Onepoint Project Server 10.0 or later, Please make sure to backup your data first (create a database dump/backup and a backup in the tool ADMINISTRATE/Repository) and follow these few steps: Note: Users of Oracle databases: Please make sure that a compatible JDBC driver for your database can be found in Tomcat's own "/lib" or "/common/lib" folder - If not yet, please copy it from "...webapps/opproject/web-inf/lib" to this folder Shutdown Tomcat Move the files "opproject.war" and the folder "opproject" out of Tomcat's "webapps" directory or delete them Copy the file "opproject.war" from the new distribution into Tomcat's "webapps" folder Start Tomcat and connect to your Onepoint installation with your webbrowser Users of Group or Enterprise Server: If your existing license file is not valid anymore for the new installation, you will be asked for a new one (license.oxl.xml) - If this is the case, please choose the correct file with the dialog. After the last step it can take some minutes until the login appears (especially when upgrading to a new major release). At this point, the database schema will be updated and if needed, the plannings will be recalculated. The progress can be best monitored by opening the

7 logfiles in either Tomcat's "logs" folder (they are called "catalina" or "stdout") or using the file "Onepoint Project Home/opproject/logs/opproject.log" 5.2 Upgrading from 9.x or earlier to 10.0 or later: Linux users: Before starting the upgrade procedure, please make sure that the user starting Tomcat is allowed to write in it's home folder (will be most likely '~tomcat', our 'Onepoint Project Home' folder will be created in this directory). Please make sure to backup your data first (create a database dump/backup and a backup in the tool ADMINISTRATE/Repository) and follow these few steps: Shutdown Tomcat Copy or move the files "configuration.oxc.xml" and your "backup" folder out of Tomcat's "...webapps/opproject" directory Move the files "opproject.war" and the folder "opproject" out of Tomcat's "webapps" directory or delete them Copy the file "opproject.war" from the new distribution into Tomcat's "webapps" folder Start Tomcat After the new "...webapps/opproject" folder was deployed, connect with a browser to your Onepoint installation (For example Note: Now the folder "Onepoint Project Home", containing the directory "opproject" will be created in the home folder of the user who started Tomcat. Windows users will usually start Tomcat as a system service which will create these folders in c:\ ("c:\onepoint Project Home\opproject") Move everything you copied out of the old installation at step number 2 back into the new "Onepoint Project Home/opproject" folder If you are using an Oracle database, please add a compatible JDBC driver in the folder "...webapps/opproject/web-inf/lib" or even better - place it in Tomcat's own "/lib" or "/common/lib" folder to make it available for other applications or for future installations or upgrades, too Restart Tomcat and connect to your Onepoint installation with your webbrowser You will be asked for you new license file (license.oxl.xml) - please choose the correct file with the file dialog After the last step it can take some minutes until the login appears (especially when upgrading to a new major release). At this point, the database schema will be updated and if needed, the plannings will be recalculated. The progress can be best monitored by opening the logfiles in either Tomcat's "logs" folder (they are called "catalina" or "stdout") or using the file "Onepoint Project Home/opproject/logs/opproject.log" 5.3 Database Migration Note: These instructions assume that your installation was already upgraded to Onepoint Project 10.0 or later and that the destination database was already installed and prepared like described in chapter Make sure to backup your data first (create a database dump/backup and a backup in the tool ADMINISTRATE/Repository) Sign off and stop Tomcat Delete the file "Onepoint Project Files/opproject/configuration.oxc.xml" Start Tomcat Connect to your installation with the web-browser as usual (Since the file "configuration.oxc.xml" is missing now, the database-configuration form will be shown) Enter the connection settings for your new (destination-)database (After the connection-parameters have been confirmed, the new database-schema gets created - This process can take a few seconds) After the login-form is shown, sign on as "administrator" Open the system-settings toolset (by clicking the tool-shaped button in the upper right corner) Select the tool "Repository" and restore the backup you created on the source database Note: If the restore-process fails, please check the logfile "opproject.log" in the folder "Onepoint Project Home/opproject/logs/" for error-messages

8 6. Onepoint Project Configuration When starting the software for the first time, all database connection parameters are stored in a file called "configuration.oxc.xml". It can be found in your "Onepoint Project Home/opproject" folder. This chapter sums up how to configure or add other configuration options in this file. If you make changes to this file which are not allowed or will not work, then the file will be renamed to "configuration.oxl.xml.bak". If this is the case, then the "opproject.log" logfile will give a hint on what went wrong. This is an example how your configuration file could look like after you installed Onepoint Project the first time: <?xml version= "0" encoding= "UTF-8"?> <configuration> <database name= "Default" > <database-type> PostgreSQL</database-type> <database-driver> org.postgresql.driver</database-driver> <database-url> jdbc:postgresql://localhost:5432/opproject</database-url> <database-login> opproject</database-login> <database-password encrypted= "true" >dgnlam9ychbvzxjlbmltzwvhcna= </database-password> </database> </configuration> Everything between <database name="default"> and </database> describes your working database connection and should remain unchanged. To add other configuration options to this file which are not automatically written to it, please open it with a texteditor or xml editor and insert the additional settings between the closing </database> and </configuration> entries. For example: </database> <smtp-server> </smtp-server> <max-attachment-size> 40</max-attachment-size> </configuration> 6.1 Enabling the Notification System (Group and Enterprise Server) <smtp-server>localhost</smtp-server> If the SMTP-Server is running on a different computer, please replace "localhost" with the domain name or IP of your SMTP Server and save the file. After restarting Tomcat, the notification system will be enabled (Of course, you will need to enter -adresses for all your users in the "Users" tool - and enable the needed notifications in the "Notifications" tool) 6.2 Configuring the Notification Trigger (Group and Enterprise Server) Some notifications like for example "Scheduled work was not yet started" are sent at the same time every day at 8:00 AM GMT. This can be overridden by the following setting (Here an example to send the notifications at 12'clock, every day): <notification-trigger> * *?</notification-trigger> The full documentation on the the format of the "Cron-Expression" string inbetween <notification-trigger> and </notification-trigger> can be found here: Maximum File Size for Attachments and Documents <max-attachment-size>10</max-attachment-size> The value stands for the size in MBytes - The example above would set the maximum attachment size to 10 MBytes. The reason for setting a default limit for the attachment size was that some JDBC drivers work more efficient than others and 5 Mbytes is safe for all databases. If you want to use higher settings like 50 MBytes for example, please make sure to set high -Xmx for Tomcat (1 GByte minimum) and use either PostrgeSQL, MS SQL or Oracle databases. For attachment sizes 100 MBytes and above, Oracle is recommended.

9 6.4 Remote Javaheap Setting for Clients <client-jvm-options>-xmx256m</client-jvm-options> This setting was introduced with version 9.1 update 1 and makes it possible to remotely increase the applet/clientside javaheap (works exactly like increasing server-side javaheap, in the example above increases the setting to 256 MBytes). Please note that your browsers' plugin versions must be Java 6.0_10 or later in order to be able to handle this setting. Older Java versions will ignore this setting. 6.5 Backup Folder Location <backup-path>path</backup-path> Please replace "PATH" with the full path to your backup folder - For example <backup-path>d:\2009\backup</backup-path> 6.6 LDAP/Active Directory Configuration (Group and Enterprise Server) Our Group and Enterprise Servers can connect to OpenLDAP or Active Directory to retrieve user accounts and groups. Please contact our support-hotline for the full documentation on this subject, along with example configuration files. 6.6 JIRA Connector (Group and Enterprise Server) Release 10.1 and later optionally allow to connect to the issue and project tracking tool JIRA by Atlassian. Please note that this new option has to be activated in your license file (If you want to try that new option please contact our sales or support-team). Detailed information on how to install the plugin and how to configure the connection itself can be found in the file "install_jira_configuration.pdf" in the folder "jira_plugin" of the downloaded Group- or Enterprise Server zip-distribution. 6.7 Configuring the JIRA Trigger (Group and Enterprise Server) All requirements, work records or tasks which have been imported from JIRA get by default synchonized with the JIRA-server at the same time every day at 8:00 AM GMT. This can be overridden by the following setting (Here an example for 12'clock, every day - the configuration works the same way like the "Notification Trigger" described in 6.2): <jira-trigger> * *?</jira-trigger> The full documentation on the the format of the "Cron-Expression" string inbetween <jira-trigger> and </jira-trigger> can be found here:

10 7. APPENDIX 7.1 Example JDBC Connection Strings A complete discussion about JDBC connect strings is way beyond the scope of this document, but we would like to provide you with example connect strings for the most simple case. PostgreSQL Connection String: This is an example connection string for a PostgreSQL instance installed with default values on "localhost" using port 5432 and database name "opproject": jdbc:postgresql://localhost:5432/opproject MS SQL Server Connection String: This is an example connection string for a MS SQL instance installed with default values on "localhost" using port 1433 and database name "opproject": jdbc:jtds:sqlserver://localhost:1433/opproject Note: If Windows server authenzication was used, please make sure to specify the domain like in the following example: "jdbc:jtds:sqlserver://localhost:1433/opproject;domain=domainname" Oracle Connection Strings: This is a connection string for a single Oracle instance installed with default values on "localhost" with SID "orcl" using port 1521: jdbc:oracle:thin:@localhost:1521/orcl or if you prefer an alternative connection string - jdbc:oracle:thin:@(description=(address=(protocol=tcp) (HOST=hostname)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=ORCL))) An example for an Oracle RAC connection string: jdbc:oracle:thin:@(description=(load_balance=on) (ADDRESS=(PROTOCOL=TCP)(HOST=host1) (PORT=1521)) (ADDRESS=(PROTOCOL=TCP)(HOST=host2) (PORT=1521)) (CONNECT_DATA=(SERVICE_NAME=service))) 7.2 Setting the GMT timezone for PostgreSQL In order to set the timezone for the database instance shutdown your PostgreSQL database instance, then: Locate the postgresql.conf file in your PostgreSQL "data" directory Open the file using any text editor (e.g. notepad) and locate the following line: #timezone = unknown # actually, defaults to TZ Change this line in the following way: timezone = GMT # actually, defaults to TZ Note: Make sure to remove the leading '#' Restart your PostgreSQL database instance (Just in case, if your PostgreSQL server fails to start after the change, please make sure that the permissions on the file 'postgresql.conf' are correct)