This information is for planning purposes only. The information herein is subject to change or removal without notice before the products described may become available.

Interactive installation guide

Select the options that apply to your environment to generate a customized installation guide for () applications.

For information on installing the applications on , see Special considerations for installing on .

Are you setting up a clustered environment for ?

Select the operating system for your application server:

Select the setup method:

Select one or more applications to install:

  • Optional applications (separate license)

  • Architecture Management

  • Important: Starting in version 7.0, the application is removed from the solution as a standalone application and is replaced by an extension to the application. Select this option to install the Architecture Management Domain Extension for . The application must be installed together with the extension, or prior to installing the extension. Also, both the application and the Architecture Management Domain Extension for must be at the same version.

    Supporting applications

  • Important: Install the if you want to enable project areas to use configurations of versioned artifacts.

    must be installed on the same server as .

  • Security server

Select your database server:

Select your user registry type:

Are you configuring a data warehouse?

To install the applications follow these steps:

Planning checklist

Before you install the applications, ensure to review the information in the following planning checklist.

  Planning task More information
Verify that your hardware and software meet the minimum system requirements.

Starting in version 6.0.6.1, the required Java version is 8.

System requirements
Get the product installation media. For local repository download, you need approximately five gigabytes (5 GB) of hard drive space to download and extract your product installation media. The server installation files can be downloaded from jazz.net
Review your installation topology. Whether you are trying out the , or installing the solution in your production environment, click the link at the right to see and study different installation topology examples. The examples include: evaluation topology, departmental topology, and distributed enterprise topology. Installation process and topology examples
Synchronize the clocks on all machines. In a distributed environment, ensure that the clocks on all machines are synchronized using the Network Time Protocol (NTP). For more information about NTP, visit the Network Time Protocol website
Learn about licensing. The licensing scheme for version 6 is role-based. When you purchase a role-based license, you will have read, write, and comment access to some or all of the capabilities of the , , and applications. Client access license management
Learn about query and search index management. These Deployment wiki articles discuss different applications index query information and how it is realized in your deployment. In addition, the second part discusses different administering tasks related to index management and index storage details.

Part 1: Query, search and indexing technologies in

Part 2: Indices storage and management (backup, recovery and recreation)

Learn about SMTP server issues. Starting in version 6.0.3, Apache Geronimo project javax.mail library is used instead of Oracle javax.mail library for email settings. This might have an impact if your system has a firewall between the SMTP server and , and also you have a monitoring solution such as MailGaurd that monitors the SMTP traffic. Troubleshooting the SMTP server

Installation process and topology

Planning your environment is critical during the installation process, particularly if you plan to use this installation for departmental or enterprise development. See Examples: Installation process and topology to learn about different installation process and topologies.

Example topology: Single-server evaluation

A common topology for deployment is a single-server () evaluation topology with Liberty and Derby. This topology is useful for small deployments, such as evaluation, demonstration, or training deployments because the Derby database has a 10-user limit.

Example topology: Standard single-server departmental

A common installation topology is a standard single-server deployment of a () departmental topology with and an enterprise database management system, such as IBM Db2, Db2 for z/OS, and Db2 for i.

Example topology: Distributed enterprise

A common installation topology is a distributed deployment of a () enterprise topology with and an enterprise database management system, such as IBM Db2, Db2 for z/OS, or Db2 for i.

Requirements for a clustered environment

To set up a clustered environment for your applications, you need the following servers:

To set up a system with HAProxy high availability, you need the following servers:

All servers in the environment must have their fully qualified host names configured. When you update the /etc/hosts file, use the IP fully-qualified-host-name alias [,alias] format. Note that the fully qualified host name must appear before any alias. If it does not, clustering might not be enabled for multiple nodes.

For a list of system requirements, see System requirements.

Set up a clustered environment

 

Set up the HAProxy load balancer

Note: Installation of HAProxy load balancer is not supported on Windows platforms.

You must install and configure HAProxy before the cluster can be activated. For more information about HAProxy, see www.haproxy.org.

Note: You can also configure and use IHS instead of HAProxy, but only one of these two methods must be used in a cluster for load balancing.

I. Installing a non-Dockerized version of HAProxy

HAProxy is part of the official Red Hat Linux repository and can be installed by using the yum command. You must have root user permissions or use the sudo command to do the installation.

  1. To install HAProxy, open a command shell and enter the following command:

    yum -y install haproxy

  2. By default HAProxy is installed in the /usr/local/haproxy/etc/haproxy directory. Go to the HAProxy installed directory and back up the haproxy.cfg file. For example, create a haproxy.cfg.backup file.
  3. Open the haproxy.cfg file for editing and configure it as needed. Use the following example as a reference. For more details about configuration language and available options, see the HAProxy Configuration Manual.

    Note: If your is fronted by the HAProxy, see this Depolyment wiki document for the haproxy.cfg sample file.

    haproxy.cfg sample file

    #---------------------------------------------------------------------
    # Example configuration for a possible web application. See the
    # full configuration options online.
    #
    # http://haproxy.1wt.eu/download/1.6/doc/configuration.txt
    #
    #---------------------------------------------------------------------

    #---------------------------------------------------------------------
    # Global settings
    #---------------------------------------------------------------------
    global
    # If not using the dockerized version,
    # to have these messages end up in /var/log/haproxy.log you will
    # need to:
    #
    # 1) configure syslog to accept network log events. This is done
    # by adding the '-r' option to the SYSLOGD_OPTIONS in
    # /etc/sysconfig/rsyslog
    #
    # 2) configure local2 events to go to the /var/log/haproxy.log
    # file. A line like the following can be added to
    # /etc/sysconfig/rsyslog
    #
    # local2.* /var/log/haproxy.log
    #
    # 3) uncomment the line below and comment the other log line
    #log 127.0.0.1 local2
    log /dev/log local2

    chroot /var/lib/haproxy
    pidfile /var/run/haproxy.pid
    maxconn 6000
    user haproxy
    group haproxy
    daemon

    # turn on stats unix socket
    stats socket /var/lib/haproxy/stats

    tune.ssl.default-dh-param 2048

    #---------------------------------------------------------------------
    # common defaults that all the 'listen' and 'backend' sections will
    # use if not designated in their block
    #---------------------------------------------------------------------
    defaults
    mode http
    option dontlognull
    option http-keep-alive
    option redispatch
    retries 3
    timeout http-request 10s
    timeout queue 1m
    timeout connect 10s
    timeout client 2h
    timeout server 2h
    timeout http-keep-alive 10s
    timeout check 10s
    maxconn 6000

    #---------------------------------------------------------------------
    # main frontend which proxys to the backends
    #---------------------------------------------------------------------
    frontend lanneluc-proxy
    bind *:80
    bind *:9443 ssl crt /etc/haproxy/ssl/proxy.pem no-sslv3
    log global
    option httplog
    mode http
    capture cookie SERVERID len 32
    redirect scheme https if !{ ssl_fc }
    maxconn 2000 # The expected number of the users of the system.
    # Limits the sockets to this number of concurrent connections. Extraneous
    # connections will remain in the system's backlog until a connection is
    # released. If unspecified, the limit will be the same as the frontend's
    # maxconn.
    default_backend ccm


    backend ccm

    option forwardfor
    http-request set-header X-Forwarded-Port %[dst_port]
    http-request add-header X-Forwarded-Proto https if { ssl_fc }
    fullconn 1000 # if not specified, HAProxy will set this
    # to 10% of 'maxconn' specified on the frontend

    balance leastconn
    cookie SERVERID insert indirect nocache

    # minconn = 100, the server will always accept at least 100,
    # but no more than 'maxconn' connections. Should be the same as CCM Liberty
    # settings in server.xml
    # maxconn = 500, the max number of connections that will be sent to a server.
    # The overage will be queued. The total for all nodes should be equal to maxxcon
    # on 'frontend'
    server ccm1 node1.host.com:9443 minconn 100 maxconn 500 ssl check cookie ccm1 verify none
    server ccm2 node2.host.com:9443 minconn 100 maxconn 500 ssl check cookie ccm2 verify none
    server ccm3 node3.host.com:9443 minconn 100 maxconn 500 ssl check cookie ccm3 verify none
    server ccm4 node5.host.com:9443 minconn 100 maxconn 500 ssl check cookie ccm4 verify none

    # Uncomment the following section if your MessageSight is fronted by HAProxy (for example if in High Availability mode)
    #
    # # connect MessageSight cluster in tcp mode (N servers if HA mode, or a single server if IoT MessageSight just must be fronted by proxy)
    # listen MessageSight
    # bind *:1883
    # mode tcp
    # balance leastconn
    # option tcplog
    # server MessageSight1 [MessageSight server 1 URI]:1883 check
    # server MessageSight2 [MessageSight server 2 URI]:1883 check
    # # connect MessageSight cluster in HTTP mode to allow gathering of MQTT statistics (6.0.6 and newer only) (N servers if HA mode, or a single server if IoT MessageSight just must be fronted by proxy)
    # listen MessageSight_REST
    # bind *:9089 ssl crt /etc/haproxy/ssl/msigh.pem no-sslv3 # Port (9089) must match that configured in MessageSight, and the same port needs to be specified in MQTTStatsService advanced property
    # mode http
    # option tcp-check # Must tell HAProxy to use TCP port to do health checks
    # balance leastconn
    # # Same number of entries and same servers as in the section above:
    # server MessageSight_REST1 [MessageSight server 1 URI]:9089 check port 1883 # Same ports (1883 and 9089) as used elsewhere in this file.
    # server MessageSight_REST2 [MessageSight server 2 URI]:9089 check port 1883 # Same ports (1883 and 9089) as used elsewhere in this file.

    listen statistics
    bind *:1936
    stats uri /
    stats admin if TRUE
    stats enable
    stats hide-version
    stats auth root:clu8ter8
    stats refresh 5s

    You must ensure that several important entries in the configuration file are entered correctly:

    • /etc/haproxy/ssl/proxy.pem: This references the certificate that must be available to HAProxy so the proxy server can examine SSL-encrypted traffic. This ability is required for session affinity, which is an important component of clustering in .
    • balance leastconn: This is the balancing strategy. The cookie SERVERID insert indirect nocache setting ensures that the user login information is passed between different sessions. Without this setting, the user will be required to log in again after navigating to any URL that requires user validation.
    • Back-end servers: Replace ccmx with your application names and nodex.host.com:9443 with your server URLs.
    • minconn, maxconn, fullconn: The minimum connection, maximum connection, and full connection parameters.
    • Administration interface:

      listen statistics
      bind *:1936
      stats uri /
      stats admin if TRUE
      stats enable
      stats hide-version
      stats auth root:clu8ter8
      stats refresh 5s

      These entries are explained in details in the next sections.

  4. Open a command shell and enter the following command to enable the service:

    systemctl enable haproxy

  5. Enter the following command to start the service:

    service haproxy start

II. Installing a certificate

HAProxy requires a certificate to parse encrypted traffic. You can use a self-signed certificate. The following commands create a self-signed certificate for your testing environment, but you must obtain a real certificate if required.

OpenSSL prompts you to enter the details for the certificate, such as the host name and so on. Double quotation marks are optional. The host name (CN) is the host name of the server where HAProxy is installed:

cd /usr/local/haproxy/etc
openssl genrsa -des3 -out ssl/proxy.key 2048
openssl req -new -key "ssl/proxy.key" -out "ssl/proxy.csr"
openssl x509 -req -days 365 -in "ssl/proxy.csr" -signkey "ssl/proxy.key" -out "ssl/proxy.crt"
cat ssl/proxy.crt ssl/proxy.csr > ssl/proxy.pem

III. Using a load-balancing rule

HAProxy offers several load-balancing algorithms. In the configuration example, the balance leastconn option is used. The balance leastconn option instructs HAProxy to direct traffic to the back-end server with the least number of connections.

IV. Configuring back-end servers

The back-end servers are the lines that start with "server" in the configuration file. These entries instruct the HAProxy to redirect traffic to the nodes. In the configuration example, there are four nodes. Replace the nodex.host.com parts with the actual host-name of the servers (nodes) on which you install your CCM servers (replicas).

You can preconfigure HAProxy with as many back-end servers (nodes) as the number of CCM nodes that you are planning to have. For the initial setup stage, start with one instance of CCM on one node by commenting out all the other server lines except for the first line:

server ccm1 node1.host.com:9443 minconn 100 maxconn 500 ssl check cookie ccm1 verify none
#server ccm2 node2.host.com:9443 minconn 100 maxconn 500 ssl check cookie ccm2 verify none
#server ccm3 node3.host.com:9443 minconn 100 maxconn 500 ssl check cookie ccm3 verify none
#server ccm4 node5.host.com:9443 minconn 100 maxconn 500 ssl check cookie ccm4 verify none

After HAProxy is configured, if it is running as a service, you can start, stop, and restart it by entering the following command:

sudo service haproxy start|stop|restart|reload

V. Optimizing the number of connections

The minconn, maxconn, and fullconn parameters are used to fine-tune the server and to control the number of simultaneous connections the server can handle. If more connections are established, the overage will be buffered. It can be difficult to determine the optimal numbers for these parameters, because they depend on the expected number of users and the server responsiveness, which can be influenced by available resources, network bandwidth, and so on. The number of connections can be fine-tuned depending on the number of users that are expected to use the clustered applications.

These numbers are also related to how is configured. By default, the instance that runs is configured with coreThreads="100" which is the lowest number of threads that handle incoming requests. The maximum is limited by the available system resources. Therefore, the minconn parameter should be set to the value of the coreThreads setting. The maxconn value in the back-end section (that is, one per back-end server) should be set to the maximum number of users that the server is capable of handling without showing any degradation in performance or response times. In the configuration example provided earlier, the maxconn value is set to 500 on each back end. The total of all back-end maxconn values should equal the maxconn value that is set in the front-end section of the configuration file. For example, if there are four nodes that are each set to maxconn=500, the maxconn value in the front-end should be set to 2000.

VI. Accessing the monitoring console and logs

The last section in the configuration file specifies how to access the HAProxy monitoring console. The console shows the number of nodes and their statuses, as well as the incoming and outgoing traffic. For a well-functioning cluster, assuming all nodes have been brought online at about the same time, the number of sessions (Total and lbTotal) should be roughly the same, and the number of bytes transferred should not vary too much between nodes. There should be no errors or warnings.

HAProxy maintains a log file in this directory: /var/log/haproxy.log. This log file contains information about which requests were redirected to which back-end servers and other HAProxy information such as session-affinity cookies and response codes.

Optional: Set up HAProxy high availability

 

Optional: Set up a custom loadbalancing

HAProxy provides different parameters for adapting and tuning its behavior, including a property named weight that you can use to identify servers for balancing. This property is only used for the first session request, because all the other requests for this session are routed to the same server with session affinity. The weight must be a value between 1 and 256. When the weight property is not set, the default value of 1 is used.

The weight property can be added to any server declaration in a back end, as shown in the following line:

backend ccm
...
server ccm1 node1.host.com:9443 minconn 100 maxconn 500 ssl check weight 50 cookie ccm1 verify none

The weight parameter enables you to define a specific weight for your server. However, you must edit the haproxy.cfg file each time that you want to change the weight. To avoid opening the haproxy.cfg file to change the weight, you can use a socket interface to change the weight while the HAProxy server is running. Use the following procedure to install the Socat program, which allows you to send messages to the HAProxy TCP stats socket:

Procedure

  1. To install Socat, enter the following command in the shell:

    yum -y install socat

  2. Open and edit the haproxy.cfg file to declare the socket and set its permission and level. Add the following lines to the general section of haproxy.cfg. In the following example, the socket in the /var/lib/haproxy/stats.sock directory is used. Only the user that is declared as the HAProxy user in the haproxy.cfg file is permitted to connect to the socket mode 600. The access level is set to administrator to allow updates to the weight parameter by using the socket:

    stats socket /var/lib/haproxy/stats.sock mode 600 level admin
    stats timeout 2m

  3. Restart the HAProxy server.
  4. Determine the correct weight for the nodes based on the server activities. You can gather system data from all nodes and compute a weight based on the gathered data. After you compute the correct weight based on system data, you can create a script and use the weight for all nodes. In the following example, ccm is the name of the back end, ccm1 is the name of the server node, and the new weight is set to 50: :

    echo "set weight ccm/<serverName> <newWeight>" | socat unix-connect:/var/lib/haproxy/stats.sock stdio
    ex: echo "set weight ccm/ccm1 50" | socat unix- connect:/var/lib/haproxy/stats.sock stdio

Set up

Note: Installation of is not supported on Windows platforms.

provides secure, rapid, bidirectional messaging for the Internet of Things (IoT) and mobile environments. is a high performance MQTT broker.

I. Installing the non-Dockerized version of

Procedure

To install a non-Dockerized version of , follow these steps:

  1. Download the required packages for the latest 2.0 from ibm.com.

    Note: An IBMid is required to access these files. If you do not have an IBMid, you will be prompted to create one before you can download .

  2. Follow the instructions in the documentation to install the non-Dockerized (RPM) version.

II. Logging in to the Web UI

About this task

You can use the URL http://server:Port to connect to the Web UI. This task uses https://10.10.2.149:9087/ to connect to the Web UI. To use this URL, your Web UI container must be running on the host with IP address 10.10.2.149.

You must accept a certificate and server certificate before you can start using the Web UI. You must change both of these certificates if you move from a non-production to a production environment.

Procedure

  1. Open a web browser and connect to the Web UI by entering the following URL: 10.10.2.149:9087
  2. Accept the Web UI certificate so that you can view the login page.
  3. Log in and accept the server certificate in one of the following ways:
    • If you are using Internet Explorer 11, complete the following steps to log in and accept the server certificate:
      1. At the login prompt, type the default ID and password (admin/admin) and click Log in.
      2. After you are logged in, follow the browser prompts to accept the certificate. The Common configuration and customization tasks section of the Web UI home page is displayed.
    • If you are using Firefox or Google Chrome, complete the following steps to log in and accept the server certificate:
      1. At the login prompt, type the default ID and password (admin/admin) and click Log in. The Cannot connect to the server error is displayed.
      2. Click Click here in the message text. An error page is displayed that indicates that you need to accept the certificate.
      3. Follow the browser prompts to accept the certificate. The About page is displayed in a new browser window.
      4. Return to the Web UI page. If the error is still displayed, refresh the page. The Common configuration and customization tasks section of the Web UI home page is displayed.
      5. Note: To prevent repeatedly having to accept certificates, you can replace the default certificate with your own appropriately signed certificate. For information about specifying your own certificate, see Changing the Web UI security certificate.

III. Configuring

uses organizational configuration objects called hubs to define configuration policies.

Procedure

  1. After logging in to the Web UI by following the procedure in the previous task, create a new hub and then create and assign a connection policy, messaging policy and endpoint.
  2. Create a new connection policy. Provide a name and a description. Enter a client ID and select MQTT for protocol. Under Specify the resources that an MQTT client is permitted to consume, select Allow Clients with Durable Subscriptions and Allow Persistent Messages check boxes.
  3. Go to the Message Policy tab and create a new topic policy. Provide a name and a description for the new topic policy. Enter a client ID and select MQTT for the protocol. In the Topic field enter an asterisk (*) and, under Authority, select both the Publish and Subscribe check boxes. Under Subscriber Settings, ensure that you enter 10000 for the Max Messages value and select Discard Old Messages for the Max Messages Behavior value.
  4. Finally, create a new endpoint. Provide a name and a description. In the Port field, specify the port that your clients (CCM or QM nodes) use to connect to publish and subscribe to messages. Later, you will add this port to the server.startup file. Select MQTT as the protocol. Set the Max Message Size value to 4096. Under Connection Policies and Messaging Policies, associate the connection policy and messaging policy (topic policy) that you created in the previous steps.

IV. Monitoring subscriptions

You can view subscription monitoring statistics by using the Web UI. To access the monitoring subscriptions, go to the Subscriptions page by selecting Monitoring > Subscriptions.

In the Monitoring view, you can see all MQTT clients (nodes), the topics being subscribed to and published, the active consumers, the number of messages, and the buffer sizes. You can use various options to filter the data.

V. Optional: high availability

To implement high availability for (primary and standby nodes), see the following topics in the documentation:

Install the server

Install , , and the application

Before you begin

