Installing IBM Rational Team Concert Express Edition using IBM Installation Manager
Installing Rational Team
Concert Express edition
Upgrading to Rational Team
Concert 1.0.1
or 1.0.1.1
You can upgrade Rational® Team
Concert clients
and servers by either performing a zip or Installation Manager install.
Note:
If you use the Installation Manager to install Rational Team
Concert 1.0.1.1 on a computer
where Rational Team
Concert is
not currently installed, the Installation Manager prompts you to select
the languages to install. However if you update from an earlier version
to 1.0.1.1, the Installation Manager assumes that you want to use
the current languages and does not prompt you to select languages.
Pre-1.0.1.1 versions are available in English only. To select the
additional languages, after you update to 1.0.1.1, select Modify from
the main screen in the Installation Manager, then select the offering.
The next screen shows the list of supported languages. Select the
ones you need.
Upgrading 1.0 Rational Team
Concert Eclipse
Clients
If you have 1.0 clients, we recommend that you obtain
the 1.0.1 or 1.0.1.1 client to connect to your new 1.0.1 or 1.0.1.1
server. You can install these using a zip file, or you can update
your prior Installation Manager installs.
Upgrading a Server from a Trial or Early Access release
to a Permanent release
If you are running an Early Access
release of Rational Team
Concert,
first upgrade to the 1.0 Trial release, or directly to the purchased
1.0.1 Server product. The 1.0 server keys do not make an Early Access
server Permanent.
From the 1.0 Trial release, you can make
your server Permanent by purchasing and installing the Server Activation
Kit for your edition which is available here: http://www-306.ibm.com/software/awdtools/rtc/.
The activation kit consists of a JAR file containing the Permanent
server key. It is installed using the License Key Management page
of your server's administrative Web interface.
Upgrading a Server from 1.0
You can upgrade
directly to the 1.0.1 or 1.0.1.1 release of Rational Team
Concert from
the 1.0 release. You can re-use your 1.0 database; there is no database
migration required.
Note:
Before you begin upgrading a Websphere
Application Server, reset the server by navigating to https://servername:9443/jazz/admin#action=com.ibm.team.repository.admin.serverReset and
clicking Request Server Reset.
If
you are running an earlier milestone or Beta, follow the upgrade instructions
for 1.0 https://jazz.net/downloads/rational-team-concert/releases/. First, perform any necessary database migration.
If
you installed the 1.0 release from a zip file, then there is no intersection
with the previous install. You can install the 1.0.1 or 1.0.1.1 release
from a zip in a new location, or you can use the Installation Manager
to install an instance of 1.0.1 or 1.0.1.1.
If you used Installation
Manager to install the 1.0 release, you can either install 1.0.1 or
1.0.1.1 as a separate instance or update the 1.0 instance to 1.0.1
or 1.0.1.1. If you install a separate instance of the server for the
1.0.1 or 1.0.1.1 release, select Create a new package group on
the Install Packages page of the installation
wizard.
Note:
To upgrade a Websphere Application Server, remove
the 1.0 jazz.war file and deploy the 1.0.1 jazz.war file.
To
complete the upgrade, see Copying the required configuration
files from a previous server installation and Installing 1.0.1 Activation
Keys.
Upgrading a Server from One Rational Team
Concert Edition
to Another
You can upgrade between Rational Team
Concert editions.
Typical upgrades include moving from Express-C to Express™,
or Express to Standard. You can also downgrade in the opposite direction
by following the same process.
Because all Rational Team
Concert 1.0.1
and 1.0.1.1 editions support Derby databases, you do not need to migrate
from Derby to DB2® or Oracle if you are moving from Express-C
to Express or Standard. We recommend that you migrate your server
edition first, make sure things work smoothly with the existing database,
and then perform a database migration if required. For information
on performing a database migration, see Migrating the Jazz™ Team
Server.
If you have installed a Rational Team
Concert 1.0.1
or 1.0.1.1 edition and want to upgrade to another, download and install
the new edition, alongside the existing edition, and then copy the
required configuration files to run the new edition. The section below
describes the configuration files that you require.
If you
installed your previous edition from a zip file, then there is no
intersection with the previous install. You can install the new edition
from a zip in a new location, or you can use the Installation Manager
install for the new edition. We recommend that the Installation Manager
be used for production servers to enable future updates to be applied.
If
you used Installation Manager to perform your previous server install,
and want to use Installation Manager to install your new edition,
during the new Installation Manager install, do not to overlay the
previous edition. On the Install Packages page
of the installation wizard, select Create a new package
group.
This will install the new edition in a different
location and create program shortcuts using the new package group
name.
If you do not perform this task, the installation will
fail with a file collision. This occurs if you see an error dialog
titled Installation Failed, and the details
show the following text:
Installation failed.
Error during "install" phase:
Failed to extract zip standard 1.0.1.I20081018-1820. File
D:\JazzTeamServer\server\license-update-site\site.xml already exists.
If this occurs, it is not fatal; you can restart
the installation and correctly create a new package group.
Copying the required configuration
files from a previous server installation
Copy the following
files from the source server to the target server. First, rename the
original files in the upgraded server install to create backups. If
you used the Installation Manager to update from 1.0 to 1.0.1, a backup
directory containing your 1.0 configuration files was created with
a name, such as backup-config-timestamp in
the server subdirectory of the installation location.
- workitemindex (directory)
- If you are using Derby, copy the repositoryDB directory
tree.
- If you are using Tomcat and have changed the configuration, copy
over the tomcat/conf directory.
- If you are using the Tomcat user database, copy over tomcat-users.xml.
- If you are using Tomcat and you have customized the application
deployment descriptor, copy the modified web.xml file
for jazz.war, located in \JazzTeamServer\server\tomcat\webapps\jazz\WEB-INF.
If you are upgrading to Standard edition, and you have purchased
the Developer Client Activation Kit for Express, purchase and install
the Developer Client Activation Kit for Standard Edition, so that
you can use those client licenses. Your Developer license assignments
will still be in effect, but the Developer licenses will be deactivated
until the correct activation kit is installed.
Installing 1.0.1 Activation
Keys
If you had installed the permanent Server Activation
Key and Client Activation License Keys onto the 1.0 server installation,
obtain and install the 1.0.1 versions of these keys. The server reverts
to a trial license after the upgrade to 1.0.1. Obtain the 1.0.1 activation
keys from Passport Advantage®. Below are
the names of the applicable keys for each server edition:
Express
edition keys:
- IBM® Rational Team
Concert Express
Edition - Server License Activation Kit V1.0.1 Multiplatform
- IBM Rational Team
Concert Express
Edition - Developer Client License Activation Kit V1.0.1 Multiplatform
- IBM Rational Team
Concert -
Contributor Client License Activation Kit V1.0.1 Multiplatform
Standard edition keys:
- IBM Rational Team
Concert Standard
Edition - Server License Activation Kit V1.0.1 Multiplatform
- IBM Rational Team
Concert Standard
Edition - Developer Client License Activation Kit V1.0.1 Multiplatform
- IBM Rational Team
Concert -
Contributor Client License Activation Kit V1.0.1 Multiplatform
Express edition installation overview
The installation package includes everything you need to get started.
The default configuration includes these items:
- The supported versions of a Java™ Development Kit (JDK) for Windows® and Linux®.
- A working image of Apache Tomcat Web application server that contains
the Jazz Web
application.
- A Derby database and all necessary database libraries.
Important:
Using Jazz Team
Server with
a Derby database supports up to 10 users. To support more than 10
users, use a DB2 Express, DB2 or Oracle database. DB2 Express
is included with the Standard and Express edition installation packages
when you use the IBM Installation Manager. If you use the .zip file
installation method, the DB2 Express download is available on the
same site as the Rational Team
Concert download.
After DB2 Express is installed, you must install and configure it
as described in the installation setup guide.
Note:
An optional
planning worksheet is
available within the online help to help you choose your configuration
and record your decisions.
Preparing to install Express edition
Before installing the server verify the special considerations
are met.
Special instructions for Linux
Review the following special instructions when the Jazz Team
Server is installed on Linux.
Installing the Express edition from the IBM Installation Manager
After obtaining the installation files, start the installation.
About this task
The Jazz Team
Server, Rational Team
Concert client, Build System Toolkit, ClearCase® Connector, ClearQuest® Connector and
other incubator files can be downloaded from http://jazz.net. To purchase Rational Team
Concert,
go to http://www.ibm.com/software/awdtools/rtc/,
where you can download an installable image or order a DVD.
- Download one of the following installation packages.
There
are two methods to install Rational Team
Concert Express edition by using IBM Installation Manager.
- Start the launchpad program.
If the Installation
Manager is not running, start it.
Note:
You must have administrator
privileges to run the launchpad program.
- If you are using the Installation Manager Web install,
run the executable file. The files are extracted to a directory and
a launchpad program appears.
- If you are using the Full DVD Contents .zip file, extract
the contents of the archive into a temporary directory and run the
launchpad program.
- To run the file on Windows, run this command:
launchpad.exe
- To run the file on Linux, run this command:
sh launchpad.sh
-
When the launchpad program starts you see
a list of items to install. Install each package that you want to use in the
order listed.
- Install the Jazz Team
Server.
When using the IBM Installation Manager,
note the Installation Directory on the Location page during the installation
process. The directory is referred to as JazzInstallDir.
Note:
If you are planning to use an
existing application server, instead of the included Apache Tomcat
server, clear the Apache Tomcat package check box. Doing so, installs
only the files required to use with your existing application server.
The Installation Manager prompts you to choose a location to install
these files.
- Optional: Install DB2 Express.
Note:
Although a Derby database
is included in the default configuration and requires no installation,
this database cannot support more than 10 users. If you want to support
more than 10 users and do not have access to an existing DB2 or Oracle
database, install DB2 Express
If you
install DB2 Express, record the user ID, password and port number.
This information is needed later. Accepting the defaults during the
installation simplifies the Jazz Team
Server configuration.
- Install the Rational Team
Concert client.
- Optional: Install the Build System Toolkit.
Setting up the database
After your database is installed, configuration work is required.
Fast path:
If you are using the included Derby database no additional
setup is necessary. Proceed to
Starting the server.
The overview steps for setting up a database are:
- Create a database.
- Configure the properties files.
- Create the database tables.
If you are using DB2 or DB2 Express, proceed to Setting up a DB2 database.
If you are using Oracle, proceed to Setting up an Oracle database.
Setting up a DB2 database
Set up a DB2 or DB2 Express database to work with the Jazz Team
Server.
Before you begin
This procedure assumes the following prerequisites have been met.
Consult your DB2 documentation or a DB2 database administrator (DBA) for help.
About this task
To set up a DB2 database:
- Create the database in the DB2 Command Window. The
example commands create a new database called JAZZ. These commands run in
the DB2 Command Window. The Command Window can be opened from the application
Start menu under the DB2 Command Line Tools menu.
Note:
To ensure proper handling of Unicode content, the database character
set must be UTF-8 encoding.
Tip:
If the database is not
running, the command db2start starts DB2.
- Locate the file teamserver.properties in the
directory JazzInstallDir/server and rename it to teamserver.derby.properties.
- Locate the file teamserver.db2.properties in
the directory JazzInstallDir/server and rename it to teamserver.properties.
- Specify the database and connection details in the file teamserver.properties.
The default connection specification connects to a DB2 database that
runs on localhost on port 50000. On Windows, the database is called JAZZ,
and both the user name and password are db2admin. If the default values were
used when setting up your database, the teamserver.properties file might already
be configured correctly. If not, change this information to match your configuration.
- Open the file teamserver.properties in
a text editor.
- Locate the following lines:
com.ibm.team.repository.db.vendor = DB2
com.ibm.team.repository.db.jdbc.location=//localhost:50000/JAZZ:fullyMaterializeLobData=false;user=db2admin;password={password};
com.ibm.team.repository.db.jdbc.password=db2admin
- Edit the value of com.ibm.team.repository.db.jdbc.location
for your DB2 server and database.
Tip:
In
the DB2 Command Window, run the command db2 get dbm cfg,
then find the line that contains SVCENAME, which indicates the DB2 port name
or number. If this command displays a number, use it as the port number (in
place of 50000 in the example above). If the command returns a non-numeric
name, determine what port number was assigned for this name and use that port
number. On Linux, the file /etc/services contains the
mapping between port names and numbers, and on Windows, the file C:\windows\system32\drivers\etc\services contains
the mapping. For more information, ask your database administrator or consult
the database documentation.
- Edit the value of com.ibm.team.repository.db.jdbc.location for
your DB2 user name.
Note:
The DB2 user must have permissions
to create tables, tablespaces, and modify the database configuration. DB2 users
are created by the operating system.
- Specify the user password in the property com.ibm.team.repository.db.jdbc.password.
Note:
Do not change the password={password} text in the com.ibm.team.repository.db.jdbc.location property.
- If necessary, change the property com.ibm.team.repository.db.db2.content.tablespace.location
to a path on your Jazz Team
Server where
the main tablespace can be created.
Note:
If this value is not
changed from the default of content_tablespace, the tablespace is created
under the database storage location. On Windows, if a new path is specified,
it must be specified by using double backslashes, for example: com.ibm.team.repository.db.db2.content.tablespace.location=c:\\db2\\jazz\\content_tablespace.
Results
You are finished setting up your database. Continue with Creating the Jazz Team
Server database
tables.
Setting up an Oracle database
Set up an Oracle database to work with the Jazz Team
Server.
Before you begin
This assumes the following prerequisites have been met. Consult your
Oracle documentation or an Oracle database administrator (DBA) for help.
- Oracle is installed on a machine to be used as the database server.
This machine can be a different one from that on which the Jazz Team
Server runs.
- A default database exists on the Oracle server.
Note:
When you install
Oracle, you have the option to create a database automatically.
Note:
To
ensure proper handling of Unicode content, the database character set must
be UTF-8 encoding.
- The user who performs these instructions has system administration authority
on the Oracle database.
When running Jazz Team
Server on
Oracle, create an Oracle tablespace to improve performance. You must create
a user linked to that tablespace.
Note:
Neither of these steps are performed
by the database builder with the repository tools.
About this task
To set up an Oracle database:
-
Create a tablespace. The tablespace
location must be appropriate to the machine and disk drive.
Note:
The tablespace
can have any of these properties:
- A name other than oracle_tbs
- A location in another directory
- A size larger than 1GB. For large installations, you need to allocate
more space.
The example below shows a create statement executed
on a Windows machine:
CREATE BIGFILE TABLESPACE oracle_tbs DATAFILE 'D:\oracle_tbs\oracle_tbs.dbf' SIZE 1G AUTOEXTEND ON EXTENT MANAGEMENT LOCAL AUTOALLOCATE
Note:
The directory path (in this example D:\oracle_tbs)
must exist. It is not necessary to create a separate special tablespace. You
can use the Oracle default USERS tablespace, but Oracle
performs better with a pre-allocated space on the disk that it manages.
- Create an Oracle user.
After the tablespace is created,
a special Oracle user must be created for Jazz to use the Oracle database.
In this example, the user has the name jazzDBuser
and password (IDENTIFIED BY in Oracle terms) jazzDBpswd and
exists in the tablespace created in 1.
CREATE USER jazzDBuser IDENTIFIED BY jazzDBpswd DEFAULT TABLESPACE oracle_tbs
After
the user is created, grant the database system permissions necessary to perform
these actions:
- Create a session.
- Create, alter, and drop tables and indexes.
- Insert, update, and delete from the tables created.
- Locate the file teamserver.properties in the
directory JazzInstallDir/server and rename it to teamserver.derby.properties.
- Locate the file teamserver.oracle.properties in
the directory JazzInstallDir/server and rename it to teamserver.properties.
- Configure the server
- Open the file teamserver.properties in
a text editor. Locate the following lines; and change the location
and password properties for your configuration:
com.ibm.team.repository.db.vendor = ORACLE
com.ibm.team.repository.db.jdbc.location=thin:jazzDBuser/{password}@localhost:1521/ORCL
com.ibm.team.repository.db.jdbc.location=thin:jazzDBuser/{password}@//oracleserver.example.com:1521/ORCL
com.ibm.team.repository.db.jdbc.password=jazzDBpswd
Note:
If you
are using Oracle Express, change ORCL to XE.
com.ibm.team.repository.db.vendor = ORACLE
com.ibm.team.repository.db.jdbc.location=thin:jazzDBuser/{password}@localhost:1521/XE
com.ibm.team.repository.db.jdbc.location=thin:jazzDBuser/{password}@//oracleserver.example.com:1521/XE
com.ibm.team.repository.db.jdbc.password=jazzDBpswd
Specify
the user password in the property com.ibm.team.repository.db.jdbc.password.
Note:
Do not change the password={password} text in the property com.ibm.team.repository.db.jdbc.location.
-
In the same directory as the server scripts
(JazzInstallDir/server),
create a directory named oracle.
- Locate the Oracle JDBC driver JAR file, named ojdbc14.jar.
The location can vary depending on the Oracle product and operating system.
Copy this file to the directory named oracle.
Note:
If you are using WebSphere® Application Server, configure a property
named "ORACLE_JDBC"; then set it to the absolute file path (not URL) to the
Oracle JDBC drivers. This task is described in the WebSphere Application Server setup
instructions. Make a note of the file path for later use in these instructions.
Results
You are finished setting up your database and can continue with Creating the Jazz Team
Server database
tables.
Setting up a SQL Server database
Set up a SQL Server database to work with the Jazz Team Server.
This procedure assumes that the following prerequisites have been met:
Note:
The default login name defined in JazzInstallDir/server/teamserver.properties file
for a SQL Server database is jazzDBuser and the default
password is jazzDBPswd. These values are used in the
steps below for creating a database. You can substitute these values with
the user name and password for your database.
Setting up a database
Note:
This section describes
how to set up the SQL Server database by using the command line tool sqlcmd,
which is provided with the SQL Server installation. You can also use a visual
tool, such as SQL Server Studio Management, which is also available for the Express version
as SQL Server Studio Management Express. See the SQL Server documentation
or an SQL Server database administrator (DBA) for more information.
To
set up an SQL Server database by using the command tool sqlcmd:
- Create a Jazz Team Server database.
From the command line tool, type:
CREATE DATABASE jazz
GO
- Create a user and password and change the ownership of the Jazz Team Server database. From the command line tool, type:
CREATE LOGIN jazzDBuser
WITH PASSWORD = 'jazzDBPswd';
USE jazz;
exec sp_changedbowner 'jazzDBuser'
GO
- Change the collation of the Jazz Team Server database.
From the command line tool, type:
ALTER DATABASE jazz COLLATE SQL_Latin1_General_CP437_CS_AS
GO
Configuring the server
Note:
By default, the teamserver.properties file
in JazzInstallDir/server directory is not set up to connect
to a SQL Server database. All default settings, along with SQL Server-specific
settings, are contained in the teamserver.sqlserver.properties file
in the same directory.
To configure the server:
- Rename the following files:
- Rename the JazzInstallDir/server/ teamserver.properties file
to teamserver.OtherDBProvider.properties
- Rename the teamserver.sqlserver.properties file to teamserver.properties
Note:
Renaming the original teamserver.properties file
enables you to restore the file to the previous working version. By default,
the DB Provider is derby.
- Edit the server configuration file if you used a different user name,
password, or db name, installed SQL Server on a different machine than Jazz Team Server,
or are using a port other than the default. Open the file teamserver.properties in JazzInstallDir/server directory, and change the information listed below to match your setup.
com.ibm.team.repository.db.vendor = SQLSERVER
com.ibm.team.repository.db.jdbc.location=//SQL SERVER MACHINE IP:SQL SERVER TCIP PORT;databaseName=JAZZ DATABASE NAME;user=JAZZ USERNAME;password={password}
com.ibm.team.repository.db.jdbc.password=JAZZ LOGIN PASSWORD
- Locate the SQL Server JDBC driver JAR file, named sqljdbc.jar.
The location can vary depending on where the drivers were installed, as noted
in the prerequisites section.
- Specify the JDBC JAR file location for JDBC by completing one of the following
tasks:
- Copy the JDBC drivers JAR file into JazzInstallDir/server/sqlserver directory
- Set up the environment variable SQLSERVER_ABSPATH to
point to the directory that contains the JAR file
Note:
If you use WebSphere Application
Server, configure a property named SQLSERVER_JDBC; then
set it to the absolute file path (not URL) to the SQL Server JDBC drivers
directory. For more information, see the WebSphere Application Server setup
instructions. Note the file path for later use in these instructions.
You have completed setting up your database. Now, create the Jazz Team Server database
tables. For more information, see Creating the Jazz Team
Server database
tables.
Troubleshooting
If the repotools command does not
succeed, check the log file named repotools_createTables.log,
located in the JazzInstallDir/server directory.
Also,
verify the following:
- The SQL Server is configured to allow connections using the TCP/IP protocol.
If required, restart the SQL service.
- The SQL Server machine host name, and the port is correctly reflected
in the teamserver.properties file.
- The login name, password, and database name are properly reflected in
the teamserver.properties file.
- A firewall does not prevent you from accessing the SQL Server. Use a telnet
command to telnet to the machine using hostname and port from the teamserver.properties file.
- The created user has proper permissions in the Jazz Team Server database.
Note:
The database code for Jazz Team Server was
designed to be generic and standard in order to run on multiple database platforms;
however, differences between the enterprise database vendors exist in syntax,
optimization strategies, and locking semantics. The server has been tested
on SQL Server using a combination of automated tests and simulations of normal
workloads and stress testing. The simulation of normal workloads showed acceptable
performance. In some instances database deadlocks have been observed in automated
concurrency tests; however, these have not been consistently reproduced on
different server hardware.
The server is designed to service a large number
of simultaneous requests. In exceptional cases, deadlocks can occur in the
repository database, as similar or equal objects are updated concurrently
in transactions associated with the requests. These are rare, but normal events.
The system is designed to be defensive against this, and data integrity is
maintained; there is no loss of data. Occasionally, deadlocks are logged by
tasks, such as build engine execution. Generally, the condition is detected,
and the task is re-tried. The deadlock can result in a failed build. In very
rare cases, it can be a user action, such as working with work items or source
code, that is aborted to resolve a deadlock. In that case, the user action
fails and an error with details regarding a deadlock is displayed to the user.
The user can then retry the action.
All deadlocks encountered are logged
on the server to provide information about what happened when the deadlock
occurred. The log entry has text similar to the following: com.ibm.team.repository.common.RetryableDatabaseException:
Serialization failure.
If your system encounters deadlocks,
see the error log, which is available at https://servername:9443/jazz/service/com.ibm.team.repository.common.internal.IFeedService?category=SystemLog.
If you encounter frequent deadlock exceptions, contact your product
support, or check the forums on jazz.net for the latest information, updates,
or mitigating techniques.
Creating the Jazz Team
Server database
tables
Create the database tables using the repository tools.
About this task
To create the database tables:
- Run the command repotools -createTables to
create the database tables for a Jazz repository.
The repotools
file is located in JazzInstallDir/server.
The
command uses the configuration properties in teamserver.properties for
the connection and size settings. By default, the command looks in the current
directory. The parameter teamserver.properties can
be used to reference a different properties file.
This command creates the tablespace and all the required tables and
indexes for a Jazz Team
Server repository.
- After the database tables are created, you must stop and restart
the database to make sure all changes are in effect.
Tip:
Example
commands that stop and start DB2 are db2stop and db2start.
These commands are run at the DB2 Command Window. The Command Window can
be opened from the application start menu under the DB2 Command Line Tools cascade menu.
Results
You are finished setting up your database and can continue with Starting the server.
Starting the server
This topic describes the different options for running the server
startup scripts.
About this task
If you plan to use the included Apache
Tomcat application server, you are ready to start the Jazz Team
Server.
If you plan to use the WebSphere Application
Server, set up your server environment as described in Setting up a WebSphere Application Server.
Starting the Apache Tomcat server
You are now ready to start the Apache Tomcat server.
Apache Tomcat has been installed in the
directory JazzInstallDir/server/tomcat.
The Web application (jazz.war) has been installed
in the Apache Tomcat directory webapps. In a
command window, set your current directory to JazzInstallDir/server.
The server startup and shutdown scripts are located in this directory.
- If you want to run the start and stop scripts from any other directory,
you must change the profiles.ini file in JazzInstallDir/server/provision_profiles
to use an absolute path.
- Apache Tomcat is configured to use the ports 9080 and 9443 in
file JazzInstallDir/server/tomcat/conf/server.xml.
If necessary, change them as appropriate for your system. If necessary,
also update the configuration settings of Jazz server Repository HTTP
ports in the Advanced Properties configuration page of in the Jazz
Admin Web UI.
- The directory JazzInstallDir/server/tomcat/logs
contains the server log files. If you have trouble starting the server,
check the log files.
Starting the server on Windows
Run the startup file to start your server on Windows.
About this task
- To start the server, from the JazzInstallDir/server directory,
run this command:
server.startup.bat
Note:
A
separate Apache Tomcat console window opens. Do not close this window
or the server will stop working. Also, several informational messages
launch, including a message about the Apache Tomcat Native Library.
These informational messages do not affect the Jazz Team
Server functionality.
- To stop the server, from the JazzInstallDir/server directory,
run this command:
server.shutdown.bat
What to do next
Note:
The example above runs the start
and stop scripts directly from the directory JazzInstallDir/server.
If you installed Jazz Team
Server using IBM Installation
Manager, you can also run the commands from the Jazz Team
Server Windows start menu.
After
the server is started, proceed to Running the setup wizard.
Starting the server on Linux
Run the startup file to start server on Linux.
About this task
- To start the server, from the JazzInstallDir/server directory,
as user root, run this command:
./server.startup
If
your user ID has administrator access, run this command:
sudo ./server.startup
A separate Apache Tomcat console window is not visible. You
can check the server startup progress by viewing the log file at JazzInstallDir/server/tomcat/logs/catalina.out.
- To stop the server, from the JazzInstallDir/server directory,
as user root, run this command:
./server.shutdown
If
your user ID has administrator access, run this command:
sudo ./server.shutdown
What to do next
Note:
This example runs the start and
stop scripts directly from the directory JazzInstallDir/server.
If you installed Jazz Team
Server by
using IBM Installation Manager, you can also run the
commands from the Jazz Team
Server application
start menu.
After
the server is started, proceed to Running the setup wizard.
Setting up a WebSphere Application Server
This topic describes how to set up the Jazz Team
Server to
work with WebSphere Application Server. This setup
assumes that you are installing the Jazz Team
Server on
the same machine as the Websphere Application Server.
Before you begin
Before beginning these steps, you should have
the following completed:
- WebSphere Application server is already
installed.
- The database is created and the teamserver.properties file
is updated with your database settings.
- Refer to your WebSphere documentation for
security setup and turn off the case-insensitive property.
Note:
Although
Websphere and many LDAP directories allow you to log in case-insensitive, Jazz Team
Server stores
user records with user IDs in exact case as they are imported. When
you log in to the Jazz Team
Server,
the user record is retrieved from the list of users and the case must
match exactly.
- Java 2 Security option should be turned off.
If this option is turned on in WebSphere Application Server it will
cause the Jazz Team
Server .war
to fail to start.
- The Jazz Team
Server includes
the files required to run a complete Apache Tomcat-based server. For
a WebSphere installation you only need a
subset of the Jazz Team
Server files
and you should place them in a directory on your WebSphere server
machine. Further instructions refer to this as the Jazz Team
Server installation
directory, or JazzInstallDir for
short. From this directory, use:
- The file JazzInstallDir/server/teamserver.properties.
- The file JazzInstallDir/server/log4j.properties.
If you use a Websphere Application Server, in this file you can change
the path for the jazz.log file, which only logs messages from the Jazz Team
Server.
The default path is tomcat/logs/jazz.log.
- The file JazzInstallDir/server/tomcat/webapps/jazz.war.
- The directory JazzInstallDir/server/provision_profiles.
- The directory JazzInstallDir/server/update-site.
- The default repository database in JazzInstallDir/repositoryDB.
- The repository tools in JazzInstallDir/repotools.
Tip:
When using the IBM Installation
Manager the Jazz Team
Server files
can be installed into a Web application directory. During the installation
process, you should not install the included Apache Tomcat application
server; this makes the Installation Manager ask for a Web Application
directory and install only the files needed for WebSphere.
The default directory is C:\Program Files\IBM\JazzTeamServer on Windows or /opt/IBM/JazzTeamServer on Linux.
The installation directory is referred to as JazzInstallDir in
this procedure. If you use the IBM Installation Manager to install
the files into the WebSphere Application Server
Web applications directory, then you do not need to manually move
the files as described above.
About this task
Note:
This document does not teach the configuration
of WebSphere authentication or SSL, which
is a complex topic. Detailed information about the various authentication
and encryption options for WebSphere is covered in the WebSphere Information Center. For more
information, go to the
WebSphere Information Center and
search for
Securing applications and their environment.
The Jazz Web UI requires that authentication be
configured in order to perform authorization and personalize the application.
- Modify the profile.ini and license-profile.ini files:
Edit each of profiles in JazzInstallDir/server/provision_profiles/
and set an absolute path for the URL property.
For example,
Note:
The directory JazzInstallDir/server/provision_profiles/
must only contain the .ini files included and must not contain any
backup files. Some editors automatically save a backup file which
must be removed.
- Review and update the database location in the teamserver.properties file
com.ibm.team.repository.db.vendor = DB2
com.ibm.team.repository.db.jdbc.location=//localhost:50000/JAZZ:fullyMaterializeLobData=false;user=db2admin;password={password};
com.ibm.team.repository.db.jdbc.password=db2admin
- Verify or update the WebSphere Application
Server level.
Jazz Team
Server requires WebSphere Application Server Version 6.1
with the IBM Java SDK
1.5 SR5 or later Cumulative Fix applied. The IBM Java SDK 1.5 SR6 SDK update is available from http://www-1.ibm.com/support/docview.wss?rs=180&uid=swg24017492. With WebSphere 6.1
and the GA IBM Java SDK, Jazz
starts to report "proxy errors" after some number of operations.
- Update the JVM arguments.
The Jazz Team
Server needs
some specific settings on the Java Virtual
Machine in which it is run.
First, it needs to know where to
find the configuration files for the server and for log4j, the logging
framework used by the server. This is done by setting the system properties
com.ibm.team.server.configURL and log4j.configuration. These properties
use a URL rather than a simple path, so the value should be specified
as a file://-style URL.
The second property which is required
for the Jazz JVM is to provide it with more than the
default maximum memory allocation, using the -Xmx setting. This should
be set based on the size of the team supported by the server and the
memory capacity of the server where Jazz Team
Server is
running. A typical medium-size team can use a value of -Xmx1000M,
providing 1000 MB of heap memory for the Jazz Team
Server process.
If
you are connecting to an Oracle database then you need to add a property
named "ORACLE_JDBC". Set the property to the absolute file path (not
a URL) to the Oracle jdbc drivers.
There are a couple other
system properties which need to be set to control some behavior of
the server, they are included below. Here are the specifics of setting
these JVM properties in the WebSphere Administrative Console,
substitute JazzInstallDir with
your Jazz Team
Server installation
directory:
- Click on Servers -> Application Servers.
- Click on server1.
- Click on Java and Process Management -> Process Definition.
- Click on Java Virtual Machine.
- Add the value 100 to the Initial Heap.
- Add the value 1000 to the Maximum Heap Size.
- Click Apply.
- Click Logging and Tracing. Click Change
Log Detail Levels. The Jazz Team
Server uses
the BIRT reporting engine. To prevent BIRT informational entries from
being written to the WebSphere log file, set the logging level to severe for
the org.eclipse.birt.* packages. Click Apply.
- Click Custom Properties
- Add the following properties: Click New;
enter the Name and Value;
then click OK.
- Click Save directly to the master
configuration.
- Restart Websphere to install the Jazz Application
In the following command line examples, WASInstallDir
represents the location where WebSphere Application Server
is installed on your server.
- On Windows, the default value for WebSphere installation
directory is:
C:\Program Files\IBM\WebSphere\AppServer
You
can restart the server with the following commands on Windows:
cd WASInstallDir\bin
stopServer.bat server1 [for a secure server, include: -username {LDAP_User} -password {LDAP_Password}]
startServer.bat server1
- On Linux, the default value for WebSphere installation
directory is:
/opt/IBM/WebSphere/AppServer
You
can restart the server with the following commands on Linux:
cd WASInstallDir/bin
./stopServer.sh server1 [for a secure server, include: -username {LDAP_User} -password {LDAP_Password}]
./startServer.sh server1
- Open the Admin console for your WebSphere Application
Server.
- Click on Applications -> Install New Application.
- Under Path to new Application,
click Local file system.
- Under Full path enter:
JazzInstallDir/server/jazz.war
- Set Context Root to /jazz.
- Click Next and continue through
the remaining Install New Application steps.
- Click Finish.
- Click Save directly to the master
configuration.
- Click on Applications -> Enterprise Applications.
- Select the box next to jazz_war; click Start.
A green arrow should appear indicating the application
started successfully.
What to do next
After the server is started, proceed to Running the setup wizard.
Running the setup wizard
Running the setup wizard verifies
that the server is operating properly and guides you through the steps
configure the server.
About this task
To verify that the Jazz Team
Server is
connecting to the database, look at the server log or console output.
The connection and database information is echoed on its first access.
The directory JazzInstallDir/server/tomcat/logs
is used for the server log files.
This procedure assumes your
server is available using the hostname localhost and the default ports
9443. If necessary, replace localhost with your server hostname and
replace the port 9443.
Start the setup wizard to configure your server. Use the
URL https://localhost:9443/jazz/setup.
The default user name and
password are case-sensitive:
- The user name is ADMIN.
- The password is ADMIN.
If you configured the LDAP directory Web container, log in with
a JazzAdmin user that is defined in your LDAP directory.
Choose a setup path. The setup wizard has two main
paths.
- The Fast Path Setup uses the default configuration. If
you want to get the server running quickly, the fast path setup is
a good option. During the Fast Path Setup, setup
- The Custom Setup guides you through the detailed server
configuration, including the ability to enable e-mail notifications.
During the Custom Setup, you set up the following items:
- Database
- E-mail notification
- User registry
Note:
By default, the server is configured to use Derby as the
database. To use another database, such as DB2, select the custom
setup path and complete Step 2: Configure Database.
When the initial setup is complete, additional options
can be configured from the Jazz Team
Server Admin
Web user interface by using the URL https://localhost:9443/jazz/admin.
What to do next
If the server setup wizard does not
load, check the following items:
- Verify that the application server has started. Use the URL http://localhost:9080.
- Verify the Jazz Team
Server has
started by logging in to the Jazz Team
Server Admin
Web UI using the URL https://localhost:9443/jazz/admin.
If the page does not load or the server has errors, the server did
not start correctly. See the troubleshooting
information at Troubleshooting server issues.
- The URI root for the Jazz Team
Server path
must be /jazz. For example https://example.com:9443/jazz must be used
rather than https://example.com:9443.
Completing the installation
After the server is installed, you must consider some configuration
options before continuing.
About this task
After the installation, there are a few additional actions to take.
- Some files contain passwords. Those files should be protected so
that they are readable only by users authorized to know the password for the
accounts.
- teamserver.properties - The Jazz Team
Server requires that the database password is stored in JazzInstallDir/server/teamserver.properties.
When
properties files are saved, the application always makes a backup
copy of the previous version in the same directory. If you want to
remove all files that contain the clear-text password, remove the
backup properties files after configuring the server for the first
time.
- When connecting to the server with the Rational Team
Concert client or a Web browser, you might see security certificate warnings.
To disable the warning, see Configuring security certificate
settings.
- If you configured the application server to use ports other than the
defaults, these ports should also be configured in the Jazz configuration.
These port numbers are used for composing URLs for things like feed links
and item links in email notifications. To update the defaults, use the advanced
properties configuration page of the Admin Web UI to modify the following
properties:
- com.ibm.team.repository.servlet.internal.ServletConfigurationService
- Repository HTTP port
- Repository HTTPS port
- com.ibm.team.repository.service.internal.webuiInitializer.ConfigPropertyInitializer
- URL HTTP Port
- URL HTTPS Port
- You are now ready to connect to the server with the Rational Team
Concert client or a Web browser.
Installing the client using the IBM Installation
Manager
The client is distributed as a downloadable file via the IBM Installation
Manager.
About this task
Note:
If
you want to install the client into an existing Eclipse workbench,
use the IBM Installation Manager. The IBM Installation Manager install
prompts you for the workbench you want to extend and takes care of
managing future workbench updates, rollbacks, and modifications
Note:
If Security-Enhanced Linux (SELinux) is enabled, you
must disable
it or change the security context of the Java Runtime Environment (JREs) to
allow text relocation in order to install and run Rational Team Concert. For
more information, see
Installing Rational Team
Concert with
Security-Enhanced Linux.
- Download one of the following installation packages.
There are three methods to install theRational Team
Concert client.
- Start the launchpad program.
If the Installation
Manager is not already running, complete the following steps to start
it.
Note:
You must have administrator privileges to run the launchpad
program.
Note:
The Linux commands to start the launchpad program
are only for the Rational Team
Concert for
Eclipse IDE.
To start the launchpad program file
on:
- If you are using the Client CD Contents .zip file,
extract the contents of the archive into a temporary directory and
run the launchpad program. To start the launchpad program file on:
- To run the file on Windows, run this command:
launchpad.exe
- To run the file on Linux, run this command:
sh launchpad.sh
- If you are using the Installation Manager Web install,
run the executable file. The files are extracted to a directory and
a launchpad program appears. To start the executable file on:
- If you are using the Full DVD Contents .zip file, extract
the contents of the archive into a temporary directory and run the
launchpad program. To start the launchpad program file on:
- To run the file on Windows, run this command:
launchpad.exe
- To run the file on Linux, run this command:
sh launchpad.sh
- You can install the following clients:
- To install Rational Team
Concert client
for Eclipse, click Rational Team
Concert Client
for Eclipse IDE link.
- To install Rational Team
Concert client
for Microsoft Visual Studio, click Rational Team Concert Client for Microsoft® Visual Studio IDE link.
The Installation Manager wizard is displayed.
The wizard guides you through to install the client.
- Start the client by clicking the Rational Team
Concert shortcut
created by the installation.
- Connect to the server. The
easiest way to connect to a server is using the Team Invitation. If
you do not have an invitation you can connect manually.
- Click File -> Accept
team invitation. The wizard guides you through
the process.
Note:
If you do not have an invitation you
need the URI or URL from your server admin. (an example format is:
https://example.com:9443/jazz). Click on the connecting
to an existing project area hyperlink that appears in
the bottom right corner of the Accept Team Invitation window.
- Follow the instructions in the wizard to set up your
connection.
Example
Trouble
Shooting: Here are some suggested problem management techniques.
- Start with an empty workspace.
- The client and the server builds must match. Make sure the build
ID's match for both the client and server distributions.
- Make sure the server is up. Confirm using the status URL: https://example.com:9443/jazz.
- On Linux, if you want to start the client from outside of the
directory JazzInstallDir/client/eclipse you
must change each file in JazzInstallDir/client/eclipse/links/
and include the absolute path to the named directory. By default,
relative paths are used. For example, JazzInstallDir/client/eclipse/links/build.link contains
the text "path=jazz/build". If your client is
installed in the directory /home/username/teamconcert, edit the file
to look like "path=/home/username/teamconcert/jazz/client/eclipse/build".
What to do next
After
you have successfully installed the client, you should refer to the
following topics to help you get started with Rational Team
Concert.
The Build System Toolkit can
be installed on the build machines using the IBM Installation Manager.
About this task
- Start the launchpad program.
If the Installation
Manager is not running, start it.
Note:
You must have administrator
privileges to run the launchpad program.
- If you are using the Installation Manager Web install,
run the executable file. The files are extracted to a directory and
a launchpad program appears.
- If you are using the Full DVD Contents .zip file, extract
the contents of the archive into a temporary directory and run the
launchpad program.
- To run the file on Windows, run this command:
launchpad.exe
- To run the file on Linux, run this command:
sh launchpad.sh
- When the launchpad program appears, click on the Build System Toolkit to
start the installation process.
- After the installation is complete a build should be configured. More information about the Build System Toolkit can be found in About Jazz team build.
Installing Rational Team
Concert with
Security-Enhanced Linux
If Security-Enhanced Linux (SELinux) is enabled, you must either
disable it or change the security context of the Java Runtime Environments (JREs)
used for installing and running Rational Team
Concert to allow text relocation.
About this task
If you have setup a machine for the sole purpose of evaluating Rational Team
Concert and
the SELinux features are not important to you, then the easiest way to proceed
is to disable SELinux.
Note:
- SELinux is installed and enabled by default on Red Hat Enterprise Linux 5.
- SELinux is not installed on Suse Linux Enterprise Server 10 or Suse Linux Enterprise
Desktop 10.
- To disable SELinux do one of the following:
- From the windowing system:
- Select System -> Administration -> Security Level and Firewall.
- Switch to the SELinux tab.
- Change the SELinux setting to Disabled.
- Click OK to save the new setting.
- From the command line:
- Run the "setup" command (this is /usr/bin/setup)
- Select Firewall Configuration and press Enter
- Use the Tab and arrow keys to change the SELinux to
Disabled
- Select OK and press Enter
-
To change the security context of the JREs:
-
If you are installing directly from DVD media;
skip to step 2.
Otherwise, change the security context of the installation JRE.
- In the installation files directory, locate the directory jre. linux/jre_5.0.2.sr5_20070511/jre.
If you extracted the installation files to /tmp/rtc then the directory jre
is located at /tmp/rtc/linux/jre_5.0.2.sr5_20070511/jre.
- Run the command chcon -R -t textrel_shlib_t against the jre directory.
This command recursively processes the files and allows text relocation. For
example, if you extracted the installation files to /tmp/rtc run the following
command:
chcon -R -t textrel_shlib_t /tmp/rtc/linux/jre_5.0.2.sr5_20070511/jre
-
Install the Rational Team
Concert server, client and connectors, but do not start them.
- Before you start Rational Team
Concert, you must change the security context of the product JREs. For each product
you install, run the same command (chcon -R -t textrel_shlib_t) with the appropriate
product-specific JRE directory. The default directories are listed below.
Note:
The paths are the default if you installed the product as user
root. If you installed as a non-root user, look for these directories inside
an opt/IBM structure in the installation user's home directory.
- IBM Installation
Manager:
- /opt/IBM/InstallationManager/eclipse/jre_5.0.2.sr5_20070511/jre
- Jazz Team
Server:
- /opt/IBM/JazzTeamServer/server/linux/ibm-java2-i386-50/jre
- Rational Team
Concert -
Client: (run chcon on all 4 directories)
- /opt/IBM/TeamConcert/jdk/bin
- /opt/IBM/TeamConcert/jdk/lib
- /opt/IBM/TeamConcert/jdk/jre/bin
- /opt/IBM/TeamConcert/jdk/jre/lib
- Rational Team
Concert - Build System Toolkit:
- not applicable (no JRE included)
- Rational Team
Concert - ClearCase Connector:
(run chcon on all 4 directories)
- /opt/IBM/ClearCaseConnector/jdk/bin
- /opt/IBM/ClearCaseConnector/jdk/lib
- /opt/IBM/ClearCaseConnector/jdk/jre/bin
- /opt/IBM/ClearCaseConnector/jdk/jre/lib
- Rational Team
Concert - ClearQuest Connector:
- /opt/IBM/ClearQuestConnector/gateway/linux/ibm-java2-i386-50/jre