Before you start the installation, complete these tasks:

  • If you installed an product for trial or demonstration purposes, you must uninstall and remove any -related application directories before the new installation. For more information see, Uninstalling and the applications.
  • To install the servers and applications for the () or , you must obtain the installation files. You can download either the Web Installer or the Installation Manager repository package for your platform from Jazz.net download section.
  • Obtain the installation files from the Jazz.net download area.
  • On IBM AIX® platforms, you can use the jar command to extract the package, but you must run the following chmod command to ensure that the Launchpad program has the correct execution permission: chmod -R +x launchpad.sh
  • You must have a supported version of IBM® Installation Manager for your platform. The Web Installer downloads contain Installation Manager. The easiest way to proceed is to get the Web Installer download for your platform.
  • You must have an Installation Manager response file that is tailored for the products to install. The Web Installer downloads contain sample response files for installing each of the available products.
  • You must have the Installation Manager repositories for each of the products to install. These repositories are available in the All Downloads section of the product downloads page.
  • Extract the downloaded .zip file to a temporary directory. To avoid issues, do not use long paths and directories that have spaces in their names. Extract any other Installation Manager repository files that you download into the same directory as the Web Installer.
  • The response files contain an example command-line invocation that uses the -acceptLicense argument. Before attempting a command-line installation, review the license agreement that is included in the /license directory at the top-level of the product download. Use the -acceptLicense argument on the command-line to indicate acceptance of this license agreement.
  • Each response file contains a line that refers to the Installation Manager repository to be used during installation. Edit the repository location attribute to point to the repository.config file in the directory that you extracted the Installation Manager repository files to.
  • Before you can install and run applications on your IBM AIX® system, you must increase the limit of open files:
    1. Start smit.
    2. Go to Security & Users > Users > Change/Show Characteristics of a User.
    3. Enter the User ID under which the is running.
    4. Enter a value of 65536 in the Soft NOFILE descriptors and Hard NOFILE descriptors fields.
    5. Enter a value of 10000 in the Soft NPROC per user and Hard NPROC per user fields.
    6. Log out and log back in to the system.
    7. Before starting Tomcat , run ulimit -n to see if the configuration took effect. The output must be 65536.
    8. Also before starting Tomcat , run ulimit -u to see if the configuration took effect. The output must be 10000.
  • Unless you plan to perform a silent installation, a supported browser is required to install the products with a graphical user interface and IBM Installation Manager.
  • The browser must be included in the $PATH environment variable. If the launchpad.sh program for IBM Installation Manager cannot find the browser, an error message will be displayed.
  • Before you can install and run applications on your Linux system, you must increase the limit of open files and user processes:
    1. As a root user add the following lines to the /etc/security/limits.conf file:

      * hard nofile 65536
      * soft nofile 65536
      * hard nproc 10000
      * soft nproc 10000

    2. Also ensure that the nproc value in /etc/security/limits.d/90-nproc.conf (RHEL6) or /etc/security/limits.d/20-nproc.conf (RHEL7) is set to 10000.
    3. After you modify the configuration files, restart the Linux system.
    4. To increase the limits in a running shell, use the following commands:

      ulimit -n 65536
      ulimit -u 10000

      Note: If you use these commands, start the Launchpad program or IBM Installation Manager from the same shell to inherit the modified limits. After these settings are applied, reindex the server to fix any corrupted server indexes by running the Jazz_Install_Dir/server/repotools-jts -reindex repotools command.

  • If Security-Enhanced Linux (SELinux) is enabled, you must disable it or change the security context of the Java Runtime Environment (JRE) to allow text relocation. For more information, see Installing with Security-Enhanced Linux.
  • The installation path names for the applications must not contain spaces. The startup script (Jazz_Install_Dir/server/server.startup) and the repository tools script (Jazz_Install_Dir/server/repotools-app.sh) detect and report this problem.
  • The Reports component requires that 32-bit X11 libraries be installed on the server. On Redhat Enterprise Linux 5, the required packages are libXp, libXinerama, mesa-libGL, and compat-libstdc++-33.
  • You must have the GTK x32 libraries available in your Linux system to be able to open the Installation Manager link from the Launchpad program. For more information, see this article on jazz.net.
  • When you run the applications, you can modify and write logs and other files to the installation directory. For all users to write to the installation directory, you must manually grant write permissions to it Jazz_Install_Dir.

Important: If you use a system startup script such as /etc/init.d/was or /etc/rc.*/SXXWebSphere to start WebSphere® Application Server at system boot up time, init.d invokes the startup scripts with the maximum number of file descriptors set to 1024 instead of the system default value that is set in /etc/security/limits.conf (65536). To avoid this problem, add the command ulimit -n 65536 to the top of your startup script. This ensures that is started with the correct file descriptor limit.

About this task

There are two ways to download and install applications. The first installation method is a web-based installation that includes a smaller download and connects to the internet during the installation to get the repository files. If you must install the server in an environment without internet access, use the second installation method: download and extract the repository files to a local computer to install the server.

If you do not have User Interface libraries installed on your server or just prefer to use the command-line installation method, you can use an IBM Installation Manager response file to install . This method is also referred to as silent installation.

There are two sample response files provided to install and applications:

  • silent-install-server.xml: Use this script to produce an installation of the applications in the C:\tmp\silent-install\JazzTeamServer/tmp/silent-install/JazzTeamServer directory that can be compressed and relocated on the file system, or to other computers with the same operating system and architecture. To use this script, you must have Installation Manager installed on your server.
  • silent-install-server2.xml: Use this script to install the applications in the default installation location. If you do not have Installation Manager, this script will install Installation Manager on your server before continuing with the installation.

There are two sample response files provided to install :

  • silent-install-jas.xml: Use this script to produce an installation of the in the C:\tmp\silent-install\JazzAuthServer/tmp/silent-install/JazzAuthServer directory that can be compressed and relocated on the file system, or to other computers with the same operating system and architecture. To use this script, you must have Installation Manager installed on your server.
  • silent-install-jas2.xml: Use this script to install the in the default installation location. If you do not have Installation Manager, this script will install Installation Manager on your server before continuing with the installation.

In addition to the server sample response files, these additional component sample response files are also included:
  • silent-install-buildsystem.xml: Installs Build System Toolkit
  • silent-install-cc-connector.xml: Installs Rational ClearCase Synchronizer
  • silent-install-client.xml: Installs - Client for Eclipse IDE
  • silent-install-cq-connector.xml: Installs Rational ClearQuest Synchronizer
  • silent-install-jazz-msscci.xml: Installs MS-SCCI provider
  • silent-install-vs-client.xml: Installs - Client for Microsoft Visual Studio
  • silent-install-windows-shell-client.xml: Installs Windows Explorer Shell

Procedure

Note: Ensure that the application is already installed on the server, or you are installing it with the Architecture Management Domain Extension for at this time. If the same version of the application is not present on the server, the installation will fail.

  1. Extract the downloaded .zip file to a temporary directory. To avoid issues, do not use long paths and directories that have spaces in their names.
  2. Install by using either the web installer or the Installation Manager repository package.
    • To install by using the web installer:
      1. Open a command prompt and change to the directory where you extracted the .zip file to, and enter launchpad. The Launchpad opens.

        Note: If you want to install the product as a non-root usernon-administrator user, from the Select user mode for Installation Manager list, select Non-Administrator. When you select Non-Administrator, the software packages will be installed in the user's directory and the package group will be named My IBM Collaborative Lifecycle Management. Also on Windows operating systems with User Access Control (UAC) enabled, the user who is installing the applications must be able to write to the installation directories.

      2. Follow the links in the Launchpad to continue the installation. As you follow the links in the Launchpad, Installation Manager opens to install the software packages.
    • To install by using the Installation Manager repository package:
      1. Start Installation Manager.

        If you do not have a supported version of Installation Manager, you can obtain it from Jazz.net or download the web installer, which includes Installation Manager.

      2. Click File > Preferences, and then select Add Repository.
      3. To specify the repository location, browse to the directory where you downloaded the .zip file and open the repository.config file.
      4. Click OK, and then click Install to start the installation process.
      5. Follow the instructions in Installation Manager to install the software packages.
  3. During installation, select the Install with WAS Liberty Profile check box.
  4. To install the reporting components, select the check box and then on the "Select the features to install" page, expand and select the following reporting components that you want to install:
    • Apache Cassandra
    • Elasticsearch
  5. Note: Apache Cassandra and Elasticsearch are technology preview in version 6.0.6. Select these packages only if you want to enable the with Property Graph technology preview. Apache Cassandra provides the backend storage for the property graph solution and Elasticsearch is used to index the data in the property graph solution.

  6. During the installation of and CCM applications, ensure that you select Enable Jazz Security Architecture SSO.
  7. During installation, clear Install with WAS Liberty Profile and select the Install application WAR files check box. This is to ensure that the application WAR files are copied in the default webapps directory for later deployment. You can also choose a directory of your choice to copy the WAR files.
  8. To install , from the launchpad menu under Install and the Applications, select Install . Follow the steps in the Installation Manager wizard to install . For information about starting , see Deploying and starting .

Note: If you are planning to use the System for Cross-domain Identity Management (SCIM) standard, you must install and configure the . The link to install the is available in the left menu of the Launchpad program.

Note: You can install on the same computer as or on its own dedicated server. Install on the computer that you identified as your , and install on the computer corresponding to the node you have enabled in your HAProxy configuration.

  1. Open a command prompt and change to the ExtractedDir\im\win32.win32.x86 directory.
  2. Open a command shell and change to the ExtractedDir/im/linux.gtx.x86 directory.
  3. Open a command shell and change to the ExtractedDir/im/linux.gtx.ppc directory.
  4. Open a command shell and change to the ExtractedDir/im/linux.gtx.s390 directory.
  5. Open a command shell and change to the ExtractedDir/im/aix.motif.ppc directory.
  6. To install the applications as an administrator into a shared area, use the installc variant in the following command:

    .\installc -acceptLicense -showVerboseProgress -input silent-install-server2.xml --launcher.ini silent-install.ini

    ./installc -acceptLicense -showVerboseProgress -input silent-install-server2.xml --launcher.ini silent-install.ini

  7. To install the applications into a user-specific location use the userinstc variant in the following command:

    .\userinstc -acceptLicense -showVerboseProgress -input silent-install-server2.xml --launcher.ini user-silent-install.ini

    ./userinstc -acceptLicense -showVerboseProgress -input silent-install-server2.xml --launcher.ini user-silent-install.ini

  8. To install as an administrator into a shared area, use the installc variant in the following command:

    .\installc -acceptLicense -showVerboseProgress -input silent-install-jas2.xml --launcher.ini silent-install.ini

    ./installc -acceptLicense -showVerboseProgress -input silent-install-jas2.xml --launcher.ini silent-install.ini

  9. To install into a user-specific location use the userinstc variant in the following command:

    .\userinstc -acceptLicense -showVerboseProgress -input silent-install-jas2.xml --launcher.ini user-silent-install.ini

    ./userinstc -acceptLicense -showVerboseProgress -input silent-install-jas2.xml --launcher.ini user-silent-install.ini

  10. By default, the response files are configured for a Liberty server deployment. To modify the response files for a deployment, complete the following steps:
    1. Open silent-install-server.xml and search for user.com.ibm.team.install.jfs.appserver.noappserver.disable and change its value to false.
    2. Search for user.com.ibm.team.install.jfs.appserver.liberty.disable and change its value to true.
    3. Remove the comment from the following section and specify a location to install the web application WAR files:

      <data key='user.JazzFoundationServer.NoAppServer.WebApps.InstallLocation'
      value='C:\tmp\silent-install\JazzTeamServer\server\webapps'/>

      <data key='user.JazzFoundationServer.NoAppServer.WebApps.InstallLocation'
      value='/tmp/silent-install/JazzTeamServer/server/webapps'/>

  11. To remove an application from being installed, search for the application name and comment out or delete the line. For example, if you do not want to install application, search for rtc and delete or comment out the offering line:

    <!--
    <offering id='com.ibm.team.install.jfs.app.rtc'/>
    -->

  12. By default, the jrs offering installs all reporting features. If you want to install a subset of features, add a features parameter and list the features that you want to install separated by commas, for example:

    <offering id='com.ibm.team.install.jfs.app.jrs' features='lqe,dcc'/>

Installing the server on IBM i

For step-by-step instructions for new installations of , see Installing and applications on IBM i.

For detailed instructions for installing the Build System Toolkit and the context-aware search engine, see the following resources:

Set up the database

Before you create databases for your clustered environment, ensure that theread and write caches are enabled for the disk configuration.

Open the /etc/security/limits.conf file and set the following ulimits parameters:

<dbuser> hard nofile 65536
<dbuser> soft nofile 65536
<dbuser> hard nproc 65536
<dbuser> soft nproc 65536

If you are using the included Derby database, no additional setup is necessary. Proceed with the next step.

Note: Although a Derby database is included in the default configuration and requires no installation, this database is limited to 10 users. To enable more users, install a supported enterprise database such as Db2, Oracle, or SQL Server.

To create database tables, see Creating Db2 for z/OS database tables remotely.

By default, IBM Db2i database is setup and configured on your IBM i system. No additional setup is necessary. Proceed with the next step.

The products support IBM Db2 Enterprise Server Edition. For platforms that do not support Enterprise Server Edition, you can use IBM Db2 Workgroup Server Edition. You can obtain a trial download of one these Db2 editions or the free Db2 Express Server edition for deployments of 50 developers or fewer from ibm.com.

Before you begin

This procedure requires that the following prerequisites are met:

  • The databases are not partitioned. Partitioned databases are not supported in this release and must not be used.
  • You have the correct user password. On the UNIX systems, get the password for the Db2 instance owner, which is typically the db2inst1 user.
  • You have reviewed the Db2 documentation to verify that your system meets the requirements and is configured correctly.
  • Db2 is installed and running on a computer to be used as the database server. This computer can be different from the one that the runs on.
  • The user in the teamserver.properties file has system administrator authority over the database. For information about preparing a Db2 database with only DBADM authority, see this wiki page.

Procedure

database

  1. Open a Db2 command window.
  2. Enter this command to create a database for called JTS with 16K pages and the UTF-8 code set:

    db2 create database JTS using codeset UTF-8 territory en PAGESIZE 16384

database

  1. Create a file called createOauthTablesDB2.sql. Refer to the following SQL example to create the database and tables for . You can use a different database name than oauth2db, but you must use the OAuthDBSchema schema.

    Also note that these values are examples and you should change them according to your usage and environment. For example, if the TOKENSTRING value of 2048 is too small, you can increase that by using a datatype of TOKENSTRING NVARCHAR(MAX) NOT NULL,.

    CREATE DATABASE oauth2db USING CODESET UTF8 TERRITORY US;
    CONNECT TO oauth2db;

    CREATE BUFFERPOOL BUFF16K IMMEDIATE SIZE 2500 AUTOMATIC PAGESIZE 16K;
    create tablespace TAB16K pagesize 16K bufferpool BUFF16K dropped table recovery on;
    CREATE SYSTEM TEMPORARY TABLESPACE TEMPSYS16K PAGESIZE 16K BUFFERPOOL BUFF16K;

    ---- CREATE TABLES ----
    CREATE TABLE OAuthDBSchema.OAUTH20CACHE
    (
    LOOKUPKEY VARCHAR(256) NOT NULL,
    UNIQUEID VARCHAR(128) NOT NULL,
    COMPONENTID VARCHAR(256) NOT NULL,
    TYPE VARCHAR(64) NOT NULL,
    SUBTYPE VARCHAR(64),
    CREATEDAT BIGINT,
    LIFETIME INT,
    EXPIRES BIGINT,
    TOKENSTRING VARCHAR(2048) NOT NULL,
    CLIENTID VARCHAR(64) NOT NULL,
    USERNAME VARCHAR(64) NOT NULL,
    SCOPE VARCHAR(512) NOT NULL,
    REDIRECTURI VARCHAR(2048),
    STATEID VARCHAR(64) NOT NULL,
    EXTENDEDFIELDS CLOB NOT NULL DEFAULT '{}'
    );

    CREATE TABLE OAuthDBSchema.OAUTH20CLIENTCONFIG
    (
    COMPONENTID VARCHAR(256) NOT NULL,
    CLIENTID VARCHAR(256) NOT NULL,
    CLIENTSECRET VARCHAR(256),
    DISPLAYNAME VARCHAR(256) NOT NULL,
    REDIRECTURI VARCHAR(2048),
    ENABLED INT,
    CLIENTMETADATA CLOB NOT NULL DEFAULT '{}'
    );

    CREATE TABLE OAuthDBSchema.OAUTH20CONSENTCACHE (
    CLIENTID VARCHAR(256) NOT NULL,
    USERID VARCHAR(256),
    PROVIDERID VARCHAR(256) NOT NULL,
    SCOPE VARCHAR(1024) NOT NULL,
    EXPIRES BIGINT,
    EXTENDEDFIELDS CLOB NOT NULL DEFAULT '{}'
    );

    ---- ADD CONSTRAINTS ----
    ALTER TABLE OAuthDBSchema.OAUTH20CACHE
    ADD CONSTRAINT PK_LOOKUPKEY PRIMARY KEY (LOOKUPKEY);

    ALTER TABLE OAuthDBSchema.OAUTH20CLIENTCONFIG
    ADD CONSTRAINT PK_COMPIDCLIENTID PRIMARY KEY (COMPONENTID,CLIENTID);

    ---- CREATE INDEXES ----
    CREATE INDEX OAUTH20CACHE_EXPIRES ON OAUTHDBSCHEMA.OAUTH20CACHE (EXPIRES ASC);

    ---- GRANT PRIVILEGES ----
    ---- UNCOMMENT THE FOLLOWING IF YOU USE AN ACCOUNT OTHER THAN ADMINISTRATOR FOR DB ACCESS ----

    -- Change dbuser to the account you want to use to access your database
    -- GRANT ALL ON OAuthDBSchema.OAUTH20CACHE TO USER dbuser;
    -- GRANT ALL ON OAuthDBSchema.OAUTH20CLIENTCONFIG TO USER dbuser;

    ---- END OF GRANT PRIVILIGES ----

    DISCONNECT CURRENT;

  2. Open a Db2 command window and run the following script to create the database, tables, and indexes, and to grant privileges:

    db2 -stvf createOauthTablesDB2.sql

  3. After creating the database tables, you must configure to use the tables. Go to C:\IBM\JazzAuthServer\wlp\usr\servers\jazzop/opt/IBM/JazzAuthServer/wlp/usr/servers/jazzop and open appConfig.xml for editing.
  4. Comment out the following Apache Derby database section:

    <dataSource id=OAuthFvtDataSource jndiName=jdbc/OAuth2DB>
    <jdbcDriver libraryRef=DerbyLib />
    <properties.derby.embedded
    databaseName=asDB
    createDatabase=create />
    </dataSource>

    <library id=DerbyLib>
    <fileset dir=${shared.config.dir}/lib/global includes=derby.jar />
    </library>

  5. Add the following section to configure a Db2 database. You must customize this section to work with your specific Db2 server:

    <dataSource id=OAUTH2DBDS jndiName=jdbc/OAuth2DB>
    <jdbcDriver id=db2Universal libraryRef=DB2JCC4LIB/>
    <library id=DB2JCC4LIB filesetRef=db2jcc4 apiTypeVisibility=spec,ibm-api,third-party/>
    <fileset dir=${shared.config.dir}/lib/global id=db2jcc4 includes=db2jcc4.jar db2jcc_license_cu.jar/>
    <dataSource id=OAUTH2DBDS jndiName=jdbc/oauthProvider jdbcDriverRef=db2Universal>
    <properties.db2.jcc password=***** databaseName=OAUTH2DB user=db2inst1 portNumber=50000 serverName=yourDB2.com driverType=4/>
    </dataSource>

    Ensure that you have the correct values for the following attributes:

    • For user, provide the name of the Db2 user that is used to connect to the database.
    • For password, use the Db2 user password.
    • For databaseName, use the database name you created in the previous step. If you used the sample script file, the database name is OAUTH2DB.
    • For portNumber, use the port number that the Db2 instance is running on. The default port number is 50000.
    • For serverName, enter the host name of the Db2 server.

  6. In the oauthProvider section of the appConfig.xml file, update the databaseStore property so it specifies the Db2 data source rather than the default Apache Derby data source. The databaseStore property should specify the name of the DB2 data source, which in this example, is OAUTH2DBDS:

    <oauthProvider id=JazzOP
    httpsRequired=true
    autoAuthorize=true
    customLoginURL=/jazzop/form/login
    accessTokenLifetime=7201
    authorizationGrantLifetime=604801>
    <autoAuthorizeClient>client01</autoAuthorizeClient>
    <databaseStore dataSourceRef=OAUTH2DBDS />
    </oauthProvider>

  7. Save and close the appConfig.xml file.
  8. Copy the Db2 db2jcc4.jar and db2jcc_license_cu.jar JDBC drivers from your Db2 server to this directory: C:\IBM\JazzAuthServer\wlp\usr\shared\config\lib\globalopt/IBM/JazzAuthServer/wlp/usr/shared/config/lib/global.

database

  1. Open a Db2 command window.
  2. Enter this command to create a database for application called CCM with 16K pages and the UTF-8 code set:

    db2 create database CCM using codeset UTF-8 territory en PAGESIZE 16384

database

  1. Open Db2 command window.
  2. Enter this command to create a database for application called QM with 16K pages and the UTF-8 code set:

    db2 create database QM using codeset UTF-8 territory en PAGESIZE 16384

database

  1. Open a Db2 command window.
  2. Enter this command to create a database for application called RM with 16K pages and the UTF-8 code set:

    db2 create database RM using codeset UTF-8 territory en PAGESIZE 16384

database

  1. Open a Db2 command window.
  2. Enter this command to create a database for the application called DCC with 16K pages and the UTF-8 code set:

    db2 create database DCC using codeset UTF-8 territory en PAGESIZE 16384

database

  1. Open a Db2 command window.
  2. Enter this command to create a database for the application called LQE with 32K pages and the UTF-8 code set:

    Note: The database requires 32K pages.

    db2 create database LQE using codeset UTF-8 territory en PAGESIZE 32768

    The LQE database must have the MAXAPPLS increased to allow for concurrent connections in to process data if it is not set to AUTOMATIC. Increase the value to 300:

    db2 update db cfg for LQE using maxappls 300

    This means that the lock list must also be increased if it is not set to AUTOMATIC:

    db2 update db cfg FOR LQE using locklist 20000

    The transaction logs will also grow as data is processed in parallel. Increase the LOGFILSIZ to 20000:

    db2 update db cfg for LQE using LOGFILSIZ 20000

    Increase the number of primary and secondary transactions log files:

    db2 update db cfg for LQE using logprimary 25
    db2 update db cfg for LQE using logsecond 100

database

  1. Open a Db2 command window.
  2. Enter this command to create a database for the application called LDX with 32K pages and the UTF-8 code set:

    Note: The database requires 32K pages.

    db2 create database LDX using codeset UTF-8 territory en PAGESIZE 32768

database

  1. Open a Db2 command window.
  2. Enter this command to create a database for the Global Configuration application called GC with 16K pages and the UTF-8 code set:

    db2 create database GC using codeset UTF-8 territory en PAGESIZE 16384

database

  1. Open a Db2 command window.
  2. Enter this command to create a database for the application called RELM with 16K pages and the UTF-8 code set:

    db2 create database RELM using codeset UTF-8 territory en PAGESIZE 16384

Data warehouse database

  1. Open a Db2 command window.
  2. Enter this command to create a database for your data warehouse called DW with 32K pages and the UTF-8 code set:

    db2 create database DW using codeset UTF-8 territory en PAGESIZE 32768

    The data warehouse database must have the MAXAPPLS increased to allow for concurrent connections in to process data if it is not set to AUTOMATIC. Increase the value to 300:

    db2 update db cfg for DW using maxappls 300

    This means that the lock list must also be increased if it is not set to AUTOMATIC:

    db2 update db cfg FOR DW using locklist 20000

    The transaction logs will also grow as data is processed in parallel. Increase the LOGFILSIZ to 20000:

    db2 update db cfg for DW using LOGFILSIZ 20000

    Increase the number of primary and secondary transactions log files:

    db2 update db cfg for DW using logprimary 25
    db2 update db cfg for DW using logsecond 200

DBADM authority

If you are creating the database with a user other than the user specified in the teamserver.properties file, you must grant DBADM authority to that user:

db2 connect to database_name
db2 grant dbadm on database to user user_name
db2 disconnect database_name

Verify

If you create all databases on the same database server, verify that the Max number of concurrently active databases is set to a number greater than the number of databases you created. If this value is lower than the number of active databases, you will get the SQL Code 1041 error.

To verify the value and increase the number if necessary, complete these steps:

  1. Open a Db2 command window and enter this command to display the database manager configuration:

    db2 get dbm cfg

  2. Look for the Max number of concurrently active databases line. If this number is lower than the installed databases, increase the number by entering this command:

    db2 update dbm cfg using numdb 32

  3. Stop and start the database manager for these changes to take effect by entering these commands:

    db2stop
    db2start

To create and set up an Oracle database, it is assumed that the user who is preparing the database has database administration authority over the database and that the database, tablespace storage, and appropriate storage configuration is created by a user with system administration authority.

Before you begin

  • The required Java Database Connectivity (JDBC) driver is ojdbc8.jar. For a list of supported database versions and driver versions, see the system requirements link in the Planning checklist section of this document.
  • Restriction: Because of a defect in Oracle JDBC driver 12.1.0.2.0, this version of the driver cannot be used. For details, see repotools -createTables command fails with ORA-01000 on Oracle 12 on the IBM Support portal page.

  • The configuration parameters and tablespace options used in this step are examples and might not entirely apply to your environment. For example, if you cannot use the AUTOEXTEND setting, then the files must be large enough to allow for growth. Or if you cannot use the UNLIMITED size quota for the database user, then make sure to allow enough space for rapid growth.
  • If you install the () applications on the same computer or distributed platforms, you can either create separate databases for each application or you can use the same database for all applications. However, you must create a separate tablespace and a database user who is associated with that tablespace for each application.

    The examples in this step are for one Oracle database with separate tablespaces and database users who are dedicated to each application.

  • The database that you create for the and all applications must be formatted to use UTF-8 as the character set. By default, Oracle does not create a database with the UTF-8 character set. When you create a new database, ensure that you select AL32UTF8 in the Oracle DB setup.
  • Change the open cursors limit:
    • If you use spfile to start the database, open a SQL *Plus window and enter the following command:

      alter system set open_cursors = 10000 scope=both;

    • If you use pfile to start the database, open a SQL *Plus window and enter the following command:

      alter system set open_cursors = 10000;

  • For the Oracle data warehouse database to work efficiently with the , you must increase the PROCESSES configuration to 3000.

Procedure

Create an Oracle database

As a system administrator, create a database with UTF-8 encoding for and all applications.

  1. Start the Database Configuration Assistant wizard and on the Welcome page click Next.
  2. On the Operations page, select Create a Database and then click Next.
  3. On the Templates page, select Custom Database and click Next.
  4. In both the Global Database Name and SID fields, enter a name for the content storage database, for example, DB. Click Next.
  5. To configure the database control, enter the required information for alert notification and optionally enable the daily disk backup schedule. To continue without database control configuration, clear the check box next to Configure Enterprise Manager and then click Next.
  6. On the Database Credentials page, choose an option for your user account, and then click Next.

    Note: Oracle password complexity policy requires that passwords should have minimum of 12 characters in length. In addition, the password must contain at least one upper-case character, one lower-case character, and one digit. If your password contains special characters, multibyte characters, or starts with numbers or special characters, you must enclose it in double quotation marks. For details, see the Oracle documentation.

  7. On the next page, select a storage type and location for database files. Click Next.
  8. On the next page, choose a recovery option for the database, and then click Next.
  9. On the next page, specify whether or not to add the Sample Schemas to your database. Click Next.
  10. On the next page, click the Character Sets tab and select Use Unicode (AL32UTF8). Click Next.

    Note: Setting character set to Unicode (AL32UTF8) enables you to store multiple language groups.

  11. On the Database Storage page verify or change the database objects and click Next.
  12. On the next page click Finish to create the database.
  13. On the Confirmation window that opens, optionally save the page as an HTML file, and then click OK. A progress bar is displayed to show the database creation progress.

Create tablespaces for

  1. Start SQL Plus and log in as SYSTEM or SYSDBA.
  2. To create a tablespace for , enter the following command. Replace JTS with the tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in previous step, and JTS.DBF with the datafile name that you want to create.
  3. CREATE BIGFILE TABLESPACE JTS
    DATAFILE 'ORACLE_BASE/oradata/DB/JTS.DBF'
    SIZE 1G AUTOEXTEND ON EXTENT MANAGEMENT LOCAL AUTOALLOCATE;

  4. To create a temporary tablespace for , enter the following command. Replace JTS_TEMP with the temporary tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and JTS_TEMP.DBF with the temporary file name that you want to create.
  5. CREATE TEMPORARY TABLESPACE JTS_TEMP
    TEMPFILE 'ORACLE_BASE/oradata/DB/JTS_TEMP.DBF'
    SIZE 20M AUTOEXTEND ON EXTENT MANAGEMENT LOCAL UNIFORM SIZE 1M;

Create tablespaces for

  1. Create a file called createOauthOracle.sql. Refer to the following SQL example to create the tablespaces required for .

    Note that the values in the script file are examples and you should change them according to your usage and environment. For example, if the TOKENSTRING value of 2048 is too small, you can increase that by using a datatype of TOKENSTRING NVARCHAR(MAX) NOT NULL,.

    createOauthOracle.sql creates two tablespaces: OAUTH and OAUTH_TMP, and creates the tables in the OAUTH tablespace. If you have an existing tablespace that you want to use, you can change the CREATE TABLE statement to use your existing tablespace. If you want to create new tablespaces, then you should edit the DATAFILE and TEMPFILE clauses to point at the directory that you want to use for the tablespace.

    expects to find a user named OAUTHDBSCHEMA, and it expects to find tables in a schema named OAUTHDBSCHEMA. You must create the OAUTHDBSCHEMA user in Oracle. Customize the CREATE USER statement to specify a password for the OAUTHDBSCHEMA user. When you create the OAUTHDBSCHEMA user, you must also associate that user with the tablespace you plan to use for the OAUTH tables.

    CREATE TABLESPACE OAUTH DATAFILE '/home/oracle/tablespaces/OAUTH.dbf' SIZE 1G AUTOEXTEND ON EXTENT MANAGEMENT LOCAL AUTOALLOCATE;
    CREATE TEMPORARY TABLESPACE OAUTH_TMP TEMPFILE '/home/oracle/tablespaces/OAUTH_TMP.dbf' SIZE 20M AUTOEXTEND ON EXTENT MANAGEMENT LOCAL UNIFORM SIZE 1M;
    CREATE USER OAUTHDBSCHEMA IDENTIFIED BY <your password> DEFAULT TABLESPACE OAUTH QUOTA UNLIMITED ON OAUTH TEMPORARY TABLESPACE OAUTH_TMP;
    GRANT CREATE PROCEDURE, CREATE SESSION, CREATE TABLE, CREATE VIEW TO OAUTHDBSCHEMA;

    ---- CREATE TABLES ----
    CREATE TABLE OAuthDBSchema.OAUTH20CACHE
    (
    LOOKUPKEY VARCHAR(256) NOT NULL,
    UNIQUEID VARCHAR(128) NOT NULL,
    COMPONENTID VARCHAR(256) NOT NULL,
    TYPE VARCHAR(64) NOT NULL,
    SUBTYPE VARCHAR(64),
    CREATEDAT NUMBER(19,0),
    LIFETIME INT,
    EXPIRES NUMBER(19,0),
    TOKENSTRING VARCHAR(2048) NOT NULL,
    CLIENTID VARCHAR(64) NOT NULL,
    USERNAME VARCHAR(64) NOT NULL,
    SCOPE VARCHAR(512) NOT NULL,
    REDIRECTURI VARCHAR(2048),
    STATEID VARCHAR(64) NOT NULL,
    EXTENDEDFIELDS CLOB DEFAULT '{}' NOT NULL
    )
    TABLESPACE OAUTH STORAGE(INITIAL 50K);

    CREATE TABLE OAuthDBSchema.OAUTH20CLIENTCONFIG
    (
    COMPONENTID VARCHAR(256) NOT NULL,
    CLIENTID VARCHAR(256) NOT NULL,
    CLIENTSECRET VARCHAR(256),
    DISPLAYNAME VARCHAR(256),
    REDIRECTURI VARCHAR(2048),
    ENABLED INT,
    CLIENTMETADATA CLOB DEFAULT '{}' NOT NULL
    ) TABLESPACE OAUTH STORAGE(INITIAL 50K);

    CREATE TABLE OAuthDBSchema.OAUTH20CONSENTCACHE (
    CLIENTID VARCHAR(256) NOT NULL,
    USERID VARCHAR(256),
    PROVIDERID VARCHAR(256) NOT NULL,
    SCOPE VARCHAR(1024) NOT NULL,
    EXPIRES NUMBER(19,0),
    EXTENDEDFIELDS CLOB DEFAULT '{}' NOT NULL
    ) TABLESPACE OAUTH STORAGE(INITIAL 50K);

    ---- ADD CONSTRAINTS ----
    ALTER TABLE OAuthDBSchema.OAUTH20CACHE
    ADD CONSTRAINT PK_LOOKUPKEY PRIMARY KEY (LOOKUPKEY);

    ALTER TABLE OAuthDBSchema.OAUTH20CLIENTCONFIG
    ADD CONSTRAINT PK_COMPIDCLIENTID PRIMARY KEY (COMPONENTID,CLIENTID);

    ---- CREATE INDEXES ----
    CREATE INDEX OAUTH20CACHE_EXPIRES ON OAuthDBSchema.OAUTH20CACHE (EXPIRES ASC);

    ---- GRANT PRIVILEGES ----
    ---- UNCOMMENT THE FOLLOWING IF YOU USE AN ACCOUNT OTHER THAN ADMINISTRATOR FOR DB ACCESS ----

    -- Change dbuser to the account you want to use to access your database
    GRANT ALL ON OAuthDBSchema.OAUTH20CACHE TO OAUTHDBSCHEMA;
    GRANT ALL ON OAuthDBSchema.OAUTH20CLIENTCONFIG TO OAUTHDBSCHEMA;
    GRANT ALL ON OAuthDBSchema.OAUTH20CONSENTCACHE TO OAUTHDBSCHEMA;

    ---- END OF GRANT PRIVILIGES ----

  2. After you finish customizing the createOauthOracle.sql script, open SQL Plus and log in as SYSDBA, and run the SQL script:

    @createOauthOracle.sql

  3. After creating the database tables, you must configure to use the tables. Go to C:\IBM\JazzAuthServer\wlp\usr\servers\jazzop/opt/IBM/JazzAuthServer/wlp/usr/servers/jazzop and open appConfig.xml for editing.
  4. Comment out the following Apache Derby database section:

    <dataSource id=OAuthFvtDataSource jndiName=jdbc/OAuth2DB>
    <jdbcDriver libraryRef=DerbyLib />
    <properties.derby.embedded
    databaseName=asDB
    createDatabase=create />
    </dataSource>

    <library id=DerbyLib>
    <fileset dir=${shared.config.dir}/lib/global includes=derby.jar />
    </library>

  5. Add the following section to configure Oracle. You must customize this section to work with your specific Oracle server:

    <dataSource id=OAUTH2ORA jndiName=jdbc/OAuth2DB>
    <jdbcDriver id=oracle libraryRef=ORAJCC4LIB/>
    <library id=ORAJCC4LIB filesetRef=orajcc4 apiTypeVisibility=spec,ibm-api,third-party/>
    <fileset dir=${shared.config.dir}/lib/global id=orajcc4 includes=ojdbc8.jar/>
    <dataSource id=OAUTH2ORA jndiName=jdbc/oauthProvider jdbcDriverRef=oracle>
    <properties.oracle password=***** databaseName=ORCL user=OAUTHDBSCHEMA portNumber=1521 serverName=yourOracle.com/>
    </dataSource>

    Ensure that you have the correct values for the following attributes:

    • For password, use the password you specified when creating the OAUTHDBSCHEMA user in Oracle.
    • For databaseName, use the Oracle SID for your database. The sample uses the default value assigned by Oracle - ORCL. Your value might be different.
    • For portNumber, use the port number that the Oracle instance is running on. The default port number is 1521.
    • For serverName, enter the host name of the Oracle server.

  6. In the oauthProvider section of the appConfig.xml file, update the databaseStore property so it specifies the Oracle data source rather than the default Apache Derby data source. The databaseStore property should specify the name of the Oracle data source, which in this example, is OAUTH2ORA:

    <oauthProvider id=JazzOP
    httpsRequired=true
    autoAuthorize=true
    customLoginURL=/jazzop/form/login
    accessTokenLifetime=7201
    authorizationGrantLifetime=604801>
    <autoAuthorizeClient>client01</autoAuthorizeClient>
    <databaseStore dataSourceRef=OAUTH2ORA />
    </oauthProvider>

  7. Save and close the appConfig.xml file.
  8. Copy the Oracle ojdbc8.jar JDBC drivers from your Oracle server to this directory: C:\IBM\JazzAuthServer\wlp\usr\shared\config\lib\globalopt/IBM/JazzAuthServer/wlp/usr/shared/config/lib/global.

Create tablespaces for

  1. Start SQL Plus and log in as SYSTEM or SYSDBA.
  2. To create a tablespace for the application, enter the following command. Replace CCM with the tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and CCM.DBF with the datafile name that you want to create.
  3. CREATE BIGFILE TABLESPACE CCM
    DATAFILE 'ORACLE_BASE/oradata/DB/CCM.DBF'
    SIZE 1G AUTOEXTEND ON EXTENT MANAGEMENT LOCAL AUTOALLOCATE;

  4. To create a temporary tablespace for the application, enter the following command. Replace CCM_TEMP with the temporary tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and CCM_TEMP.DBF with the temporary file name that you want to create.
  5. CREATE TEMPORARY TABLESPACE CCM_TEMP
    TEMPFILE 'ORACLE_BASE/oradata/DB/CCM_TEMP.DBF'
    SIZE 20M AUTOEXTEND ON EXTENT MANAGEMENT LOCAL UNIFORM SIZE 1M;

Create tablespaces for

  1. Start SQL Plus and log in as SYSTEM or SYSDBA.
  2. To create a tablespace for the application, enter the following command. Replace RELM with the tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and RELM.DBF with the datafile name that you want to create.
  3. CREATE BIGFILE TABLESPACE RELM
    DATAFILE 'ORACLE_BASE/oradata/DB/RELM.DBF'
    SIZE 1G AUTOEXTEND ON EXTENT MANAGEMENT LOCAL AUTOALLOCATE;

  4. To create a temporary tablespace for the application, enter the following command. Replace RELM_TEMP with the temporary tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and RELM_TEMP.DBF with the temporary file name that you want to create.
  5. CREATE TEMPORARY TABLESPACE RELM_TEMP
    TEMPFILE 'ORACLE_BASE/oradata/DB/RELM_TEMP.DBF'
    SIZE 20M AUTOEXTEND ON EXTENT MANAGEMENT LOCAL UNIFORM SIZE 1M;

Create tablespaces for

  1. Start SQL Plus and log in as SYSTEM or SYSDBA.
  2. To create a tablespace for the application, enter the following command. Replace QM with the tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and QM.DBF with the datafile name that you want to create.
  3. CREATE BIGFILE TABLESPACE QM
    DATAFILE 'ORACLE_BASE/oradata/DB/QM.DBF'
    SIZE 1G AUTOEXTEND ON EXTENT MANAGEMENT LOCAL AUTOALLOCATE;

  4. To create a temporary tablespace for the application, enter the following command. Replace QM_TEMP with the temporary tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and QM_TEMP.DBF with the temporary file name that you want to create.
  5. CREATE TEMPORARY TABLESPACE QM_TEMP
    TEMPFILE 'ORACLE_BASE/oradata/DB/QM_TEMP.DBF'
    SIZE 20M AUTOEXTEND ON EXTENT MANAGEMENT LOCAL UNIFORM SIZE 1M;

Create tablespaces for

  1. Start SQL Plus and log in as SYSTEM or SYSDBA.
  2. To create a tablespace for the application, enter the following command. Replace RM with the tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and RM.DBF with the datafile name that you want to create.
  3. CREATE BIGFILE TABLESPACE RM
    DATAFILE 'ORACLE_BASE/oradata/DB/RM.DBF'
    SIZE 1G AUTOEXTEND ON EXTENT MANAGEMENT LOCAL AUTOALLOCATE;

  4. To create a temporary tablespace for the application, enter the following command. Replace RM_TEMP with the temporary tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and RM_TEMP.DBF with the temporary file name that you want to create.
  5. CREATE TEMPORARY TABLESPACE RM_TEMP
    TEMPFILE 'ORACLE_BASE/oradata/DB/RM_TEMP.DBF'
    SIZE 20M AUTOEXTEND ON EXTENT MANAGEMENT LOCAL UNIFORM SIZE 1M;

Create tablespaces for

  1. Start SQL Plus and log in as SYSTEM or SYSDBA.
  2. To create a tablespace for the application, enter the following command. Replace DCC with the tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and DCC.DBF with the datafile name that you want to create.
  3. CREATE BIGFILE TABLESPACE DCC
    DATAFILE 'ORACLE_BASE/oradata/DB/DCC.DBF'
    SIZE 1G AUTOEXTEND ON EXTENT MANAGEMENT LOCAL AUTOALLOCATE;

  4. To create a temporary tablespace for the application, enter the following command. Replace DCC_TEMP with the temporary tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and DCC_TEMP.DBF with the temporary file name that you want to create.
  5. CREATE TEMPORARY TABLESPACE DCC_TEMP
    TEMPFILE 'ORACLE_BASE/oradata/DB/DCC_TEMP.DBF'
    SIZE 20M AUTOEXTEND ON EXTENT MANAGEMENT LOCAL UNIFORM SIZE 1M;

Create tablespaces for

  1. Start SQL Plus and log in as SYSTEM or SYSDBA.
  2. To create a tablespace for the application, enter the following command. Replace LQE with the tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and LQE.DBF with the datafile name that you want to create.
  3. CREATE BIGFILE TABLESPACE LQE
    DATAFILE 'ORACLE_BASE/oradata/DB/LQE.DBF'
    SIZE 1G AUTOEXTEND ON EXTENT MANAGEMENT LOCAL AUTOALLOCATE;

  4. To create a temporary tablespace for the application, enter the following command. Replace LQE_TEMP with the temporary tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and LQE_TEMP.DBF with the temporary file name that you want to create.
  5. CREATE TEMPORARY TABLESPACE LQE_TEMP
    TEMPFILE 'ORACLE_BASE/oradata/DB/LQE_TEMP.DBF'
    SIZE 20M AUTOEXTEND ON EXTENT MANAGEMENT LOCAL UNIFORM SIZE 1M;

Create tablespaces for

  1. Start SQL Plus and log in as SYSTEM or SYSDBA.
  2. To create a tablespace for the application, enter the following command. Replace LDX with the tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and LDX.DBF with the datafile name that you want to create.
  3. CREATE BIGFILE TABLESPACE LDX
    DATAFILE 'ORACLE_BASE/oradata/DB/LDX.DBF'
    SIZE 1G AUTOEXTEND ON EXTENT MANAGEMENT LOCAL AUTOALLOCATE;

  4. To create a temporary tablespace for the application, enter the following command. Replace LDX_TEMP with the temporary tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and LDX_TEMP.DBF with the temporary file name that you want to create.
  5. CREATE TEMPORARY TABLESPACE LDX_TEMP
    TEMPFILE 'ORACLE_BASE/oradata/DB/LDX_TEMP.DBF'
    SIZE 20M AUTOEXTEND ON EXTENT MANAGEMENT LOCAL UNIFORM SIZE 1M;

Create tablespaces for

  1. Start SQL Plus and log in as SYSTEM or SYSDBA.
  2. To create a tablespace for the Global Configuration application, enter the following command. Replace GC with the tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and GC.DBF with the datafile name that you want to create.
  3. CREATE BIGFILE TABLESPACE GC
    DATAFILE 'ORACLE_BASE/oradata/DB/GC.DBF'
    SIZE 1G AUTOEXTEND ON EXTENT MANAGEMENT LOCAL AUTOALLOCATE;

  4. To create a temporary tablespace for the Global Configuration application, enter the following command. Replace GC_TEMP with the temporary tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and GC_TEMP.DBF with the temporary file name that you want to create.
  5. CREATE TEMPORARY TABLESPACE GC_TEMP
    TEMPFILE 'ORACLE_BASE/oradata/DB/GC_TEMP.DBF'
    SIZE 20M AUTOEXTEND ON EXTENT MANAGEMENT LOCAL UNIFORM SIZE 1M;

Create tablespaces for Data Warehouse

  1. Start SQL Plus and log in as SYSTEM or SYSDBA.
  2. To create a tablespace for the common data warehouse, enter the following command. Replace DW with the tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and DW.DBF with the datafile name that you want to create.
  3. CREATE BIGFILE TABLESPACE DW
    DATAFILE 'ORACLE_BASE/oradata/DB/DW.DBF'
    SIZE 1G AUTOEXTEND ON EXTENT MANAGEMENT LOCAL AUTOALLOCATE;

  4. To create a temporary tablespace for the common data warehouse, enter the following command. Replace DW_TEMP with the temporary tablespace name, ORACLE_BASE with the absolute path where Oracle is installed, DB with the database name you created in step a, and DW_TEMP.DBF with the temporary file name that you want to create.
  5. CREATE TEMPORARY TABLESPACE DW_TEMP
    TEMPFILE 'ORACLE_BASE/oradata/DB/DW_TEMP.DBF'
    SIZE 20M AUTOEXTEND ON EXTENT MANAGEMENT LOCAL UNIFORM SIZE 1M;

Verify

In the Oracle Enterprise Manager Database Control, click Server > Tablespaces and verify that the tablespaces you created are displayed and accessible. Also ensure that the default Oracle tablespace named USERS already exist. If this tablespace does not exist in your Oracle database, create it.

Create an Oracle database user for each new tablespace

After the tablespaces are created, a special Oracle user must be created for each application to use the Oracle database. For multiple Jazz servers that run on one Oracle database, an Oracle database user must be created for each application. The Oracle database user must be able to create database objects in its tablespace (either unlimited or with a space quota) with privileges to create session, table, procedure, and views.

To create a user for tablespace and to grant the required permissions, enter the following commands:

CREATE USER JTS_DB_USER IDENTIFIED BY Passw0rd DEFAULT TABLESPACE JTS QUOTA UNLIMITED ON JTS TEMPORARY TABLESPACE JTS_TEMP;

GRANT CREATE PROCEDURE, CREATE SESSION, CREATE TABLE, CREATE VIEW TO JTS_DB_USER;

To create a user for the application tablespace and to grant the required permissions, enter the following commands:

CREATE USER CCM_DB_USER IDENTIFIED BY Passw0rd DEFAULT TABLESPACE CCM QUOTA UNLIMITED ON CCM TEMPORARY TABLESPACE CCM_TEMP;

GRANT CREATE PROCEDURE, CREATE SESSION, CREATE TABLE, CREATE VIEW TO CCM_DB_USER;

To create a user for the application tablespace and to grant the required permissions, enter the following commands:

CREATE USER RELM_DB_USER IDENTIFIED BY Passw0rd DEFAULT TABLESPACE RELM QUOTA UNLIMITED ON RELM TEMPORARY TABLESPACE RELM_TEMP;

GRANT CREATE PROCEDURE, CREATE SESSION, CREATE TABLE, CREATE VIEW TO RELM_DB_USER;

To create a user for the application tablespace and to grant the required permissions, enter the following commands:

CREATE USER QM_DB_USER IDENTIFIED BY Passw0rd DEFAULT TABLESPACE QM QUOTA UNLIMITED ON QM TEMPORARY TABLESPACE QM_TEMP;

GRANT CREATE PROCEDURE, CREATE SESSION, CREATE TABLE, CREATE VIEW TO QM_DB_USER;

To create a user for application tablespace and to grant the required permissions, enter the following commands:

CREATE USER RM_DB_USER IDENTIFIED BY Passw0rd DEFAULT TABLESPACE RM QUOTA UNLIMITED ON RM TEMPORARY TABLESPACE RM_TEMP;

GRANT CREATE PROCEDURE, CREATE SESSION, CREATE TABLE, CREATE VIEW TO RM_DB_USER;

To create a user for the application tablespace and to grant the required permissions, enter the following commands:

CREATE USER DCC_DB_USER IDENTIFIED BY Passw0rd DEFAULT TABLESPACE DCC QUOTA UNLIMITED ON DCC TEMPORARY TABLESPACE DCC_TEMP;

GRANT CREATE PROCEDURE, CREATE SESSION, CREATE TABLE, CREATE VIEW TO DCC_DB_USER;

To create a user for the application tablespace and to grant the required permissions, enter the following commands:

CREATE USER LQE_DB_USER IDENTIFIED BY Passw0rd DEFAULT TABLESPACE LQE QUOTA UNLIMITED ON LQE TEMPORARY TABLESPACE LQE_TEMP;

GRANT CREATE PROCEDURE, CREATE SESSION, CREATE TABLE, CREATE VIEW TO LQE_DB_USER;

To create a user for the application tablespace and to grant the required permissions, enter the following commands:

CREATE USER LDX_DB_USER IDENTIFIED BY Passw0rd DEFAULT TABLESPACE LDX QUOTA UNLIMITED ON LDX TEMPORARY TABLESPACE LDX_TEMP;

GRANT CREATE PROCEDURE, CREATE SESSION, CREATE TABLE, CREATE VIEW TO LDX_DB_USER;

To create a user for the application tablespace and to grant the required permissions, enter the following commands:

CREATE USER GC_DB_USER IDENTIFIED BY Passw0rd DEFAULT TABLESPACE GC QUOTA UNLIMITED ON GC TEMPORARY TABLESPACE GC_TEMP;

GRANT CREATE PROCEDURE, CREATE SESSION, CREATE TABLE, CREATE VIEW TO GC_DB_USER;

To create a user for common data warehouse tablespace and to grant the required permissions, enter the following commands:

CREATE USER DW_USER IDENTIFIED BY Passw0rd DEFAULT TABLESPACE DW QUOTA UNLIMITED ON DW TEMPORARY TABLESPACE DW_TEMP;

GRANT DBA TO DW_USER;

Note: The creation of the data warehouse on Oracle requires more permissions as compared to other databases. When you specify the database user in the connection spec for data warehouse, ensure that the database user has DBA permissions. You can change this permission after the data warehouse is created. For more information, see Completing the installation.

To create the data warehouse without DBA permissions, see this deployment wiki article.

Create an environment variable

Create an environment variable named ORACLE_JDBC_DRIVER_FILE and point to the ojdbc8.jar JDBC driver. The location can vary depending on the Oracle product and operating system. You can download the supported Oracle JDBC driver from the Oracle website.

  1. Click Start > Control Panel > System.
  2. Click the Advanced tab, and then click Environment Variables.
  3. In the System variables list, click New.
  4. In the Variable name enter ORACLE_JDBC_DRIVER_FILE, and in the Variable value enter C:\Path_to_JDBC_driver\ojdbc8.jar.
  1. Open a shell window and enter the following environment variable declaration.
  2. export ORACLE_JDBC_DRIVER_FILE =/Path_to_JDBC_driver/ojdbc8.jar

Before you begin

This procedure requires that the following prerequisites are met:

  • The service is started.
  • The Java Database Connectivity (JDBC) driver is installed. See Hardware and software requirements for a supported driver version.
  • The TCP protocol is enabled for SQL Server.
  • The user who creates the database table must be a member in the sysadmin fixed server role, or an owner of the database (dbo).
  • The password you use for the JDBC connection cannot contain the open curly bracket ({) and semicolon (;) characters.
  • Ensure that your server security is in mixed mode. You can verify the mode by checking the server security. It should be set to SQL Server and Windows Authentication Mode.
  • Create an empty directory on your database server to be used as the data warehouse base folder. During the setup wizard, you will be asked to enter this directory.

Procedure

Set up the SQL Server database by using the sqlcmd command line tool, which is provided with the SQL Server installation. You can also use a visual tool, such as SQL Server Studio Management.

Important: If you install applications either on the same computer or distributed platforms, a separate database and a database user who is associated with that database must be created.

database

  1. Enter the following command to create a database for :

    CREATE DATABASE jts
    GO

  2. Create a user and password and change the ownership of the database by entering these commands:

    CREATE LOGIN jtsDBuser
    WITH PASSWORD = 'jtsDBpswd';
    USE jts;
    exec sp_changedbowner 'jtsDBuser'
    GO

  3. Change the collation of the databases:

    ALTER DATABASE jts COLLATE SQL_Latin1_General_CP437_CS_AS
    GO

  4. Change the row version system for the database:

    Note: Ensure that the connection to the database is open before running this command.

    ALTER DATABASE jts SET READ_COMMITTED_SNAPSHOT ON
    GO

database

  1. Create a file called createOauthMSSQL.sql. Refer to the following SQL example to create the database and tables for . You can use a different database name than oauth2db, but you must use schema OAuthDBSchema.

    Note that the values in the script file are examples and you should change them according to your usage and environment. For example, if the TOKENSTRING value of 2048 is too small, you can increase that by using a datatype of TOKENSTRING NVARCHAR(MAX) NOT NULL,.

    -- Manually create DATABASE using object explorer and provide name as OAUTH2DB2;

    USE OAUTH2DB2;
    GO

    CREATE SCHEMA OAUTHDBSCHEMA;
    GO

    ---- CREATE TABLES ----
    CREATE TABLE OAUTHDBSCHEMA.OAUTH20CACHE
    (
    LOOKUPKEY VARCHAR(256) NOT NULL,
    UNIQUEID VARCHAR(128) NOT NULL,
    COMPONENTID VARCHAR(256) NOT NULL,
    TYPE VARCHAR(64) NOT NULL,
    SUBTYPE VARCHAR(64),
    CREATEDAT BIGINT,
    LIFETIME INT,
    EXPIRES BIGINT,
    TOKENSTRING VARCHAR(2048) NOT NULL,
    CLIENTID VARCHAR(64) NOT NULL,
    USERNAME VARCHAR(64) NOT NULL,
    SCOPE VARCHAR(512) NOT NULL,
    REDIRECTURI VARCHAR(2048),
    STATEID VARCHAR(64) NOT NULL,
    EXTENDEDFIELDS NVARCHAR(2048) NOT NULL DEFAULT '{}'
    );
    GO

    CREATE TABLE OAUTHDBSCHEMA.OAUTH20CLIENTCONFIG
    (
    COMPONENTID VARCHAR(256) NOT NULL,
    CLIENTID VARCHAR(256) NOT NULL,
    CLIENTSECRET VARCHAR(256),
    DISPLAYNAME VARCHAR(256) NOT NULL,
    REDIRECTURI VARCHAR(2048),
    ENABLED INT,
    CLIENTMETADATA NVARCHAR(2048) NOT NULL DEFAULT '{}'
    );
    GO

    CREATE TABLE OAUTHDBSCHEMA.OAUTH20CONSENTCACHE (
    CLIENTID VARCHAR(256) NOT NULL,
    USERID VARCHAR(256),
    PROVIDERID VARCHAR(256) NOT NULL,
    SCOPE VARCHAR(1024) NOT NULL,
    EXPIRES BIGINT,
    EXTENDEDFIELDS NVARCHAR(2048) NOT NULL DEFAULT '{}'
    );
    GO

    ---- ADD CONSTRAINTS ----
    ALTER TABLE OAUTHDBSCHEMA.OAUTH20CACHE
    ADD CONSTRAINT PK_LOOKUPKEY PRIMARY KEY (LOOKUPKEY);
    GO

    ALTER TABLE OAUTHDBSCHEMA.OAUTH20CLIENTCONFIG
    ADD CONSTRAINT PK_COMPIDCLIENTID PRIMARY KEY (COMPONENTID,CLIENTID);
    GO

    ---- CREATE INDEXES ----
    CREATE INDEX OAUTH20CACHE_EXPIRES ON OAUTHDBSCHEMA.OAUTH20CACHE (EXPIRES ASC);
    GO

    ---- GRANT PRIVILEGES ----
    ---- UNCOMMENT THE FOLLOWING IF YOU USE AN ACCOUNT
    OTHER THAN ADMINISTRATOR FOR DB ACCESS ----

    -- Change dbuser to the account you want to use to access your database
    --GRANT ALL ON OAUTHDBSCHEMA.OAUTH20CACHE TO dbuser;
    --GRANT ALL ON OAUTHDBSCHEMA.OAUTH20CLIENTCONFIG TO dbuser;
    --GRANT ALL ON OAUTHDBSCHEMA.OAUTH20CONSENTCACHE TO dbuser;

    ---- END OF GRANT PRIVILIGES ----

  2. Open a sqlcmd command line tool and run the following script to create the database, tables, and indexes, and to grant privileges:

    createOauthMSSQL.sql
    GO

    The script will create a database called oauth2db, and then create tables in the OAuthDBSchema schema. The tables require a buffer pool that has a page size of at least 8K. The SQL script creates the necessary buffer pool and table spaces, but you can skip this if your buffer pools use page sizes of 8K or greater already.

  3. After creating the database tables, you must configure to use the tables. Go to C:\IBM\JazzAuthServer\wlp\usr\servers\jazzop/opt/IBM/JazzAuthServer/wlp/usr/servers/jazzop and open appConfig.xml for editing.
  4. Comment out the following Apache Derby database section:

    <dataSource id=OAuthFvtDataSource jndiName=jdbc/OAuth2DB>
    <jdbcDriver libraryRef=DerbyLib />
    <properties.derby.embedded
    databaseName=asDB
    createDatabase=create />
    </dataSource>

    <library id=DerbyLib>
    <fileset dir=${shared.config.dir}/lib/global includes=derby.jar />
    </library>

  5. Add the following section to configure a SQL database. You must customize this section to work with your specific SQL server:

    <dataSource id=OAUTH2DBDS jndiName=jdbc/OAUTH2DB>
    <jdbcDriver libraryRef=MSJDBCLib/>
    <properties.microsoft.sqlserver user=username password=Password databaseName=OAUTH2DB serverName=SQLDBServer portNumber=1433/>
    </dataSource>
    <library id=MSJDBCLib>
    <fileset dir=${shared.config.dir}/lib/global id=sqljdbc42 includes=sqljdbc42.jar/>
    </library>

    Ensure that you have the correct values for the following attributes:

    • For user, provide the name of the MS SQL Server user that is used to connect to the database.
    • For password, use the MS SQL Server user password.
    • For databaseName, use the database name you created in the previous step. If you used the sample script file, the database name is OAUTH2DB.
    • For portNumber, use the port number that the MS SQL Server instance is running on. The default port number is 1433.
    • For serverName, enter the host name of the MS SQL Server.

  6. In the oauthProvider section of the appConfig.xml file, update the databaseStore property so it specifies the MS SQL Server data source rather than the default Apache Derby data source. The databaseStore property should specify the name of the MS SQL Server data source, which in this example, is OAUTH2DBDS:

    <oauthProvider id=JazzOP
    httpsRequired=true
    autoAuthorize=true
    customLoginURL=/jazzop/form/login
    accessTokenLifetime=7201
    authorizationGrantLifetime=604801>
    <autoAuthorizeClient>client01</autoAuthorizeClient>
    <databaseStore dataSourceRef=OAUTH2DBDS />
    </oauthProvider>

  7. Save and close the appConfig.xml file.
  8. Copy the MS SQL Server sqljdbc42.jar JDBC drivers from your MS SQL Server server to this directory: C:\IBM\JazzAuthServer\wlp\usr\shared\config\lib\globalopt/IBM/JazzAuthServer/wlp/usr/shared/config/lib/global.

database

  1. Enter the following command to create a database for the application:

    CREATE DATABASE ccm
    GO

  2. Create a user and password and change the ownership of the database by entering these commands:

    CREATE LOGIN ccmDBuser
    WITH PASSWORD = 'ccmDBpswd';
    USE ccm;
    exec sp_changedbowner 'ccmDBuser'
    GO

  3. Change the collation of the databases:

    ALTER DATABASE ccm COLLATE SQL_Latin1_General_CP437_CS_AS
    GO

  4. Change the row version system for the database:

    Note: Ensure that the connection to the database is open before running this command.

    ALTER DATABASE ccm SET READ_COMMITTED_SNAPSHOT ON
    GO

database

  1. Enter the following command to create a database for the application:

    CREATE DATABASE relm
    GO

  2. Create a user and password and change the ownership of the database by entering these commands:

    CREATE LOGIN relmDBuser
    WITH PASSWORD = 'relmDBpswd';
    USE relm;
    exec sp_changedbowner 'relmDBuser'
    GO

  3. Change the collation of the databases:

    ALTER DATABASE relm COLLATE SQL_Latin1_General_CP437_CS_AS
    GO

  4. Change the row version system for the database:

    Note: Ensure that the connection to the database is open before running this command.

    ALTER DATABASE relm SET READ_COMMITTED_SNAPSHOT ON
    GO

database

  1. Enter the following command to create a database for the application:

    CREATE DATABASE qm
    GO

  2. Create a user and password and change the ownership of the database by entering these commands:

    CREATE LOGIN qmDBuser
    WITH PASSWORD = 'qmDBpswd';
    USE qm;
    exec sp_changedbowner 'qmDBuser'
    GO

  3. Change the collation of the databases:

    ALTER DATABASE qm COLLATE SQL_Latin1_General_CP437_CS_AS
    GO

  4. Change the row version system for the database:

    Note: Ensure that the connection to the database is open before running this command.

    ALTER DATABASE qm SET READ_COMMITTED_SNAPSHOT ON
    GO

database

  1. Enter the following command to create a database for the application:

    CREATE DATABASE rm
    GO

  2. Create a user and password and change the ownership of the database by entering these commands:

    CREATE LOGIN rmDBuser
    WITH PASSWORD = 'rmDBpswd';
    USE rm;
    exec sp_changedbowner 'rmDBuser'
    GO

  3. Change the collation of the databases:

    ALTER DATABASE rm COLLATE SQL_Latin1_General_CP437_CS_AS
    GO

  4. Change the row version system for the database:

    Note: Ensure that the connection to the database is open before running this command.

    ALTER DATABASE rm SET READ_COMMITTED_SNAPSHOT ON
    GO

database

  1. Enter the following command to create a database for the application:

    CREATE DATABASE dcc
    GO

  2. Create a user and password and change the ownership of the database by entering these commands:

    CREATE LOGIN dccDBuser
    WITH PASSWORD = 'dccDBpswd';
    USE dcc;
    exec sp_changedbowner 'dccDBuser'
    GO

  3. Change the collation of the databases:

    ALTER DATABASE dcc COLLATE SQL_Latin1_General_CP437_CS_AS
    GO

  4. Change the row version system for the database:

    Note: Ensure that the connection to the database is open before running this command.

    ALTER DATABASE dcc SET READ_COMMITTED_SNAPSHOT ON
    GO

database

  1. Enter the following command to create a database for the application:

    CREATE DATABASE lqe
    GO

  2. Create a user and password and change the ownership of the database by entering these commands:

    CREATE LOGIN lqeDBuser
    WITH PASSWORD = 'lqeDBpswd';
    USE lqe;
    exec sp_changedbowner 'lqeDBuser'
    GO

  3. Change the collation of the databases:

    ALTER DATABASE lqe COLLATE SQL_Latin1_General_CP437_CS_AS
    GO

  4. Change the row version system for the database:

    Note: Ensure that the connection to the database is open before running this command.

    ALTER DATABASE lqe SET READ_COMMITTED_SNAPSHOT ON
    GO

database

  1. Enter the following command to create a database for the application:

    CREATE DATABASE ldx
    GO

  2. Create a user and password and change the ownership of the database by entering these commands:

    CREATE LOGIN ldxDBuser
    WITH PASSWORD = 'ldxDBpswd';
    USE ldx;
    exec sp_changedbowner 'ldxDBuser'
    GO

  3. Change the collation of the databases:

    ALTER DATABASE ldx COLLATE SQL_Latin1_General_CP437_CS_AS
    GO

  4. Change the row version system for the database:

    Note: Ensure that the connection to the database is open before running this command.

    ALTER DATABASE ldx SET READ_COMMITTED_SNAPSHOT ON
    GO

database

  1. Enter the following command to create a database for the application:

    CREATE DATABASE gc
    GO

  2. Create a user and password and change the ownership of the database by entering these commands:

    CREATE LOGIN gcDBuser
    WITH PASSWORD = 'gcDBpswd';
    USE gc;
    exec sp_changedbowner 'gcDBuser'
    GO

  3. Change the collation of the databases:

    ALTER DATABASE gc COLLATE SQL_Latin1_General_CP437_CS_AS
    GO

  4. Change the row version system for the database:

    Note: Ensure that the connection to the database is open before running this command.

    ALTER DATABASE gc SET READ_COMMITTED_SNAPSHOT ON
    GO

Data Warehouse database

  1. Enter the following command to create a database for the data warehouse application:

    CREATE DATABASE dw
    GO

  2. Create a user and password and change the ownership of the database by entering these commands:

    CREATE LOGIN dwDBuser
    WITH PASSWORD = 'dwDBpswd';
    USE dw;
    exec sp_changedbowner 'dwDBuser'
    GO

  3. Change the collation of the databases:

    ALTER DATABASE dw COLLATE SQL_Latin1_General_CP1_CS_AS
    GO

  4. Change the row version system for the database:

    Note: Ensure that the connection to the database is open before running this command.

    ALTER DATABASE dw SET READ_COMMITTED_SNAPSHOT ON
    GO

Create an environment variable

Create an environment variable named SQLSERVER_JDBC_DRIVER_FILE and point to the JDBC driver. The location of the driver varies depending on your installation.

  1. Click Start > Control Panel > System.
  2. Click the Advanced tab, and then click Environment Variables.
  3. In the System variables list, click New.
  4. In the Variable name enter SQLSERVER_JDBC_DRIVER_FILE, and in the Variable value enter C:\Path_to_JDBC_driver\sqljdbc42.jar.
  1. Open a shell window.
  2. Enter the following environment variable declaration:

    SQLSERVER_JDBC_DRIVER_FILE =.:Path_to_JDBC_driver/sqljdbc42.jar

Enable database table partitioning

You can use the partitioning repotools command to partition a non-partitioned REPOSITORY.VERSIONREPOSITORY_VERSION<SchemaPrefix>_REPOSITORY.VERSIONRPSTR_VRSN table in a configuration-enabled system. It will partition by Range based on Item Types. Starting in version 6.0.6.1, database table partitioning was introduced to handle performance, availability, and scalability of large amount of data (millions of artifacts) in your repository. You must install an Enterprise edition of Db2Db2zDb2iOracleSQL Server database to take advantage of these features. Standard, Workgroup, Personal, or Express editions of the databas, or the default Apache Derby database do not support partitioning. The command fails if the underlying database does not support partitioning.

To enable database table partitioning, open a command window and enter the following commands:

cd /opt/IBM/QM_Server/server/
./repotools-qm.sh -partitioning teamserver.properties=conf/qm/teamserver.properties enable

cd C:\Program Files\IBM\QM_Server\server\
repotools-qm.bat -partitioning teamserver.properties=conf\qm\teamserver.properties enable

For details about the partitioning repotools command, see Repository tools command to partition a database table.

Install the Apache Tomcat server

Starting in version 6.0.1, Apache Tomcat is not provided as a default application server. For production environments, the preferred application servers are or . Apache Tomcat is an open-source tool that is not commercially supported. However, if you choose to use Apache Tomcat, complete the following steps to download and install version 7.0.59. If you are considering a complex deployment topology with Apache Tomcat, consult the Apache Tomcat documentation.

The following method copies the Tomcat files to the installation directory and the examples show Apache Tomcat installed in this location: Jazz_Install_Dir. If you install Tomcat in another location, change the installation path accordingly.

  1. Open a browser, go to the Apache Tomcat website, and download Apache Tomcat version 7.0.59.
  2. Extract the downloaded .zip file to the Jazz_Install_Dir/server\server directory.
  3. The extraction process creates a directory named apache-tomcat-7.0.59. Rename this directory to tomcat.
  4. Go to the Jazz_Install_Dir/server/webapps\server\webapps directory and copy all application WAR files to this location: Jazz_Install_Dir/server/tomcat/webapps\server\tomcat\webapps.

Configure Apache Tomcat

When you set up a new installation of to run on Apache Tomcat, you must update some of the default Tomcat configuration files before you start the application server.

Add the SessionCookiePath attribute

When all applications are installed in a single Apache Tomcat server, each application must use the same session cookie in order to have single sign-on and single sign-out. You can achieve this by adding the SessionCookiePath attribute to the context.xml file.

Note: If you are deploying applications in more than one Apache Tomcat server, do not use the session cookie attribute because it can cause problems with cross-server authentication.

  1. Go to the Jazz_Install_Dir/server/tomcat/conf\server\tomcat\conf directory and open the context.xml file for editing.
  2. Add the SessionCookiePath=/ to the opening tag of the <Context> element, so it looks like this:
  3. <Context sessionCookiePath=/>

Change the port numbers

By default, all Tomcat port numbers are in the 8000 range. In products, the default port numbers are in the 9000 range. If you want to change the default 8080 (HTTP) and 8443 ( HTTPS) port numbers, complete these steps:

  1. Go to the Jazz_Install_Dir/server/tomcat/conf\server\tomcat\conf directory and open the server.xml file for editing.
  2. Change all instances of port="8080" and redirectPort="8443" to port="9080" and redirectPort="9443".
  3. Save the file.

Create secure connections (SSL/TLS)

If you want to use secure (HTTPS) connections, you must create or obtain a security certificate for SSL/TLS. You can either generate a self-signed certificate or obtain one from a certificate authority. For more information, see Installing a security certificate and SSL/TLS Configuration HOW-TO (apache.tomcat.org).

In the following example, change my-ssl.keystore and my-ssl-password to the actual keystore file name and password. If you copy the .keystore file to TomcatHome, no path is required. Otherwise, provide a full path to the .keystore file.

After you create the .keystore file, make the following changes in the server.xml file:

  1. Locate the following connector and remove the <!-- --> comment tags from around the code snippet:
  2. <Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol"
    maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
    clientAuth="false" sslProtocol="TLS" />

  3. Edit the code snippet to look like the following example. Ensure that you use the correct .keystore file name and password. Also, if you changed the connector port, ensure that you use the correct one:
  4. <Connector SSLEnabled="true"
    URIEncoding="UTF-8"
    acceptCount="100"
    algorithm="${jazz.connector.algorithm}"
    ciphers="SSL_DHE_RSA_WITH_AES_128_CBC_SHA,SSL_DHE_DSS_WITH_AES_256_CBC_SHA,SSL_DHE_RSA_WITH_AES_256_CBC_SHA,SSL_DHE_RSA_WITH_AES_128_CBC_SHA256,SSL_DHE_DSS_WITH_AES_128_CBC_SHA256,SSL_DHE_RSA_WITH_AES_256_CBC_SHA256,SSL_DHE_RSA_WITH_AES_128_GCM_SHA256,SSL_DHE_DSS_WITH_AES_128_GCM_SHA256,SSL_ECDHE_RSA_WITH_AES_128_CBC_SHA,SSL_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,SSL_ECDHE_RSA_WITH_AES_256_CBC_SHA,SSL_ECDHE_RSA_WITH_AES_128_GCM_SHA256,SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,SSL_ECDHE_RSA_WITH_AES_256_GCM_SHA384,SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,SSL_ECDHE_RSA_WITH_AES_128_CBC_SHA256,SSL_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,SSL_ECDHE_RSA_WITH_AES_256_CBC_SHA384,SSL_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,SSL_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_DSS_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_DSS_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_256_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_DSS_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,SSL_RSA_WITH_3DES_EDE_CBC_SHA,SSL_RSA_WITH_AES_128_CBC_SHA,SSL_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_3DES_EDE_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA"
    clientAuth="false"
    connectionTimeout="20000"
    disableUploadTimeout="true"
    enableLookups="false"
    keystoreFile="my-ssl.keystore"
    keystorePass="my-ssl-password"
    maxHttpHeaderSize="8192"
    maxThreads="150"
    minSpareThreads="25"
    port="9443"
    protocol="HTTP/1.1"
    scheme="https"
    secure="true"
    sslEnabledProtocols="${jazz.connector.sslEnabledProtocols}"/>

  5. Locate the AJP 1.3 connector and define it as follow by adding the sslEnabledProtocols parameter. Ensure to use the correct redirect port.
  6. <Connector enableLookups="false"
    port="9009"
    protocol="AJP/1.3"
    redirectPort="9443"
    sslEnabledProtocols="${jazz.connector.sslEnabledProtocols}"/>

  7. Save the server.xml file.

Enable single sign-on

If you use Jazz Security Architecture single sign-on, Apache Tomcat does not authenticate users, so no configuration is required for the user registry.

If you install more than one application on the same Tomcat instance, complete these steps to enable Tomcat single sign-on:

  1. In the server.xml file, locate the following line and remove the comment tags from around it.
  2. <Valve className="org.apache.catalina.authenticator.SingleSignOn" />

Configure the user registry

Complete the following steps to update the Tomcat user registry.

Note: You must configure this section to be able to log on to the setup wizard for the first time by using the ADMIN user ID.

  1. In the server.xml file, locate the <Resource name="UserDatabase" auth="Container" line.
  2. Add the attribute readonly="false". The entire Resource code snippet should look like this:
  3. <Resource name="UserDatabase" auth="Container"
    type="org.apache.catalina.UserDatabase"
    description="User database that can be updated and saved"
    factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
    pathname="conf/tomcat-users.xml"
    readonly="false"/>

  4. In the server.xml file, locate the <Realm className="org.apache.catalina.realm.UserDatabaseRealm" line.
  5. Add the attributes digest="SHA-1" and digestEncoding="UTF-8":
  6. <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
    digest="SHA-1"
    digestEncoding="UTF-8"
    resourceName="UserDatabase"/>

Disable access logging

In previous releases of , access logging was disabled by default to improve performance. If you do not use access logging, insert comment tags around the following section in the server.xml file:

<!--
<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
prefix="localhost_access_log." suffix=".txt"
pattern="%h %l %u %t "%r" %s %b" />
-->

Define Jazz security roles

You must define the standard Jazz security roles and create an administrative user account. In previous releases, a predefined ADMIN user with the ADMIN password was used for the initial administrative login. Now, you can define any user name and password in the tomcat-users.xml file. To define Jazz security roles and create a default user, complete these steps:

  1. Go to Jazz_Install_Dir/server/tomcat/conf\server\tomcat\conf and open the tomcat-users.xml file for editing.
  2. Add the following code snippet to the <tomcat-users>:
  3. <tomcat-users>
    <role rolename="JazzUsers"/>
    <role rolename="JazzAdmins"/>
    <role rolename="JazzGuests"/>
    <role rolename="JazzProjectAdmins"/>
    <role rolename="manager-gui"/>
    <user username="ADMIN" password="ADMIN" roles="JazzUsers,JazzAdmins,JazzProjectAdmins"/>
    </tomcat-users>

    The password must be entered in clear text in the tomcat-users.xml file, and then encrypted by completing the following steps.

  4. Open a command window and enter these commands:

    cd Jazz_Install_Dir/server\server
    repotools-jts -convertTomcatUsers tomcatUsersPath=Jazz_Install_Dir/server/tomcat/conf/\server\tomcat\conf\tomcat-users.xml

  5. The repotools command creates a file called tomcat-users.xml.converted. Delete the original tomcat-users.xml file and rename tomcat-users.xml.converted to tomcat-users.xml.

Start the Apache Tomcat server

You are now ready to start the Apache Tomcat server.

  1. To start the server, open a command prompt and change to the Jazz_Install_Dir\server directory.
  2. Enter this command:

    server.startup.bat -tomcat

    Note: A separate Apache Tomcat console window opens. If you close this window, the server stops. Depending on your installation options, the server startup might take a few minutes. After the server is started, the startup time in millisecond is displayed in the Tomcat window. For example, a line like this might be displayed: Server startup in 203645 ms.

    Important: If the server is installed in the default Program Files directory, to be able to write to this directory, you must run the startup program as an administrator.

  3. Tip: To stop the server, you can enter server.shutdown.bat -tomcat

  1. To start the server, open a command shell and change to the Jazz_Install_Dir/server directory.
  2. Enter this command:

    ./server.startup -tomcat

    Note: A separate Apache Tomcat console window does not open. You can check the server startup progress by viewing the Jazz_Install_Dir/server/logs/jts.log file.

    After you access the server for the first time, the logs directory under Jazz_Install_Dir/server is created.

  3. Tip: To stop the server, you can enter ./server.shutdown -tomcat

Manage federated file-based user registry

Before you begin

  • Ensure that is already installed and running.

About this task

uses J2EE container managed authentication for login and system permissions. For application server to work, you must configure a realm with the application server. The file-based user registry is useful for testing or evaluation, because does not support importing users or mapping user roles. For the full application functionality, including viewing system user roles and importing users, supports an LDAP realm.

Configure the federated repositories

  1. In the WebSphere Integrated Solutions Console, click Security > Global security.
  2. Make sure Enable administrative security and Enable application security check boxes are selected.
  3. From the Available realm definitions select Federated repositories and click Configure.
  4. In the Primary administrative user name field, type the administrative ID.
  5. Under Server user identity, make sure Automatically generated server identity is selected. Click OK and then save.
  6. Set Federated repositories as the current realm definition by clicking Set as Current.
  7. Stop and restart the .

Setting up groups and users

To be able to run , you need to define groups and users in the repository and map them to Jazz groups. Before installing any applications, you must create the user groups.

  1. In the WebSphere Integrated Solutions Console, click Users and Groups > Manage Groups.
  2. Click Create and create the following group names:
    • JazzAdmins
    • JazzProjectAdmins
    • JazzUsers
    • JazzGuests
  3. In the Users and Groups section, click Manage Users.
  4. Click Create and enter a name in the User ID field to create a user in the JazzAdmins group.
  5. Click Group Membership and then click Search.
  6. Select JazzAdmins from the Available window and then click Add, to add JazzAdmins to the Mapped To window.
  7. Click Close and in the Create a User page fill in the remaining required fields. Click Create.
  8. Click Create Like and create other users and assign them to the appropriate Jazz group membership.

Start the server

You can now start the server.

  1. To start the server, open a command windowshell and enter the following commands:
  2. cd Jazz_Install_Dir\server
    server.startup.bat

    cd Jazz_Install_Dir/server
    ./server.startup

Set up the by using the Jython script

The clm_was_config.py script configures and sets up security options so that you can run applications in a WebSphere environment.

Before you begin

Ensure you have completed the following tasks:

Procedure

  1. If your is installed on a Windows platform, but you are using the Db2 for z/OS database server, open the Jazz_Install_Dir/server/was/clm_was_config.py for editing.
  2. Search for #createJVMCustomProperty(jvm, "DB2Z_JDBC", db2DriverPath, "") and delete the # sign at the beginning of the line to remove the comment.
  3. Add the file path to location of the Db2z JDBC driver. Note the forward slash. For example:

    createJVMCustomProperty(jvm, "DB2Z_JDBC", "/etc/jazz/server/db2z", "")

  4. To configure the Oracle JDBC driver location open the Jazz_Install_Dir/server/was/clm_was_config.py for editing.
  5. Search for #createJVMCustomProperty(jvm, "ORACLE_JDBC_DRIVER_FILE", oracleDriverPath, "") and delete the # sign at the beginning of the line to remove the comment.
  6. Add the absolute path to location of the Oracle JDBC driver. For example:

    createJVMCustomProperty(jvm, "ORACLE_JDBC_DRIVER_FILE", "C:\app\user\product\12.2.0\dbhome_1\jdbc\lib\ojdbc8.jar", "")

    createJVMCustomProperty(jvm, "ORACLE_JDBC_DRIVER_FILE", "/opt/app/user/product/12.2.0/dbhome_1/jdbc/lib/ojdbc8.jar", "")

  7. To configure the SQL Server JDBC driver location open the Jazz_Install_Dir/server/was/clm_was_config.py for editing.
  8. Search for #createJVMCustomProperty(jvm, "SQLSERVER_JDBC_DRIVER_FILE", sqlDriverPath, "") and delete the # sign at the beginning of the line to remove the comment.
  9. Add the absolute path to location of the SQL Server JDBC driver. For example:

    createJVMCustomProperty(jvm, "SQLSERVER_JDBC_DRIVER_FILE", "C:\MSSQL\jdbc\sqljdbc42.jar", "")

    createJVMCustomProperty(jvm, "SQLSERVER_JDBC_DRIVER_FILE", "/opt/mssql/jdbc/sqljdbc42.jar", "")

  10. Save and close the clm_was_config.py file.
  11. Open a command window as administrator and enter the following commands. Replace WAS_Profile_Dir with the directory where profile is installed. For example, C:\Program Files (x86)\IBM\WebSphere\AppServer\profiles\AppSrv01/opt/IBM/WebSphere/AppServer/profiles/AppSrv01:
  12. Note: On Windows platforms you must use forward slash in the paths for the location of the Jython script and the conf directory.

    cd WAS_Profile_Dir\bin
    wsadmin.bat -lang jython -user WAS_USER -password WAS_PASSWORD -f C:/Jazz_Install_Dir/server/was/clm_was_config.py C:/Jazz_Install_Dir/server/conf

    cd WAS_Profile_Dir/bin
    ./wsadmin.sh -lang jython -user WAS_USER -password WAS_PASSWORD -f /opt/Jazz_Install_Dir/server/was/clm_was_config.py /opt/Jazz_Install_Dir/server/conf

  13. For changes to take effect, restart the application server. Replace server1 with the name of your application server:
  14. cd WAS_Profile_Dir\bin
    stopServer.bat server1 -user WAS_USER -password WAS_PASSWORD
    startServer.bat server1

    cd WAS_Profile_Dir/bin
    ./stopServer.sh server1 -user WAS_USER -password WAS_PASSWORD
    ./startServer.sh server1

Set up the

Before you begin

Ensure you have completed the following tasks:

  • is already installed and running.
  • You have the WebSphere administrative user name and password.
  • Verify or update the level. For a list of supported versions and fix packs, see the Detailed System Requirements page.
  • On UNIX systems, ensure that the Open File Limit value is properly set. For more information, see Planning to install on UNIX and Linux systems.
  • The database is created. If you use the default Derby database for evaluation purposes, ensure the location to the database in the teamserver.properties file is an absolute path.

Procedure

  1. Open a browser and login to WebSphere Integrated Solutions Console at https://hostname.example.com:9043/ibm/console/logon.jsp.
  2. The Java 2 Security option must be turned off. If this option is turned on in , the web application will not start.
    1. Click Security > Global security.
    2. Under Java 2 security, clear the check box for Use Java 2 security to restrict application access to local resources.
    3. Ensure that the Enable administrative security and Enable application security check boxes are selected.
  3. To ensure that the LTPA cookies are secure, enable the Requires SSL setting:
    1. Click Security > Global security > Web and SIP security > Single sign-on(SSO).
    2. Click the Requires SSL check box.
    3. Also ensure that Set security cookies to HTTPOnly to help prevent cross-site scripting attacks is selected.
    4. Click OK and Save directly to the master configuration.
  4. Set the Restrict cookies to HTTPS sessions to ensure that the session cookies include the secure field. Enabling this feature restricts the exchange of cookies to HTTPS sessions:
    1. In WebSphere Integrated Solutions Console, click Server > Server Types > WebSphere application servers > server_name > Session management > Enable cookies.
    2. Select the Restrict cookies to HTTPS sessions check box.
  5. Also ensure that the Use available authentication data when an unprotected URI is accessed application server security setting is selected.
    1. Click Security > Global security > Web and SIP security > General settings.
    2. Click the Use available authentication data when an unprotected URI is accessed check box.
    3. Click OK and Save directly to the master configuration.
  6. Add the following session management custom property to avoid SESN0008E error message when a user logs out without terminating the session:
    1. Click Servers > Server Types > WebSphere application servers.
    2. Click server1 and then in the Container Settings section, click Session management.
    3. In the Additional Properties section, click Custom properties.
    4. Click New and enter the following information:
      • Name: InvalidateOnUnauthorizedSessionRequestException
      • Value: true
    5. Click Apply and save directly to the master configuration.
  7. To improve performance of the operating procedures, change the WebContainer thread pool size settings:
    1. Click Servers > Server Types > WebSphere application servers.
    2. Click server1 and then in the Additional Properties section, click Thread pools.
    3. In the Thread pools page, click WebContainer.
    4. Enter 200 in the Minimum Size and Maximum Size fields.
    5. Click OK and save directly to the master configuration.
  8. In version 9.0, the Contexts and Dependency Injection (CDI) 1.2 is enabled by default. If CDI is enabled, it might increase unnecessary performance overhead if the application is not using it. applications do not use CDI and to gain performance, you can disable CDI by setting some Java custom properties and manifest attributes. For detailed instructions, see this IBM Support troubleshooting document.
  9. requires several specific settings on the Java Virtual Machine in which it runs. To set these properties, click Servers > Server Types > WebSphere application servers > server1.
  10. Under Server Infrastructure, click Java and Process Management > Process definition.
  11. Under Additional Properties, click Java Virtual Machine.
  12. In the Generic JVM arguments field, type the following lines:

    -Xmx4g -Xms4g -Xmn1g
    -Xgcpolicy:gencon -Xnocompressedrefs

    -Xmx4g -Xms4g -Xmn1g
    -XX:MaxPermSize=768M -XX:ReservedCodeCacheSize=512M -XX:CodeCacheMinimumFreeSpace=2M

    -Xmx4g -Xms4g -Xmn1g
    -Xgcpolicy:gencon -Xcompressedrefs
    -Xgc:preferredHeapBase=0x100000000

    Tip: If you need more heap size, then you can use the following setting, replacing {N} with the amount of memory to be used and {N/4} with 1/4 of the total memory. For example, if -Xmx is set to 8g, -Xmn should be set to 2g.

    -Xmx{N} -Xms{N} -Xmn{N/4}

    For only: The -Xmn value should be 33% of the -Xms value. For example, if the -Xmx size is 4gb, the -Xmn should be 1365m. The following Deployment wiki document contains useful information about sizing and tuning: Sizing and tuning guide for . For only: If application pages become unresponsive as a result of memory issues, see this technote for troubleshooting.

  13. Click Apply, and then click Save directly to the master configuration.
  14. One of the custom properties you must add is JAZZ_HOME, a system property that specifies where to find certain configuration files. This property uses a URL rather than a simple path, so specify the value as a file-style URL: file:///file_path. Under Java Virtual Machine > Additional Properties, click Custom properties. You must use three forward slashes (///) after file:.

    In a distributed environment, when you are using a separate application server for each web application, you must add these custom properties for each instance of the .

  15. Click New, enter JAZZ_HOME in the Name field, and enter file:///Jazz_Install_Dir/server/conf in the Value field. Substitute Jazz_Install_Dir with the location of installation directory. For example, file:///C:/PROGRA~1/IBM/JazzTeamServer/server/conf if the server is installed in /opt/IBM, enter file:////opt/IBM/JazzTeamServer/server/conf.

    To avoid problems, do not use spaces in file paths. You can use double quotation marks to enclose the path.

  16. Click OK.
  17. Repeat the above steps and add these custom properties:
    • Name: lqe.config.location Value: file:///Jazz_Install_Dir/server/conf/lqe
    • Name: ldx.config.location Value: file:///Jazz_Install_Dir/server/conf/ldx
    • Name: java.awt.headless Value: true
    • Name: org.eclipse.emf.ecore.plugin.EcorePlugin.doNotLoadResourcesPlugin Value: true
    • Name: ORACLE_JDBC_DRIVER_FILE Value: Absolute_path_to_the_JDBC_driver/ojdbc8.jar

      Note: The path to the JDBC driver must be an absolute path. Do not use URL path (file:///). For more information about Oracle Java Database Connectivity (JDBC) connections, see Set up the database step.

    • Name: SQLSERVER_JDBC_DRIVER_FILE Value: Absolute_path_to_the_JDBC_driver/sqljdbc42.jar

      Note: The path to the JDBC driver must be an absolute path. Do not use URL path (file:///). For more information about SQL Server JDBC connections, see Set up the database step.

    • Name: log4j.configuration Value: file:///Jazz_Install_Dir/server/conf/startup_log4j.properties

      The settings that the startup_log4j.properties file contains are used at the early stages in the startup process to pass messages to the SystemOut.log file. After the early stages, each Jazz application switches to using the application-specific settings from the Jazz_Install_Dir/server/conf/app_context/log4j.properties file.

  18. Click Save directly to the master configuration.
  19. In the WebSphere Integrated Solutions Console navigation pane, expand Environment and click Shared libraries.
  20. In the Scope list, select Node=MachineNameNode01, Server=server1 and click New.
  21. Enter the shared library name JRS Shared Library, add a description, and set the classpath to: JRS_install_dir/server/conf/rs/\server\conf\rs\WAS_SharedLibrary. For example: C:\Progra~1\IBM\JazzTeamServer\server\conf\rs\WAS_SharedLibrary/opt/IBM/JazzTeamServer/server/conf/rs/WAS_SharedLibrary
  22. Under Class Loading, select the Use an isolated class loader for this shared library check box, click Apply, and then click Save.
  23. For changes to take effect, restart the application server.

Configure the for SCIM

To use the System for Cross-domain Identity Management (SCIM) standard, you must install Jazz Authorization server and configure LDAP user registry. For more information, see Configuring the for the SCIM feature.

Deploy web application (WAR files) by using the Jython script

You can use clm_deploy.py or clm_deploy_distributed.py in a distributed environment to deploy application WAR files.

Before you begin

Ensure that , , and applications are installed prior to running the script.

Complete the following steps to map the security roles to your LDAP groups. Note that the groups must be setup on the LDAP server prior to completing this mapping.

  1. Open the config.py script in a text editor for editing.
  2. Modify the values under RoleMapping to map the security roles to your LDAP groups.
  3. The following example shows the role mapping for the application. Replace the values with the values from your LDAP server. You might need to contact your LDAP Administrator to obtain this information:

    Note: Ensure that the JazzAdmins, JazzUsers, JazzGuests, and JazzProjectAdmins security groups do not have any spaces in their names.

    RoleMapping = {
    'jts' : {
    'JazzAdmins' : {
    'mappedUser': None,
    'mappedGroup': "cn=JazzAdmins,cn=members,o=ldap.server.com",
    'AllowAccessToEveryone':'No',
    'AllowAccessToAllAuthenticatedUsers':'No'
    },
    'JazzUsers' : {
    'mappedUser': None,
    'mappedGroup': "cn=JazzUsers,cn=members,o=ldap.server.com",
    'AllowAccessToEveryone':'No',
    'AllowAccessToAllAuthenticatedUsers':'No'
    },
    'JazzGuests' : {
    'mappedUser': None,
    'mappedGroup': "cn=JazzGuests,cn=members,o=ldap.server.com",
    'AllowAccessToEveryone':'No',
    'AllowAccessToAllAuthenticatedUsers':'No'
    },
    'JazzProjectAdmins' : {
    'mappedUser': None,
    'mappedGroup': "cn=JazzProjectAdmins,cn=members,o=ldap.server.com",
    'AllowAccessToEveryone':'No',
    'AllowAccessToAllAuthenticatedUsers':'No'
    },

    RoleMapping = {
    'ccm' : {
    'JazzAdmins' : {
    'mappedUser': None,
    'mappedGroup': "cn=JazzAdmins,cn=members,o=ldap.server.com",
    'AllowAccessToEveryone':'No',
    'AllowAccessToAllAuthenticatedUsers':'No'
    },
    'JazzUsers' : {
    'mappedUser': None,
    'mappedGroup': "cn=JazzUsers,cn=members,o=ldap.server.com",
    'AllowAccessToEveryone':'No',
    'AllowAccessToAllAuthenticatedUsers':'No'
    },
    'JazzGuests' : {
    'mappedUser': None,
    'mappedGroup': "cn=JazzGuests,cn=members,o=ldap.server.com",
    'AllowAccessToEveryone':'No',
    'AllowAccessToAllAuthenticatedUsers':'No'
    },
    'JazzProjectAdmins' : {
    'mappedUser': None,
    'mappedGroup': "cn=JazzProjectAdmins,cn=members,o=ldap.server.com",
    'AllowAccessToEveryone':'No',
    'AllowAccessToAllAuthenticatedUsers':'No'
    },

    RoleMapping = {
    'qm' : {
    'JazzAdmins' : {
    'mappedUser': None,
    'mappedGroup': "cn=JazzAdmins,cn=members,o=ldap.server.com",
    'AllowAccessToEveryone':'No',
    'AllowAccessToAllAuthenticatedUsers':'No'
    },
    'JazzUsers' : {
    'mappedUser': None,
    'mappedGroup': "cn=JazzUsers,cn=members,o=ldap.server.com",
    'AllowAccessToEveryone':'No',
    'AllowAccessToAllAuthenticatedUsers':'No'
    },
    'JazzGuests' : {
    'mappedUser': None,
    'mappedGroup': "cn=JazzGuests,cn=members,o=ldap.server.com",
    'AllowAccessToEveryone':'No',
    'AllowAccessToAllAuthenticatedUsers':'No'
    },
    'JazzProjectAdmins' : {
    'mappedUser': None,
    'mappedGroup': "cn=JazzProjectAdmins,cn=members,o=ldap.server.com",
    'AllowAccessToEveryone':'No',
    'AllowAccessToAllAuthenticatedUsers':'No'
    },

  4. Save and close the file.

About this task

The clm_deploy.py script installs all application WAR files that are available in the webapps directory into a single node.

The clm_deploy_distributed.py script can be used to install any application WAR files that are available in the webapps directory, if you specify them in your command argument as a comma-separated list.

Note: The web archive applications must have a .war extension.

Procedure

To deploy applications on a single , complete this step:

  1. Open a command window as administrator and enter the following commands. Replace nodeName and server1 with your node name and server name:
  2. Note: On Windows platforms you must use forward slash in the paths for the location of the Jython script and the webapps directory.

    cd WAS_Profile_Dir\bin
    wsadmin.bat -lang jython -user WAS_USER -password WAS_PASSWORD -f C:/Jazz_Install_Dir/server/was/clm_deploy.py nodeName server1 C:/Jazz_Install_Dir/server/webapps -config C:/Jazz_Install_Dir/server/was

    cd WAS_Profile_Dir/bin
    ./wsadmin.sh -lang jython -user WAS_USER -password WAS_PASSWORD -f /opt/Jazz_Install_Dir/server/was/clm_deploy.py nodeName server1 /opt/Jazz_Install_Dir/server/webapps -config /opt/Jazz_Install_Dir/server/was

To deploy applications in a distributed environment, complete this step:

  1. Open a command window as administrator and enter the following commands. Replace nodeName and server1 with your node name and server name. Enter the application names that you want to deploy separated by commas. For example:
  2. Note: On Windows platforms you must use forward slash in the paths for the location of the Jython script and the webapps directory.

    cd WAS_Profile_Dir\bin
    wsadmin.bat -lang jython -user WAS_USER -password WAS_PASSWORD -f C:/Jazz_Install_Dir/server/was/clm_deploy_distributed.py nodeName server1 C:/Jazz_Install_Dir/server/webapps jts,ccm,clmhelp -config C:/Jazz_Install_Dir/server/was

    cd WAS_Profile_Dir/bin
    ./wsadmin.sh -lang jython -user WAS_USER -password WAS_PASSWORD -f /opt/Jazz_Install_Dir/server/was/clm_deploy_distributed.py nodeName server1 /opt/Jazz_Install_Dir/server/webapps jts,ccm,clmhelp -config /opt/Jazz_Install_Dir/server/was

To start the deployed applications, restart the application server. Replace server1 with the name of your application server:

cd WAS_Profile_Dir\bin
stopServer.bat server1 -user WAS_USER -password WAS_PASSWORD
startServer.bat server1

cd WAS_Profile_Dir/bin
./stopServer.sh server1 -user WAS_USER -password WAS_PASSWORD
./startServer.sh server1

Deploy web applications (WAR files)

Before you begin

  • Make sure is installed and started.
  • You have access to the .WAR files.
  • If is installed in a non-root environment, the user who deploys the applications must have read and write access to the installation directory and all sub-directories.
  • Uninstall default applications (DefaultApplication, ivtApp, and query) if they are installed with the profile. and applications do not use these applications and for security and performance reasons they can be removed.

Procedure

  1. Open a browser and login to WebSphere Integrated Solutions Console at https://hostname.example.com:9043/ibm/console/logon.jsp.
  2. Click Applications > New Application > New Enterprise Application.
  3. On the Path to the new application page, select Remote file system and browse for the application.war file. Click Next.

    Depending on the applications that you installed, the following web applications might be available for deployment:

    • jts.war
    • clmhelp.war
    • ccm.war
    • relm.war
    • iotp.war
    • qm.war
    • rm.war
    • converter.war
    • dcc.war
    • lqe.war
    • ldx.war
    • rs.war
    • gc.war

  4. Select Fast Path, and then click Next.
  5. For the and modules, expand Choose to generate default bindings and mappings, and then select the Generate Default Bindings check box.
  6. On the Map modules to servers page, select the check box next to ldx to specify the target scope on the server for the ldx module.
  7. On the Map modules to servers page, select the check box next to lqe to specify the target scope on the server for the lqe module.
  8. Click Next to accept all default options until you reach the Map context roots for web modules page.
  9. In the Map context roots for web modules, set the following Context Root for applications:
    • to /jts
    • IBM Knowledge Center to /clmhelp
    • to /ccm
    • to /relm
    • IBM Continuous Engineering Connector for IoT to /iotp
    • to /qm
    • to /rm
    • Converter application to /converter
    • to /dcc
    • to /rs
    • to /lqe
    • to /ldx
    • Global Configuration to /gc
  10. Click Finish.
  11. Verify that your application was installed correctly and then click Save directly to the master configuration.

Update the JAX-RS settings ( 9.x only)

If you are using version 9.x, you must update the JAX-RS settings before you can use the CE Connector for IoT application:

  1. Log in to the administrative console.
  2. Select Servers from the navigation panel and click Server Types.
  3. Under Server Types, select WebSphere application servers.
  4. Click the link for the server that you want to configure. The default server name is server1.
  5. On the Configuration tab, expand the Container Services content list under the Container Settings section and click the Default JAX-RS Settings link.
  6. On this page, you can view the supported JAX-RS providers. From the JAX-RS provider list, select JAX-RS provider version 1.1.
  7. Save the settings and restart the application server.

Configure the CE Connector for IoT

To configure the CE Connector for IoT, see Configuring the connector.

Map security roles to a user or repository group

The following applications must have the same authentication methods for their users and use the same security group mapping.

  • jts_war
  • ccm_war
  • qm_war

Procedure

  1. In WebSphere Integrated Solutions Console click Applications > Application Types > WebSphere enterprise applications.
  2. For , click the jts_war application to open it for editing.
  3. For , click the ccm_war application to open it for editing.
  4. For , click the rqm_war application to open it for editing.
  5. In the Detail Properties section, click Security role to user/group mapping.
  6. Select a specific repository group, such as JazzAdmins or JazzUsers, and click Map groups.

    These repository groups are associated with every Jazz implementation and must be mapped to a particular group that contains the authorized users. If you are using LDAP, these groups must be set up on the LDAP server prior to completing this mapping. If you are mapping these repository groups to individual users, select the repository group and click Map Users.

  7. Enter a search string to return your users or group names. Click Search to run the query.
  8. From the list of available users or groups that is returned, select the particular user or group and move it to the Selected column.
  9. Click OK to map the users or groups to the Jazz repository groups.
  10. Save the changes.

Note: If in the future there will be changes to the LDAP configuration level, you must remap the security roles to the user or repository group for JTS and other installed applications.

Configure the application

  1. In WebSphere Integrated Solutions Console click Applications > Application Types > WebSphere enterprise applications.
  2. Click lqe_war to open it and then click Manage Modules.
  3. Click lqe, locate the Class loader order field and select Classes loaded with local class loader first (parent last).
  4. Click OK and save your changes.
  5. Go back to the lqe_war application and click Class loading and update detection.
  6. On the Class loader page, select Classes loaded with local class loader first (parent last).
  7. Click Apply and Save directly to the master configuration.

Configure the application

  1. In WebSphere Integrated Solutions Console click Applications > Application Types > WebSphere enterprise applications.
  2. Click ldx_war to open it and then click Manage Modules.
  3. Click ldx, locate the Class loader order field and select Classes loaded with local class loader first (parent last).
  4. Click OK and save your changes.
  5. Go back to the ldx_war application and click Class loading and update detection.
  6. On the Class loader page, select Classes loaded with local class loader first (parent last).
  7. Click Apply and Save directly to the master configuration.

Configure the application

  1. In WebSphere Integrated Solutions Console click Applications > Application Types > WebSphere enterprise applications.
  2. On the Enterprise Applications page, in the list of resources, click rs_war.
  3. On the Configuration page, in the References section, click Shared library references.
  4. Select the rs_war check box and click Reference shared libraries.
  5. In the Available list, select JRS Shared Library and click the right arrow.
  6. Click OK. Click OK again and then click Save.
  7. In the list of resources, click rs_war.
  8. On the Configuration page, under Detail Properties, click Class loading and update detection.
  9. In the Class loader order group, ensure that Classes loaded with local class loader first (parent last) is selected. Click Apply and then click Save.

Start the applications

  1. In WebSphere Integrated Solutions Console click Applications > Application Types > WebSphere enterprise applications.
  2. Select the check box next to these applications, and then click Start:
    • jts_war
    • clmhelp_war
    • ccm_war
    • relm_war
    • iotp_war
    • qm_war
    • rm_war
    • converter_war
    • dcc_war
    • lqe_war
    • ldx_war
    • rs_war
    • gc_war

    A green arrow should appear that indicates the application is successfully started.

    Note: The Converter application is supported only on Windows and Linux. For installation instructions on other unsupported platforms, see the Delegated Configuration section of Converter Application Configuration and Troubleshooting Guide.

Configure the server on IBM i

For information about configuring the server, see Configuring the server on IBM i.

Manage users by configuring LDAP

Configure your to use LDAP registry to authenticate users.

Before you begin

If you use LDAP for user management and you enable the option to not use case-sensitive user management, make sure that is also configured to allow user management that is not case sensitive. To configure the login property after you start the server, on the Advanced Properties page of the Administrative web interface, modify the Use case insensitive user ID matching property.

Procedures

  1. Open a web browser and log in to the WebSphere Integrated Solutions Console.
  2. In the left menu, expand Security and then click Global security.
  3. Ensure Enable administrative security and Enable application security check boxes are selected.
  4. Under User account repository, select Standalone LDAP registry from the Available realm definitions list and then click Configure.
  5. In the Primary administrative user name, enter your administrative user ID.
  6. Under Server user identity, ensure that Automatically generated server identity is selected.
  7. Under LDAP server, select a type of LDAP server that you use in your organization. The following LDAP types are available:
    • IBM Tivoli Directory Server
    • Microsoft Active Directory
  8. In the Host field, provide the URL for your LDAP server.
  9. Enter the port number of your LDAP server in the Port field. The default port number is 389.
  10. Enter a base distinguish name (DN) of your directory service.
  11. In the Search timeout field, enter 120 seconds.
  12. Click Test connection to ensure you can successfully connect to your LDAP server, and then click Apply and save the changes.
  13. Under Additional Properties, click Advanced Lightweight Directory Access Protocol (LDAP) user registry settings.
  14. Enter the values for general properties that your LDAP administrator provided to configure .
  15. Click Apply and save the changes and then click OK to go back to the Global Security page.
  16. Set Standalone LDAP registry as the current realm definition by clicking Set as Current.
  17. Stop and restart .
  18. After restarts, validate the changes by logging on to the Integrated Solutions Console.

Run the setup wizard

After installing the applications, databases, and starting the and other applications, you can log in to the (jts/setup) page and run the setup wizard to configure the servers.

The "Express setup" is a simplified version of the wizard that lets you set up the default Derby database and Liberty Basic User Registry. The wizard will detect and set up the applications that you have just installed.

Procedure

  1. Point your web browser to the following address: https://hostname.example.com:9443/jts/setup.
  2. Type ADMIN (case-sensitive) in both the User ID and Password fields. Click Log In.
  3. On the Welcome page, select Express Setup. Click Next.
  4. On the Configure Public URI page, provide a Public URI that is of the form https://[fully qualified hostname]:9443/jts and select the check box to confirm that you have read and understood the recommendations on this page. Click Test Connection. After the test is successful, click Next.

    Important: A [fully qualified hostname] is the host name along with the DNS domain reference of the machine on which the is installed. An example of a good [fully qualified hostname] is hostname.example.com. Examples of bad [fully qualified hostname] are localhost or an IP address.

  5. On the Create Administrative User page, create an administrative user by providing a user ID, full name, password, and email address. This new administrative user ID will replace the default ADMIN user. Click Next.
  6. The Setup Progress page is open and displays each step of the progress. A green check mark denotes that the step was successful. After setting up the application is 100% complete, click Next.
  7. On the Assign Licenses page, if necessary, click Activate Trial for the required licenses. This opens the License Agreement page for a selected license. Read and accept the license agreement, and then click Finish.
  8. After activating the required licenses, click Finish. This opens the Server Administration page where you can perform additional administrative and project management tasks such as, managing the server, users, and licenses. For more information, see Administering servers.

The Custom setup wizard guides you through setting up your database, configuring email settings, configuring the user registry, and registering applications.

Before you begin

  • Ensure is installed and running.
  • For new installations, if you do not want to use the default port numbers, you must change them before you use the setup wizard. For more information, see Changing the port numbers for the application server.
  • Databases must be created before running the setup wizard. Make sure that you performed the Set up the database.
  • In a single server topology, the wizard detects and allows you to set up the applications that you have just installed. In a distributed environment, first install and start and all applications on each individual server, and note the applications discovery URL. Then, run the setup wizard on the server where is installed and, on the Register Applications page, provide the discovery URL of the applications that are installed on the other servers.

Procedure

  1. In a web browser, go to the following address: https://hostname.example.com:9443/jts/setup.
  2. In both the User ID and Password fields, type ADMIN (case-sensitive). Click Log In.
  3. Log in with your WebSphere Administrative ID that is a member of JazzAdmins user group.
  4. Log in as an LDAP registered user who has JazzAdmins privileges. Note that the LDAP user or group must be mapped to the repository group.
  5. On the Welcome page, ensure that Custom Setup is selected, and then click Next.
  6. Read the information on the Introduction page and click Next.
  7. On the Configure Public URI page, provide a public URI that is of the form https://fully qualified hostname:9443/jts and select the check box to confirm that you have read and understood the recommendations on this page. This URI is the public URI of the . If you are setting up the application on its own server, you must provide the public URI of the HAProxy server and not the CCM server. Click Test Connection. After the test is successful, click Next.
  8. On the Configure Database page, provide information to set up a connection to the database.
    • Database Vendor: Select Db2OracleSQL ServerDb2 for z/OS.
    • Connection Type: Select J2EE if you manage your database connection by the J2EE container in . You must provide the J2EE data source name. A JDBC connection type does not involve the container, and connects to the database directly and manages the connection pooling.
    • For a JDBC connection type, provide JDBC location and JDBC password. For Db2 for z/OS, provide the schema prefix and the Db2z database name in the appropriate fields.
    • Click Test Connection. After the connection is successful, click Create Tables. This step might take a few minutes. After the database tables are created successfully, click Next to continue.
  9. On the Enable E-mail Notification page, enable or disable email notifications. If you choose to enable notifications, you must provide information about your email server and test the connection to the email server. After making your selections and testing the connection, click Next.
  10. On the Register Applications page, the wizard detects the applications that were installed on the same server with . It might take a moment for each application to be discovered and added to the list of applications to register. The wizard does not detect applications that are installed on a different server. You can register other applications with , but clustering is only enabled for the application.

    Note: If you selected the option during the installation and installed your , in the step 1 of the setup wizard, you must configure the Authorization Server. Provide the Authorization Server URL, administrative user ID, and administrative password, and then click Test Connection.

    Ensure that your browser is not blocking pop-up windows. The uses a pop-up window for logging in.

    Restriction: When Jazz Security Architecture SSO is enabled, the browser add-on is not supported.

    1. Optional: If you do not want to register an application, click the X icon to the far right of the application name. Typically, you should register all applications; however, you might not want to register one or more applications in the following situations:
      • You downloaded and deployed all applications, but you do not intend to use all of them.
      • You will not have licenses for an application.
      • You are configuring this application as a stand-alone floating or token license server.
    2. Verify the application type and discovery URL of the installed applications. The wizard creates default pre-authorized functional user IDs for each application.
    3. Optional: To add an application installed on a different server, click Add Application and provide the application name and discovery URL. After you provide the application name and discovery URL, the Functional User ID will be generated and entered automatically. The functional user ID will be used to run tasks in the background. The functional user ID does not have to exist in the external user registry or as a user in the repository; if the user doesn't exist in the repository, it will be automatically created.
    4. Click Register Applications. The wizard creates friend relationships, registers the applications, and generates a consumer key and secret for each application.
    5. After registration is successful, click Next to configure the registered applications. Notice that the menu on the left now lists the registered application and sub-steps.
  11. On the Setup User Registry page, provide the following information:
    1. Select the type of user registry you will use.
      1. Liberty Basic Registry: Select this option if your application server is the default Liberty profile and you do not have an LDAP server. This is the simplest configuration option and allows the to manage users and groups for you with the Liberty profile user database.
      2. If you select an LDAP user registry, you must provide information to configure the connection between the and your LDAP server. You might need to request this information from your LDAP administrator.
      3. Select SCIM option if your organization centrally manages users and groups but the user registry is not directly accessible from . If you have configured your Authorization Server as the SCIM provider, choose this option and the will use the JAS SCIM provider to access user and group information.
      4. Select this option if your application server is Tomcat and you don't have an LDAP server. This is the simplest configuration option and allows the to manage users and groups for you with the Tomcat user database.
      5. If you select Non-LDAP External Registry, enter the same user ID that you used to log into the setup wizard. This is the administrative user ID.
      6. For on z/OS with RACF security or on IBM i with local OS authentication, select non-LDAP external registry.
      7. In step 2 of the wizard, you might need to request the following information from your SCIM administrator to configure to use to act as the user registry provider.
        • A URL of SCIM provider
        • User name and password to access the SCIM provider
        • Base user distinguished name
        • Base group distinguished name
        • Jazz groups to registry group mapping
      8. In step 2 of the wizard, you might need to request the following information from your LDAP administrator to configure to use an LDAP server to act as the user registry provider.
        • The LDAP registry location
        • User name and password to access the LDAP registry
        • Base user distinguished name
        • User property names mapping
        • Base group distinguished name
        • Jazz to LDAP group mapping
        • Group name property
        • Group member property
      9. Click Save LDAP Config Files.
      10. Tip: Two files are modified with this operation: ldapUserRegistry.xml and application.xml. To see the name and location of the generated XML files, click show details in the message window.

        Tip: The Tomcat configuration files are saved with this operation. To see the name and location of the generated XML files, click show details in the message window.

      11. After the setup wizard is complete, continue with the next step to configure the LDAP setup.
    2. Provide the user ID, name, password, and email Address of the user who will have administrative access to the .
    3. Optionally disable the default ADMIN access by selecting the appropriate check box.
    4. Depending on the installed applications, under , , , , select the Client Access Licenses (CALs) you want the administrative user to have. You can assign only one type of role-based CAL to the administrator. For example, you can assign the administrator only a - Developer CAL or a - Stakeholder CAL, but not both. The same rule applies to other applications. If you have installed the trial licenses, you must accept the terms of a license before you can assign it to the administrative user. To activate a license, click Activate Trial; then, in the Client Access License Agreement window, click I accept the terms in the license agreement and click Finish.
    5. Tip: For information about how licenses can provide different levels of access to the application capabilities, see Client access license management overview.

  12. After you make your selections, click Next.
  13. On the Configure Data Warehouse page provide information to set up a connection to the data warehouse. The data warehouse is a database used for reporting and analytics. By default, the application is pre-configured to use the Derby database that is included with the application and configuration is not required. Click Next to continue. If you have a database prepared on an enterprise database server such as Db2OracleSQL Server, you must configure the to use that database. Select the database vendor and the connection type from the list and enter the connection properties.
    1. In the Configure Data Warehouse Database Vendor and Connection Type section, select your database vendor and the connection type for that database vendor. The default is to use the included, preconfigured Apache Derby database with a JDBC connection. You can either keep this default or choose a different database vendor and connection type.

      Note: If you select J2EE for connection type, you must also set the resultSetHoldability property to 1 in . By default, this property is set to 2. If you do not set this property to 1, some of the data warehouse collection jobs might fail. For more information about resultSetHoldability, see your documentation.

    2. In the Configure Data Warehouse Database Connection Properties section, type the connection properties to connect to your database. The required values vary depending on your database vendor and connection type.
    3. In the Database Table Space Folder field, type the path to an existing directory on the database server where the table space will be created, and specify any additional advanced server properties for your database:
      • Temporary Table Space
      • ODS Table Space
      • ODS Index Table Space
      • Star Table Space
      • Star Index Table Space
      • Custom Report Database User
    4. If you used Common Reporting or and you want to use the existing data warehouse database as the data warehouse for your products, provide the information to connect to that existing database. You are prompted to add tables to your Common Reporting database.
    5. To verify that the server can successfully communicate with the database by using the connection information that you provided, click Test Connection.
    6. If you did not previously use a repository tools (repotools) command to create the database tables, you might see a warning that the database exists but that it does not contain any tables. To create the tables, click Create tables. You might have to wait several minutes for the command to finish.
    7. Click Next.
  14. If you do not want to configure the data warehouse at this time, select the I do not wish to configure the data warehouse at this time check box.

    If you do not configure the data warehouse, your applications will be functional but you will not be storing any reporting data and most reports will not work.

  15. For each application, configure the database and the data warehouse by following the same steps.
  16. On the Finalize Application page, click Finalize Application Setup.
  17. On the (/lqe) and (/ldx) Configure Database pages, click Save JDBC Connection to save the database connection properties. On the Configure Backups page for these applications, you can enable a weekly backup that runs every Sunday at 2:00 AM. The schedule time can be changed through web UI after the setup is complete. You must also provide a path to an existing backup directory on the server. When done, click Save Configuration.
  18. On the Setup page, click Connect to data sources. detects the data sources and makes the connection. If you want to import reports provided by your data sources, click Import ready-to-use reports.
  19. On the Summary page, click Finish to access the Administration page where you can perform administration tasks such as managing the server, users, and licenses. For more information, see Administering servers.

Manage users by configuring LDAP

Configure your server to use LDAP registry to authenticate users.

Before you begin

If you use LDAP for user management and you enable the option to not use case-sensitive user management, ensure that is also configured to allow user management that is not case sensitive. To configure the login property, on the Advanced Properties page of the Administrative web interface, modify the Use case insensitive user ID matching property.

Procedures

  1. Go to Jazz_Install_Dir/server/liberty/servers/clm\server\liberty\servers\clm and open the server.xml file for editing.
  2. To use the LDAP user registry, comment out <include location="conf/basicUserRegistry.xml"> and uncomment <!--include location="conf/ldapUserRegistry.xml"-->.
  3. Save and close the server.xml file.
  4. Open Jazz_Install_Dir/server/liberty/servers/clm/conf/\server\liberty\servers\clm\conf\ldapUserRegistry.xml for editing and examine the ldapRegistry values to ensure that they match your organization's LDAP configuration. By default, the ldapUserRegistry.xml file uses IBM Tivoli Directory Server as ldapType and idsFilters:

    <ldapRegistry
      id="sample_ldap" realm="SampleLdapIDSRealm" ignoreCase="true"
      host="localhost" port="389"
      baseDN="ou=people,dc=jazz,dc=net"
      ldapType="IBM Tivoli Directory Server">
      <idsFilters
        userFilter="(&amp;(uid=%v)(objectclass=inetOrgPerson))"
        groupFilter="(&amp;(cn=%v)(|(objectclass=groupOfNames)(objectclass=posixGroup)))"
        userIdMap="*:uid"
        groupIdMap="*:cn"
        groupMemberIdMap="ibm-allGroups:member;ibm-allGroups:uniqueMember">
      </idsFilters>
    </ldapRegistry>

    The following example is for Microsoft Active Directory LDAP type:

    ldapType="Microsoft Active Directory LDAP"
      <activedFilters
        userFilter="(&amp;(sAMAccountName=%v)(objectcategory=user))"
        groupFilter="(&amp;(cn=%v)(objectcategory=group))"
        userIdMap="user:sAMAccountName"
        groupIdMap="*:cn"
        groupMemberIdMap="memberof:member">
      </activedFilters>

  5. Save and close ldapUserRegistry.xml.
  6. Open Jazz_Install_Dir/server/liberty/servers/clm/conf/\server\liberty\servers\clm\conf\application.xml and examine each .war file group name and ensure it matches your organization group names. The following applications rely on container authentication: , , , and . Other applications delegate authentication to .
  7. Restart the server.
  8. In a web browser, go to https://host.example.com:9443/jts/setup, where host.example.com is the fully qualified host name for your server.
  9. Test the connection by logging in to your server with a user ID that is in your LDAP external registry.

What to do next:

In a distributed environment, carry out these steps to configure the Liberty files on all servers.

Configure your Tomcat server to use LDAP registry to authenticate users.

About this task

During the setup wizard if you clicked the Save LDAP Config Files button, the Tomcat configuration files are saved in the Tomcat_Home directory. Use the following procedure to setup the Tomcat configuration files to use LDAP.

Before you begin

If you use LDAP for user management and you enable the option to not use case-sensitive user management, make sure that is also configured to allow user management that is not case sensitive. To configure the login property, on the Advanced Properties page of the Administrative web interface, modify the Use case insensitive user ID matching property.

Procedures

  1. Go to Jazz_Install_Dir/server/tomcat/conf\server\tomcat\conf and rename server.xml file to server.xml.old.
  2. Rename server-LDAPxxxx.xml file to server.xml.
  3. Go to Jazz_Install_Dir/server/tomcat/webapps/jts/WEB-INF\server\tomcat\webapps\jts\WEB-INF and rename web.xml file to web.xml.old.
  4. Rename web-LDAPxxxx.xml file to web.xml.
  5. Go to Jazz_Install_Dir/server/tomcat/webapps/ccm/WEB-INF\server\tomcat\webapps\ccm\WEB-INF and rename web.xml file to web.xml.old.
  6. Rename web-LDAPxxxx.xml file to web.xml.
  7. Go to Jazz_Install_Dir/server/tomcat/webapps/qm/WEB-INF\server\tomcat\webapps\qm\WEB-INF and rename web.xml file to web.xml.old.
  8. Rename web-LDAPxxxx.xml file to web.xml.
  9. Restart the Tomcat server.
  10. Open a web browser window and go to https://host.example.com:9443/jts/setup, where host.example.com is the fully qualified host name for your server.
  11. Test the connection by logging on to your server by using a user ID that is in your LDAP external registry.

What to do next:

In a distributed environment, carry out these steps to configure the Tomcat files on all servers.

Configure the server by using the setup repotools command

You can run the setup command from a command-line to set up databases, configure email settings, configure the user registry, and register any applications you have just installed.

The setup command is a repository tools command that allows you to set up a and associated applications without using the setup wizard. The command may be run in interactive mode to help capture the response file needed to drive future automated installations. See Repository tools command to configure the server for the explanation of each parameter that you can use with the command.

Before you begin

Prior to running the setup command, you must have installed the and any applications, created your databases, and deployed and started the applications on your application server.

Note: If you are using a Derby database, before running the setup command, ensure that the location of the database and data warehouse in the Jazz_Install_Dir/server/conf/jts/teamserver.propertiesJazz_Install_Dir\server\conf\jts\teamserver.properties file is an absolute path. For example: com.ibm.team.repository.db.jdbc.location=Jazz_Install_Dir/conf/jts/derby/repositoryDB and com.ibm.team.datawarehouse.db.jdbc.location=Jazz_Install_Dir/conf/jts/derby/warehouseDB.

Procedure

  1. Open a command window and enter the following commands:

    cd Jazz_Install_Dir\server
    repotools-jts.bat -setup repositoryURL=https://qualified.hostname.com:9443/jts adminUserID=ADMINWAS_ADMIN_ID adminPassword=ADMINWAS_ADMIN_PASSWORD

    cd Jazz_Install_Dir/server
    ./repotools-jts.sh -setup repositoryURL=https://qualified.hostname.com:9443/jts adminUserID=ADMINWAS_ADMIN_ID adminPassword=ADMINWAS_ADMIN_PASSWORD

  2. Configure a public URI and then hit Enter.
  3. Read the warning and confirm your public URI:

    I understand that once the Public URI is set, it cannot be modified except with additional administrative commands, which can result in broken links from other applications that do not support changing URLs.

    Choose Confirm Public URI:

    [1] I understand
    [2] Cancel and exit setup - default

  4. At the Configure Database step, enter a number to choose a DB connection type:
  5. [1] JDBC - Default
    [2] J2EE

  6. Enter a number to choose a database vendor:
  7. [1] Derby - default
    [2] Db2
    [3] SQL Server
    [4] Db2 for z/OS
    [5] Db2i
    [6] Derby Net
    [7] Oracle

  8. Enter a location for the JDBC database. If the location contains password, use the value {password} instead of the actual password.
  9. For example:

    conf/jts/derby/repositoryDB

    //localhost:50000/JTS:user=db2admin;password={password};

    thin:jtsDBuser/{password}@localhost:1521/DB

    //localhost:1433;databaseName=jts;user=jtsDBuser;password={password};

    //ipAddress:ipPort/location:user=jtsDBuser;password={password};

  10. Enter Y to enable the email notification. Enter N to skip.
  11. At the Configure User Registry step, enter a number corresponding to one of the following entries:
  12. [1] LIBERTY
    [2] LDAP
    [3] Non-LDAP External Registry

  13. Enter the following information to create an administrative user.
    • User ID
    • Password (The password is not displayed on the screen.)
    • Re-Type Password
    • Your full name
    • Email address

    If you selected LDAP, the logged in user information is imported. If you selected Non-LDAP, the password is not required.

  14. After you created the administrative user, you can disable the default ADMIN user. Choose one these options:
  15. [1] Disable - default
    [2] Do Not Disable

  16. Next, depending on installed applications, you will be asked to register local applications. Enter Y to confirm and enter the instance name (context root) and discovery URL for each application.
  17. Note: A local application is an application that is installed under the same application server as and its details can be discovered. A non-local application is either installed in a distributed environment or not installed in the same application server as and its details must be provided by the user.

    The following table displays the applications that can be registered with with their context root and discovery URL:

    applications with their default context root and discovery URL
    Application Name Context root Discovery URL

    /ccm

    /rqm

    /rm

    /relm

    /gc

    /ldx

    /rs

    /dcc

    /lqe

    https://server.example.org:9443/ccm/scr

    https://server.example.org:9443/rqm/scr

    https://server.example.org:9443/rm/scr

    https://server.example.org:9443/relm/scr

    https://server.example.org:9443/gc/scr

    https://server.example.org:9443/ldx/scr

    https://server.example.org:9443/rs/scr

    https://server.example.org:9443/dcc/scr

    https://server.example.org:9443/lqe/scr

  18. At the Assign Licenses step, for each installed application select the appropriate Client Access License(s) to be assigned to your user. You can assign additional license keys in the Admin UI as needed.
  19. At the Configure Data Warehouse data base step, choose a DB connection type and database vendor. For the database network server port, assign a unique port number within the hosting server. The default port number is 1527.
  20. The Setup step creates known data sources and imports the ready-to-use reports so that is ready to use.

    If the data warehouse has not been set up or a Derby database is being used then no password is required. Otherwise, enter a password for data warehouse. This step might take a few minutes.

  21. At the end of the setup, you should see message on the screen that the setup completed successfully.

Configure the server by using the setup repotools command in express mode

The setup command is a repository tools command that allows you to set up a and associated applications without using the setup wizard. You can run the setup command from a command-line in express mode to set up all default values.

When you run the setup command in express mode, you are only prompted to enter information needed to create the administrative user and assign licenses to that user. All other tasks are automated using the default values. If you need to change a default value such as the Public URI entry, you can add the repositoryURL parameter in the command line. You can also use a response file that has all the recorded information needed to run the setup in express mode. See Repository tools command to configure the server for the explanation of each parameter that you can use with the command.

Procedure

  1. Open a command window and enter the following commands:

    cd Jazz_Install_Dir\server
    repotools-jts.bat -setup repositoryURL=https://qualified.hostname.com:9443/jts express=yes

    cd Jazz_Install_Dir/server
    ./repotools-jts.sh -setup repositoryURL=https://qualified.hostname.com:9443/jts express=yes

  2. When prompted, enter the following information to create an administrative user.
    • User ID
    • Password (The password is not displayed on the screen.)
    • Re-Type Password
    • Your full name
    • Email address
  3. At the Assign Licenses step, for each installed application select the appropriate Client Access License(s) to be assigned to your user. You can assign additional license keys in the Admin UI as needed.

Distributed Cache Microservice (DCM) for clustered applications

For () applications that support clustering such as , the distributed data is managed by a standalone web application called Distributed Cache Microservice.

The Distributed Cache Microservice (DCM) is a small Java application that consists of a main JAR file, distributedCache.jar, the distributedCache.cfg file for configuration properties, and required dependencies in the jarlib directory. The microservice provides a centralized management and storage location for distributed data for clustered () applications. The DCM is required for cluster operation; if the DCM is not accessible, then all clustered applications will be in a 'wait' state until the DCM is back online. The DCM itself is not an application and may have different configuration requirements from the applications.

Setup considerations

The DCM must be installed and run on a machine that is accessible by all nodes of the clustered application. By default, the microservice is installed on the (JTS) machine under the server/clustering/cache directory and is started as part of the JTS startup sequence or on demand when a clustered application asks for it. If the Distributed Cache Microservice URL advanced property setting has not been set, a clustered application calls JTS to discover the status of the microservice. Then JTS attempts to locate a running DCM process and starts the DCM if it is not running. Often in production environments, JTS is a back end server behind a proxy, such as IBM HTTP Server, or for performance reasons, it is installed on a dedicated server. In these cases, the DCM must be started manually, and the clustered application Distributed Cache Microservice URL service property must be set.

Note: For optimal performance, the DCM should be moved to a dedicated server independent from .

To move DCM or to reconfigure the URL:

  1. Determine the URL to access the DCM. Note the following important factors about the DCM URL:
    • The URL can start with http or https depending on whether SSL is enabled in the distributedCache.cfg file.
    • If the server is fronted by a proxy, use the proxy URL.
    • If the port is masked, then the port should be omitted from the URL. Otherwise, 10001 is the default port which is also configurable in the distributedCache.cfg file.
    • A context path at the end of the URL is not required.
  2. URL example:

    https://myproxy.company.com/
    https://myserver.company.com:10001/

    Note: If you do the following step before the cluster is turned on, the changes will be propagated to other nodes when you replicate the CCM nodes.

  3. Log in to the application administrative UI and go to Application > Advanced Properties.
  4. Search for Distributed Cache Microservice URL and in the Current Value field, enter the URL of the DCM server.
  5. Scroll to the top of the page and click Save.
  6. Go to the server where the application is installed and copy the server/clustering/cache directory and all subdirectories to a location on the new DCM host. Note that the DCM host must have JVM 1.7 or higher installed.
  7. Open the server/clustering/cache/distributedCache.cfg file for editing.
  8. Under the [AuthServer] section, add the DCM URL in as_trusted_url so it can be properly registered with . For example:
  9. as_trusted_url = $S{AuthServer.as_trusted_url, https://myserver.company.com:10001/}

Configuration properties checklist

Depending on your installation topology, the following configuration properties in the distributedCache.cfg file can be set.

Running DCM in secure mode

By default, Distributed Cache Microservice runs in SSL mode. This is controlled by the useSsl property in the [REST] section. Additional SSL related configurations are specified in the [REST-SslContextFactory] section. Ensure to specify the correct file name and path in keyStorePath.

Configuration samples

For your reference, here are some sample configurations. Note that these samples point out only a few important parameters and not the entire configurations.

Sample 1, DCM is:

#===========================================
# REST settings
#===========================================
[REST]

port = $E{CACHE_PORT, 10001}

stylesheet = styles/devops.css

saveConfigAction = RESTART_SERVER

useSsl = true

authType = OIDC

#===========================================
# AuthServer settings
#===========================================
[AuthServer]

auth_url = $S{AuthServer.auth_url, https://JAS_HOST:9643/oidc/endpoint/jazzop}

client_id = dcm

client_name = Distributed Cache Microservice

as_admin_id = $S{AuthServer.as_admin_id, ADMIN}

as_admin_pass = $S{AuthServer.as_admin_pass, ADMIN}

as_trusted_url = $S{AuthServer.as_trusted_url, https://JTS_HOST:10001}

#============================================
# LDAP UserRegistry settings.
#============================================
[UserRegistry]

base_group_DN = dc=jazz,dc=domain

group_name_property = cn

group_roles_mapping = {"LDAPJazzAdmins":"JazzProjectAdmins,JazzAdmins,JazzDWAdmins","LDAPJazzUsers":"JazzUsers,JazzDWAdmins"}

Sample 2, DCM is:

#============================================
# REST settings
#============================================
[REST]

port = $E{CACHE_PORT, 10001}

stylesheet = styles/devops.css

saveConfigAction = RESTART_SERVER

useSsl = true

authType = OIDC

#============================================
# AuthServer settings
#============================================
[AuthServer]

auth_url = $S{AuthServer.auth_url, https://JAS_HOST:9643/oidc/endpoint/jazzop}

client_id = dcm

client_name = Distributed Cache Microservice

as_admin_id = $S{AuthServer.as_admin_id, ADMIN}

as_admin_pass = $S{AuthServer.as_admin_pass, ADMIN}

as_trusted_url = $S{AuthServer.as_trusted_url, https://IHS_HOST}

IHS environments

If the is fronted by a proxy server, it must be configured to forward DCM requests to the appropriate host and port where the DCM is running. By default, an cluster expects the DCM to be running on the same host as , configured securely on port 10001.

To modify an IHS configuration, make changes to the following files:

a) httpd.conf - Add the following entry to listen on the default DCM port (10001). The default DCM port can be changed in the distributedCache.cfg. Note that the following change is only required if you plan to have the port as part of the DCM URL. If you plan to mask the DCM port from its URL, then no change is required in the httpd.conf file.

Listen 10001
<VirtualHost *:10001>
SSLEnable
SSLServerCert <IHS server cert alias>
</VirtualHost>

b) plugin-cfg.xml - Add the following entry to forward requests on port 10001 to the appropriate DCM server. Note that the DCM only requires /jsa and /dcm context roots to be forwarded.

<ServerCluster CloneSeparatorChange="false" GetDWLMTable="false" IgnoreAffinityRequests="true" LoadBalance="Round Robin" Name="microservice_Cluster" PostBufferSize="64" PostSizeLimit="-1" RemoveSpecialHeaders="true" RetryInterval="60">
<Server ConnectTimeout="0" ExtendedHandshake="false" MaxConnections="-1" Name="microservice" ServerIOTimeout="9000" WaitForContinue="false">
<Transport Hostname="<JTS_HOSTNAME>" Port="10001" Protocol="https">
<Property Name="keyring" Value="<File Path of keystore file (kdb)>"/>
<Property Name="stashfile" Value="<File Path of stash file file (sth)>"/>
</Transport>
</Server>
</ServerCluster>

<UriGroup Name="microservice_Cluster_URIs">
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/jsa/*"/>
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/dcm/*"/>
</UriGroup>

<Route ServerCluster="microservice_Cluster" UriGroup="microservice_Cluster_URIs" VirtualHostGroup="default_host"/>

c) Update the keystore database files to add an entry for the DCM certificate based on the keystore updates to the plugin-cfg.xml file.

Running the Distributed Cache Microservice

All the required files and scripts to start and stop the microservice are in the server/clustering/cache directory. To run the microservice, you must have a JVM version 1.7 or later installed. You can start the microservice by using the included script, or you can start it by using the following command:

java –Xms2G –Xmx3G -jar distributedCache.jar

You can change the values of JVM Xms and Xmx arguments in the command as per your requirements.

Note:

Starting the microservice:

To start the microservice, open a command windowshell and enter the following commands:

cd Path_To_DCM_Folder
start distributedCache.start.bat JRE_Bin_Path

cd PATH_To_DCM_Folder
./distributedCache.start.sh JRE_Bin_Path > /dev/null &

Where:

Path_To_DCM_Folder is where the Distributed Cache Microservice is installed and JRE_Bin_Path is the location of the JRE/Bin folder. The JRE_Bin_Path is optional. If it's not specified, the system considers that DCM is running from its default location and uses the JRE that is provided by the application.

Stopping the microservice:

To stop the microservice, open a command windowshell and enter the following commands:

cd Path_To_DCM_Folder
distributedCache.stop.bat JRE_Bin_Path

cd Path_To_DCM_Folder
./distributedCache.stop.sh JRE_Bin_Path

Where:

Unregistering Distributed Cache Microservice from

Jazz Authentication Server (JAS) is used to authenticate the Distributed Cache Microservice. To register the microservice, several parameters are configured in the distributedCache.cfg file under the AuthServer and UserRegistry sections as explained in the previous section. The DCM will be registered to the JAS automatically after it is started for the first time. After the DCM is registered with the JAS, the following properties are updated in the distributedCache.cfg file: client_secret and registration_completed = true. By default, DCM will be registered on JAS with client_id as dcm. If you need to update the JAS registration for DCM, you can delete the existing JAS registration and registering DCM again with JAS:

  1. Stop the Distributed Cache Microservice.
  2. Edit the distributedCache.cfg file.
    1. Reset client_secret to the default value.

      client_secret = $S{AuthServer.client_secret}

    2. Remove or comment out the registration_completed = true property.
    3. Review the other properties mentioned in the [AuthServer] and [UserRegistry] sections in configuration file and update them accordingly if needed.
  3. Unregister DCM from by using the rmclient utility provided by JAS:
  4. cd JAS_Install_Dir\cli
    rmclient.bat -a AUTH_SERVER_URL -u ADMIN:ADMIN dcm

    cd JAS_Install_Dir/cli
    ./rmclient -a AUTH_SERVER_URL -u ADMIN:ADMIN dcm

    Where AUTH_SERVER_URL is the auth_url specified in the configuration file. The ADMIN:ADMIN parameter is the administrative user credentials, consisting of a user ID and password separated by a colon. And dcm is the Authorization Server client ID for the microservice registartion.

  5. When you start the DCM, it will re-register itself with by using the updated properties.

Replicate the CCM nodes

After you complete the setup and configuration of a single node, you can transform it into a cluster by replicating the nodes.

I. Add Message Broker URL to the Advanced Properties

  1. Log in to the server on the first node.
  2. Click Application and, under Configuration click Advanced Properties.
  3. Search for com.ibm.team.repository.service.mqtt.internal.MqttService and click Edit in the title bar.
  4. In the Current Value field for MQTT Broker address, enter the IP address or host name of the MQTT Broker (), followed by the port number that you specified when you configured the endpoint in .
  5. To save the changes, click Preview.

II. Add the cluster information to the server.startup script

  1. Log in to the server that you set up to use as your first node and stop the Change and Configuratopm Management application.
  2. Go to the CCM_Install_Dir/server directory and open server.startup for editing, and add the following lines:

    JAVA_OPTS="$JAVA_OPTS -Dcom.ibm.team.repository.cluster.nodeId="ccm1""
    JAVA_OPTS="$JAVA_OPTS -Dcom.ibm.team.repository.service.internal.db.allowConcurrentAccess=true"
    JAVA_OPTS="$JAVA_OPTS -Dretry.count=0"
    JAVA_OPTS="$JAVA_OPTS -Dretry.wait=10"

    Replace ccm1 with the name or ID of the node. This name must be unique among all the nodes. Later on when you copy the settings to other nodes, you must change this value on all nodes, for example, ccm2, ccm3, and so on.

  3. Save and close the server.startup file.

III. Adding nodes to the client registration

When you registered your application, you used the HAProxy URL, so the does not have host names for the specific nodes. After you add a new node to your cluster, you must also add it to the client registration.

Note: When you add your second node, you must also add the first node's hostname to the registration.

  1. Go to the directory where you installed your applications and copy all files under the clustering directory to the computer where is installed. Ensure to keep the directory structure.

    The following files are included in the clustering directory:

    • addNodeReg.sh
    • JASConfig.params
    • addNodeReg.bat
    • addNodeReg.ps1
    • JASConfig.params
  2. On Linux systems run chmod 755 with the script file to make it executable.
  3. Edit the JASConfig.params file to add your administrator credentials and the path to installation directory.
  4. Run addNodeReg.shaddNodeReg.bat with the client ID and local node URL as a parameters.
  5. Client ID: The client ID of the clustered CCM application registered on . To obtain the client ID open the CCM teamserver.properties file and look for the com.ibm.team.repository.servlet.sso_clientId property.

    Local node URL: Is the fully qualified host name and port number of the computer where CCM application is installed. Note that this is not the public URL of the CCM application that was used during application registration. This host name is also used in the HAProxy config file in the backend section.

    ./addNodeReg.shaddNodeReg.bat client ID https://CCM_Hostname:Port/appContext

    Note: Ensure to run the addNodeReg script on the first node that you used for the initial setup.

IV. Replicate to all nodes

You can replicate the CCM application on all nodes in two ways. You can install the CCM application on all other nodes and only copy the teamserver.properties and server.startup files from the first node to the other nodes. Alternatively, you can copy the entire installation directory from the first node to the other nodes. Do not forget to change the node IDs in the server.startup file on all nodes so that they all have unique IDs.

V. Update the HAProxy configuration

Open the HAProxy configuration file and verify that it lists the host names of your actual CCM nodes and that the number of lines matches the number of nodes. Edit the configuration file as needed, and restart the HAProxy service.

VI. Start the nodes

Start CCM server on every node. Check the HAProxy console to ensure all back-end servers are online.

Add replicas later

Complete the following steps to add more CCM replicas after your clustered environment is set up.

  1. Stop one of the CCM nodes.
  2. Copy the teamserver.properties and server.startup files to the new CCM installation directory on the new node.
  3. Edit the server.startup file and enter a unique node ID.
  4. Add an entry for the new node to the list of back-end servers in the HAProxy configuration file and restart the HAProxy server.
  5. If the new node is not registered with , run the addNodeReg script to register the new node.
  6. Start the server on the new node.

Troubleshooting the cluster

Synchronizing all applications with

After completing the custom setup, you might see the following diagnostic failure message for one or more applications:

Application: the discovery resource at https://JTS_HOST:9443/ccm/rootservices for "/ccm" has different OAuth domains than the entry does.

OAuth domains from the discovery resource: [https://JTS_HOST:9443/ccm] Application OAuth domains: []

This error might be caused by an incomplete synchronization of applications from the repository tools (repotools) commands. To fix the issue, complete the following steps to manually synchronize the applications:

  1. First, obtain the application ID that you need to synchronize with . Open a command shellwindow and enter the following commands:

    cd Jazz_Install_Dir/\server
    ./repotools-jtsrepotools-jts -listFriends repositoryURL=https://JTS_HOST:9443/jts adminUserId=adminUserId adminPassword=adminPassword

  2. Obtain the application ID from the previous step and enter the following command:

    ./repotools-jtsrepotools-jts -synchFriend repositoryURL=https://JTS_HOST:9443/jts adminUserId=adminUserId adminPassword=adminPassword friendId=FriendID_From_PreviousStep

  3. After the repotools commands are successfully completed, return to the diagnostic page and run the diagnostics to ensure no more errors occur.

Accepting all "Content" for requests through proxy

If you installed IBM HTTP Server or another similar proxy server in front of the clustered environment, you must ensure that it is enabled to accept the content (payload) from all HTTP requests such as GET, PUT, POST, and so on. If this capability is not enabled, you might receive HTTP 400 Bad request errors in the proxy server because some of the HTTP GET requests are sent with a payload and rejected by the proxy.

To avoid such errors, in the proxy server's plugin-cfg.xml file, set AcceptAllContent="true".

Discarding HAProxy messages in the log files

The number of requests between CCM cluster members and can quickly increase and fill the disk space. You can modify the rsyslog config file so that certain HAProxy messages are discarded while logging the rest. To do this, add a tilde (~) to the end of the line that you want to discard. Example:

:msg, regex, "/map/" ~
local2.* /var/log/haproxy.log
& stop

Activate and enable configuration management

For detailed instructions about activating configuration management and enabling project areas including a link to obtain an activation key, see Getting started for application administrators.

Related links

This Jazz.net article also provides useful information about configuration management.

Install to use as an MQTT broker for the

Note: Installation of is not supported on Windows platforms.

provides secure, rapid, bidirectional messaging for the Internet of Things (IoT) and mobile environments. is a high performance MQTT broker.

I. Installing the non-Dockerized version of

Procedure

To install a non-Dockerized version of , follow these steps:

  1. Download the required packages for the latest 2.0 from ibm.com.

    Note: An IBMid is required to access these files. If you do not have an IBMid, you will be prompted to create one before you can download .

  2. Follow the instructions in the documentation to install the non-Dockerized (RPM) version.

II. Logging in to the Web UI

About this task

You can use the URL http://server:Port to connect to the Web UI. This task uses https://10.10.2.149:9087/ to connect to the Web UI. To use this URL, your Web UI container must be running on the host with IP address 10.10.2.149.

You must accept a certificate and server certificate before you can start using the Web UI. You must change both of these certificates if you move from a non-production to a production environment.

Procedure

  1. Open a browser and connect to the Web UI by entering the following URL: 10.10.2.149:9087
  2. Accept the Web UI certificate so that you can view the login page.
  3. Log in and accept the server certificate in one of the following ways:
    • If you are using Internet Explorer 11, complete the following steps to log in and accept the server certificate:
      1. At the login prompt, type the default ID and password (admin/admin) and click Log in.
      2. After you are logged in, follow the browser prompts to accept the certificate. The Common configuration and customization tasks section of the Web UI home page is displayed.
    • If you are using Firefox or Google Chrome, complete the following steps to log in and accept the server certificate:
      1. At the login prompt, type the default ID and password (admin/admin) and click Log in. The Cannot connect to the server error is displayed.
      2. Click Click here in the message text. An error page is displayed that indicates that you need to accept the certificate.
      3. Follow the browser prompts to accept the certificate. The About page is displayed in a new browser window.
      4. Return to the Web UI page. If the error is still displayed, refresh the page. The Common configuration and customization tasks section of the Web UI home page is displayed.
      5. Note: To prevent repeatedly having to accept certificates, you can replace the default certificate with your own appropriately signed certificate. For information about specifying your own certificate, see Changing the Web UI security certificate.

III. Configuring

uses organizational configuration objects called hubs to define configuration policies.

Procedure

  1. After logging in to the Web UI by following the procedure in the previous task, create a new hub and then create and assign a connection policy, messaging policy and endpoint.
  2. Create a new connection policy. Provide a name and a description. Enter a client ID and select MQTT for protocol. Under Specify the resources that an MQTT client is permitted to consume, select Allow Clients with Durable Subscriptions and Allow Persistent Messages check boxes.
  3. Go to the Message Policy tab and create a new topic policy. Provide a name and a description for the new topic policy. Enter a client ID and select MQTT for the protocol. In the Topic field enter an asterisk (*) and, under Authority, select both the Publish and Subscribe check boxes. Under Subscriber Settings, ensure that you enter 10000 for the Max Messages value and select Discard Old Messages for the Max Messages Behavior value.
  4. Finally, create a new endpoint. Provide a name and a description. In the Port field, specify the port that the application uses to connect to publish and subscribe to messages. Later, you will add this port to the server.startup file. Select MQTT as the protocol. Set the Max Message Size value to 4096. Under Connection Policies and Messaging Policies, associate the connection policy and messaging policy (topic policy) that you created in the previous steps.

IV. Configuring the MQTT broker URI

After you installed and configured , you must add the MQTT broker URI in the Advanced Properties section of the administrative Web UI:

Procedure

  1. Open a browser and log in to the administrative Web UI where the application is installed. For example, https://hostname.example.com:9443/gc/admin.
  2. Click Application > Advanced Properties.
  3. Search for Global Configurations.
  4. In the com.ibm.team.gc.service.internal.GcApiPropertiesService section, add the MQTT broker URI in the provided field.
  5. Set the Use MQTT for contribution cache property to true.
  6. Scroll up the page and click Save.
  7. Restart the server for the changes to take effect.
  8. You must perform these steps on all GCM instances. Ensure that you use the same MQTT broker URI.

To learn about other configuration settings for multiple GCM instances, see Configuring multiple GCM instances.

Collecting data with

After you install and start the server, you can use to collect data from the registered applications and load them into the data warehouse. For detailed instructions, see Collecting data with the .

Install the client for Eclipse IDE

After installing and setting up the server, you can install the Eclipse client to connect to the server. To install the client for Eclipse IDE by using IBM Installation Manager, see Installing the Eclipse client by using Installation Manager.

Configuring Kerberos single-sign-on authentication

To configure Kerberos server and client single-sign-on authentication, see Configuring Kerberos single-sign-on authentication.